LocalCan

Máy chủ MCP

Chạy máy chủ Model Context Protocol của LocalCan và kết nối nó vào MCP host của bạn, kèm tài liệu tham khảo đầy đủ về các công cụ và tùy chọn.

localcan mcp chạy một máy chủ Model Context Protocol qua stdio. Một MCP host (Claude Code, Codex, Cursor, Claude Desktop và các ứng dụng khác) khởi chạy nó và gọi các công cụ của LocalCan để đọc lưu lượng đã thu thập, quản lý Public URL (tunnel) và xuất bản Snapshot. LocalCan phải đang chạy thì các công cụ mới trả về dữ liệu, vì vậy hãy mở ứng dụng desktop hoặc chạy localcan start -d trước.

Công cụ

Máy chủ cung cấp hai mươi công cụ. Đọc hoạt động ngay khi cài đặt. Mười một công cụ thay đổi dữ liệu cần quyền ghi, mặc định bị tắt (xem các tùy chọn bên dưới). Tạo hoặc thêm Public URL cần giấy phép đang hoạt động. Xuất bản Snapshot và bảo vệ URL bằng mật khẩu cần gói đăng ký, vì vậy giấy phép vĩnh viễn sẽ bị từ chối dù vẫn có thể mở Public URL. Khi chưa có giấy phép, các công cụ bị giới hạn trả về thông báo kích hoạt rõ ràng, trong khi tạm dừng, tiếp tục và xóa URL hiện có vẫn hoạt động.

Lưu lượng:

Công cụ	Chức năng	Tham số
get_status	Báo cáo việc thu thập có đang bật không và lượng lưu lượng đã được đệm.	không có
enable_capture	Bật thu thập. Thu thập mặc định bị tắt và được đặt lại khi daemon khởi động lại.	không có
list_traffic	Liệt kê các trao đổi gần đây, mới nhất trước.	last (mặc định 20), host chuỗi con, project id, method, status (mã chính xác hoặc một lớp như 5xx)
get_exchange	Trả về một trao đổi theo id.	id bắt buộc (id đầy đủ hoặc bất kỳ tiền tố duy nhất nào), format một trong markdown, curl, http, har, json (mặc định markdown), include_response (mặc định true)

Một trao đổi là yêu cầu LocalCan đã chuyển tiếp đến backend của bạn, không phải bản sao từng byte của yêu cầu gốc từ client. Xem Traffic để biết mô hình dữ liệu.

Public URL:

Công cụ	Chức năng	Tham số
list_services	Liệt kê các dịch vụ LocalCan phục vụ, mỗi dịch vụ có một handle <project>/<service>, target cục bộ và số lượng endpoint.	không có
list_public_urls	Liệt kê các Public URL của bạn, bao gồm cả những URL đã tạm dừng, mỗi URL có trạng thái (active, paused, error, starting, inactive) và nội dung nó phục vụ (live, snapshot, none). Mỗi hàng cũng mang access: none, password, link hoặc tên chính sách nhóm. Một URL đang đỗ phục vụ Snapshot sẽ đọc trạng thái paused nhưng phục vụ snapshot, vì vậy hãy trả lời "liên kết có hoạt động không?" dựa trên serving, không phải state.	không có
get_public_url_status	Báo cáo trạng thái của một Public URL, nội dung nó phục vụ (live, snapshot, none) và bảo vệ access của nó, cùng từ vựng như danh sách.	url bắt buộc
create_public_url	Tạo một Public URL cho một cổng cục bộ trong một dự án mới và trả về địa chỉ được gán, như my-app-12.localcan.dev. Mất vài giây. Nếu tunnel bị từ chối (ví dụ giới hạn Public URL của gói bạn) hoặc hết thời gian, lần thử sẽ được hoàn tác và không để lại gì. Để có liên kết vẫn truy cập được sau khi máy của bạn ngoại tuyến, hãy thêm Snapshot bằng add_snapshot.	port bắt buộc, name tùy chọn (định hình địa chỉ), protocol http hoặc tcp (mặc định http)
add_public_url	Thêm một Public URL vào một dịch vụ bạn đã cấu hình. Giao thức tuân theo target của dịch vụ, vì vậy target tcp:// sẽ có tunnel TCP. Cùng cơ chế hoàn tác khi thất bại như create.	service handle bắt buộc
pause_public_url	Đưa một Public URL ngoại tuyến trong khi giữ địa chỉ của nó, để có thể tiếp tục sau. Một địa chỉ *.localcan.dev được tạo sẽ được giữ trong 7 ngày khi tạm dừng, tên miền tùy chỉnh không bao giờ hết hạn.	url bắt buộc
resume_public_url	Đưa một Public URL đã tạm dừng trở lại trực tuyến tại cùng địa chỉ.	url bắt buộc
remove_public_url	Xóa vĩnh viễn một Public URL. Một địa chỉ được tạo sẽ được giải phóng, tên miền tùy chỉnh vẫn thuộc về bạn và có thể thêm lại. Xóa endpoint cuối cùng của một dịch vụ cũng xóa dịch vụ và dự án đã trống. Để giữ địa chỉ nhưng ngừng phục vụ Snapshot, hãy dùng remove_snapshot. Được đánh dấu là destructive, vì vậy host thường yêu cầu xác nhận.	url bắt buộc

Snapshot (xem Snapshots):

Công cụ	Chức năng	Tham số
publish_snapshot	Xuất bản một thư mục dưới dạng Snapshot trên một Public URL mới, để nó vẫn truy cập được sau khi máy của bạn ngoại tuyến. Hãy trỏ vào đầu ra tĩnh đã build khi có thể, hoặc vào thư mục gốc dự án để LocalCan build (các phụ thuộc phải đã được cài đặt). Trả về địa chỉ mới. Luôn tạo một URL mới, vì vậy để làm mới bản xem trước hiện có hãy dùng update_snapshot.	path bắt buộc (đường dẫn tuyệt đối), name tùy chọn (định hình địa chỉ)
add_snapshot	Thêm một Snapshot vào một Public URL bạn đã có, để một liên kết hiện có tiếp tục phục vụ ngoại tuyến. Trỏ vào update_snapshot nếu URL đã có một Snapshot.	url và path bắt buộc
update_snapshot	Xuất bản lại Snapshot trên một Public URL. Bỏ qua path để build lại từ cùng nguồn, hoặc truyền vào để trỏ lại một thư mục khác. Trỏ vào add_snapshot nếu URL không có Snapshot.	url bắt buộc, path tùy chọn
remove_snapshot	Xóa Snapshot khỏi một Public URL. URL vẫn được giữ và tiếp tục phục vụ live khi tunnel của bạn đang hoạt động. Được đánh dấu là destructive.	url bắt buộc
get_snapshot_status	Báo cáo Snapshot của một Public URL: thư mục nguồn, thời điểm xuất bản, nguồn có thay đổi kể từ đó không (stale) và URL hiện đang phục vụ live hay snapshot.	url bắt buộc

Kiểm soát truy cập (xem Access control):

Công cụ	Chức năng	Tham số
set_password	Bảo vệ một Public URL bằng mật khẩu để chỉ những người có mật khẩu mới mở được. Được thực thi trên máy chủ của LocalCan, vì vậy cũng bao phủ Snapshot trên URL đó. Tạo một mật khẩu mạnh trừ khi bạn truyền vào một mật khẩu, và trả về nó để bạn chia sẻ. Cần gói đăng ký.	url bắt buộc, password tùy chọn (bỏ qua để tạo một mật khẩu)
clear_access	Xóa bảo vệ bằng mật khẩu, làm cho URL công khai trở lại. Không xóa URL hoặc Snapshot của nó. Được đánh dấu là destructive, vì vậy host thường yêu cầu xác nhận.	url bắt buộc
get_access_status	Báo cáo bảo vệ của một Public URL và trả về mật khẩu hiện tại khi nó được bảo vệ bằng mật khẩu. Mật khẩu không bao giờ được trả về bởi list_public_urls, chỉ ở đây.	url bắt buộc

Kết nối một agent

Cách bạn kết nối phụ thuộc vào cách agent chạy. Agent chạy trong terminal (Claude Code, Codex) kế thừa PATH shell của bạn, vì vậy lệnh localcan trần hoạt động. Ứng dụng GUI (Cursor, Claude Desktop, VS Code và các ứng dụng khác) không tải PATH shell của bạn, vì vậy chúng cần đường dẫn tuyệt đối đến tệp nhị phân, ví dụ /Users/you/.localcan/bin/localcan. Cài đặt của ứng dụng desktop có thể sao chép cấu hình sẵn sàng với đường dẫn chính xác đã được điền, đây cũng là cách đáng tin cậy trên Windows.

Claude Code

claude mcp add --scope user localcan -- localcan mcp

Cờ --scope user đăng ký máy chủ cho mọi dự án. Bỏ nó đi để chỉ đăng ký trong dự án hiện tại.

Codex

codex mcp add localcan -- localcan mcp

Thao tác này ghi máy chủ vào ~/.codex/config.toml. Đối với ứng dụng desktop Codex hoặc tiện ích mở rộng IDE, hãy truyền đường dẫn tuyệt đối thay cho localcan.

Cursor, Claude Desktop và Windsurf

Những ứng dụng này dùng chung định dạng mcpServers:

{
  "mcpServers": {
    "localcan": {
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

Thêm nó vào tệp phù hợp, sau đó tải lại:

• Cursor: ~/.cursor/mcp.json, sau đó bật máy chủ trong Settings.
• Claude Desktop: claude_desktop_config.json (Settings, Developer, Edit Config), sau đó thoát và khởi động lại.
• Windsurf: ~/.codeium/windsurf/mcp_config.json, sau đó làm mới bảng MCP.

VS Code

VS Code (Copilot agent mode) dùng khóa servers với loại tường minh. Thêm nội dung này vào .vscode/mcp.json trong workspace của bạn:

{
  "servers": {
    "localcan": {
      "type": "stdio",
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

Bạn cũng có thể chạy code --add-mcp với cùng đối tượng máy chủ.

Zed

Zed dùng context_servers trong settings.json của nó:

{
  "context_servers": {
    "localcan": {
      "source": "custom",
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

Bạn cũng có thể thêm nó từ cài đặt Agent Panel.

Quyền truy cập agent, redaction và quyền ghi

Cả ba đều được kiểm soát trong ứng dụng desktop tại Settings (mục "AI Agents (MCP)"), hoặc từ terminal: localcan mcp enable / disable cho quyền truy cập agent, localcan mcp redact <on|off> cho redaction, localcan mcp access <read_only|read_write> cho quyền ghi và localcan mcp status để xem trạng thái hiện tại.

• Quyền truy cập agent bật theo mặc định. Tắt nó để ngăn agent sử dụng LocalCan hoàn toàn. Máy chủ vẫn khởi động, nhưng mọi công cụ trả về thông báo "access is disabled" rõ ràng cho đến khi bạn bật lại.
• Redaction bật theo mặc định cho agent. Các header nhạy cảm (Authorization, cookie, API keys) bị loại khỏi phản hồi của công cụ. URL và body không bị redact. Tắt nó để agent của bạn nhận được giá trị thô.
• Quyền ghi tắt theo mặc định. Đọc hoạt động mà không cần nó, nhưng các công cụ ghi trả về thông báo read-only rõ ràng cho đến khi bạn bật nó, trong ứng dụng ("Allow agents to create and change Public URLs") hoặc bằng localcan mcp access read_write. Bật quyền truy cập agent không cấp quyền ghi. Chúng là các công tắc riêng biệt. Mỗi lần ghi được ghi vào đầu ra chẩn đoán của máy chủ, mà host của bạn thu thập, vì vậy bạn có bản ghi về những gì agent đã thay đổi. Mật khẩu truyền cho set_password bị che trong nhật ký đó.

Khi một công cụ từ chối

• Mọi công cụ đều báo lỗi với thông báo kết nối daemon: LocalCan không đang chạy. Hãy mở ứng dụng desktop hoặc chạy localcan start -d.
• list_traffic trả về không có gì: thu thập đang tắt (mặc định tắt và được đặt lại khi daemon khởi động lại). Chạy localcan traffic enable hoặc để agent gọi enable_capture.
• "MCP access is disabled": quyền truy cập agent đã bị tắt. Chạy localcan mcp enable hoặc bật công tắc Settings.
• "MCP is read-only": công cụ thay đổi dữ liệu và quyền ghi đang tắt. Chạy localcan mcp access read_write hoặc bật công tắc Settings.
• "public URLs require a license": tạo và thêm Public URL cần giấy phép đang hoạt động. Kích hoạt một giấy phép trong ứng dụng hoặc bằng localcan license activate <key>.
• "need a subscription plan": Snapshots và Access control chỉ dành cho gói đăng ký. Giấy phép vĩnh viễn có thể mở Public URL nhưng không thể xuất bản Snapshot hoặc đặt mật khẩu. Đăng ký từ dashboard của bạn, sau đó thử lại.
• "already has a snapshot" hoặc "has no snapshot yet": hãy dùng công cụ mà thông báo nêu tên. add_snapshot gắn Snapshot vào URL chưa có, update_snapshot làm mới URL đã có.
• "Snapshot limit reached": gói của bạn giới hạn số Public URL có thể phục vụ Snapshot cùng lúc. Thông báo liệt kê các URL đã dùng slot, bạn có thể làm mới bằng update_snapshot thay vì xuất bản một URL mới.
• Host hiển thị máy chủ bị lỗi hoặc không có công cụ: ứng dụng GUI không tìm thấy localcan trên PATH. Hãy dùng đường dẫn tuyệt đối, dễ nhất là qua Settings copy config.