LocalCan

MCP server

---

Run LocalCan's Model Context Protocol server and wire it into your MCP host, with a full reference of the tools and switches.

localcan mcp runs a Model Context Protocol server over stdio. An MCP host (Claude Code, Codex, Cursor, Claude Desktop, and others) launches it and calls LocalCan's tools to read captured traffic, manage Public URLs (tunnels), and publish Snapshots. LocalCan must be running for the tools to return data, so open the desktop app or run localcan start -d first.

Tools

The server exposes twenty tools. Reading works out of the box. The eleven tools that change things need write access, which is off by default (see the switches below). Creating or adding a Public URL needs an active license. Publishing a Snapshot and password-protecting a URL need a subscription plan, so a perpetual license is turned away even though it can still open Public URLs. Unlicensed, the gated tools return a clear activation message, while pausing, resuming, and removing existing URLs still work.

Traffic:

Tool	What it does	Parameters
get_status	Reports whether capture is on and how much traffic is buffered.	none
enable_capture	Turns capture on. Capture is off by default and resets when the daemon restarts.	none
list_traffic	Lists recent exchanges, newest first.	last (default 20), host substring, project id, method, status (exact code or a class like 5xx)
get_exchange	Returns one exchange by id.	id required (full id or any unique prefix), format one of markdown, curl, http, har, json (default markdown), include_response (default true)

An exchange is the request LocalCan forwarded to your backend, not a byte-for-byte copy of the client's original request. See Traffic for the data model.

Public URLs:

Tool	What it does	Parameters
list_services	Lists the services LocalCan serves, each with a / handle, its local target, and endpoint count.	none
list_public_urls	Lists your Public URLs, including paused ones, each with its state (active, paused, error, starting, inactive) and what it serves (live, snapshot, none). Every row also carries access: none, password, link, or a team-policy name. A parked URL that serves a Snapshot reads state paused but serving snapshot, so answer "is the link up?" from serving, not state.	none
get_public_url_status	Reports one Public URL's state, what it serves (live, snapshot, none), and its access protection, same vocabulary as the list.	url required
create_public_url	Creates a Public URL for a local port in a new project and returns the assigned address, like my-app-12.localcan.dev. Takes a few seconds. If the tunnel is rejected (for example your plan's Public URL limit) or times out, the attempt is rolled back and nothing is left behind. For a link that stays reachable after your machine goes offline, add a Snapshot with add_snapshot.	port required, name optional (shapes the address), protocol http or tcp (default http)
add_public_url	Adds a Public URL to a service you already have configured. The protocol follows the service's target, so a tcp:// target gets a TCP tunnel. Same rollback on failure as create.	service handle required
pause_public_url	Takes a Public URL offline while keeping its address, so it can be resumed later. A generated *.localcan.dev address stays reserved for 7 days while paused, custom domains never expire.	url required
resume_public_url	Brings a paused Public URL back online at the same address.	url required
remove_public_url	Permanently removes a Public URL. A generated address is released, a custom domain stays yours and can be added again. Removing a service's last endpoint also removes the emptied service and project. To keep the address but stop serving a Snapshot, use remove_snapshot. Marked destructive, so hosts typically ask for confirmation.	url required

Snapshots (see Snapshots):

Tool	What it does	Parameters
publish_snapshot	Publishes a folder as a Snapshot on a new Public URL, so it stays reachable after your machine goes offline. Point it at built static output when you can, or at a project root for LocalCan to build (dependencies must already be installed). Returns the new address. Always creates a new URL, so to refresh an existing preview use update_snapshot.	path required (absolute), name optional (shapes the address)
add_snapshot	Adds a Snapshot to a Public URL you already have, so an existing link keeps serving offline. Points at update_snapshot if the URL already has one.	url and path required
update_snapshot	Re-publishes the Snapshot on a Public URL. Omit path to rebuild from the same source, or pass it to repoint at another folder. Points at add_snapshot if the URL has none.	url required, path optional
remove_snapshot	Removes the Snapshot from a Public URL. The URL stays reserved and keeps serving live while your tunnel is up. Marked destructive.	url required
get_snapshot_status	Reports a Public URL's Snapshot: its source folder, when it was published, whether the source changed since (stale), and whether the URL serves live or the snapshot right now.	url required

Access control (see Access control):

Tool	What it does	Parameters
set_password	Password-protects a Public URL so only people who have the password can open it. Enforced on LocalCan's servers, so it also covers a Snapshot on that URL. Generates a strong password unless you pass one, and returns it so you can share it. Needs a subscription plan.	url required, password optional (omit to generate one)
clear_access	Removes password protection, making the URL public again. Does not remove the URL or its Snapshot. Marked destructive, so hosts typically ask for confirmation.	url required
get_access_status	Reports a Public URL's protection and returns its current password when it is password-protected. The password is never returned by list_public_urls, only here.	url required

Connecting an agent

How you connect depends on how the agent runs. Terminal agents (Claude Code, Codex) inherit your shell PATH, so a bare localcan command works. GUI apps (Cursor, Claude Desktop, VS Code, and others) do not load your shell PATH, so they need the absolute path to the binary, for example /Users/you/.localcan/bin/localcan. The desktop app's Settings can copy a ready-made config with the right path filled in, which is also the reliable route on Windows.

Claude Code

Shell

Copy

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

Flag --scope user registers the server for every project. Drop it to register it only in the current project.

Codex

Shell

Copy

codex mcp add localcan -- localcan mcp

This writes the server to ~/.codex/config.toml. For the Codex desktop app or IDE extension, pass the absolute path in place of localcan.

Cursor, Claude Desktop, and Windsurf

These share the same mcpServers format:

JSON

Copy

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

Add it to the right file, then reload:

• Cursor: ~/.cursor/mcp.json, then enable the server in Settings.
• Claude Desktop: claude_desktop_config.json (Settings, Developer, Edit Config), then quit and relaunch.
• Windsurf: ~/.codeium/windsurf/mcp_config.json, then refresh the MCP panel.

VS Code

VS Code (Copilot agent mode) uses a servers key with an explicit type. Add this to .vscode/mcp.json in your workspace:

JSON

Copy

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

You can also run code --add-mcp with the same server object.

Zed

Zed uses context_servers in its settings.json:

JSON

Copy

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

You can also add it from the Agent Panel settings.

Agent access, redaction, and write access

All three are controlled in the desktop app under Settings (the "AI Agents (MCP)" section), or from the terminal: localcan mcp enable / disable for agent access, localcan mcp redact <on|off> for redaction, localcan mcp access <read_only|read_write> for write access, and localcan mcp status to see the current state.

• Agent access is on by default. Turn it off to stop agents from using LocalCan at all. The server still starts, but every tool returns a clear "access is disabled" message until you turn it back on.
• Redaction is on by default for agents. Sensitive headers (Authorization, cookies, API keys) are removed from tool responses. URLs and bodies are not redacted. Turn it off to let your own agent receive raw values.
• Write access is off by default. Reading works without it, but the write tools return a clear read-only message until you turn it on, in the app ("Allow agents to create and change Public URLs") or with localcan mcp access read_write. Turning on agent access does not grant write access. They are separate switches. Every write call is logged to the server's diagnostic output, which your host captures, so you have a record of what an agent changed. A password passed to set_password is masked in that log.

When a tool refuses

• Every tool errors with a daemon connection message: LocalCan is not running. Open the desktop app or run localcan start -d.
• list_traffic returns nothing: capture is off (it is off by default and resets when the daemon restarts). Run localcan traffic enable or let the agent call enable_capture.
• "MCP access is disabled": agent access is switched off. Run localcan mcp enable or flip the Settings toggle.
• "MCP is read-only": the tool changes things and write access is off. Run localcan mcp access read_write or turn on the Settings toggle.
• "public URLs require a license": creating and adding a Public URL need an active license. Activate one in the app or with localcan license activate <key>.
• "need a subscription plan": Snapshots and Access control are subscription-only. A perpetual license can open Public URLs but cannot publish a Snapshot or set a password. Subscribe from your dashboard↗, then retry.
• "already has a snapshot" or "has no snapshot yet": use the tool the message names. add_snapshot attaches a Snapshot to a URL that has none, update_snapshot refreshes one that already does.
• "Snapshot limit reached": your plan caps how many Public URLs can serve a Snapshot at once. The message lists the URLs already using a slot, which you can refresh with update_snapshot instead of publishing a new one.
• The host shows the server as failed or with no tools: a GUI app cannot find localcan on the PATH. Use the absolute path, easiest via the Settings copy config.

© 2026 LocalCan™. All rights reserved.