# 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](/docs/cli/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, 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](/docs/public-urls/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](/docs/public-urls/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

```sh
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

```sh
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. 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](https://www.localcan.com/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.