AI agents

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 and manage Public URLs (tunnels). 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 twelve tools. Reading works out of the box. The five tools that change things need write access, which is off by default (see the switches below). Creating or adding a Public URL also needs an active license. In free mode those two 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 `<project>/<service>` 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, or inactive.	none
`get_public_url_status`	Reports one Public URL's state, 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.	`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. Marked destructive, so hosts typically ask for confirmation.	`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

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

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

{
  "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

{
  "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

{
  "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.

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": create and add need an active license. Activate one in the app or with localcan license activate <key>.
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.