# turno mcp (/docs/reference/cli/mcp)

MCP servers behind the lazy gateway, and the gateway daemon itself.

```text title="turno mcp --help"
Usage:
  turno mcp list [--json]             servers in mcp.toml and where they run
  turno mcp sync [profile...] [--dry-run] [--force]
                                      write gateway entries into every profile
                                      config
  turno mcp config --agent <a> [--profile <p>] [--json]
                                      print gateway entries for other agents
  turno mcp import [file] [--write] [--move-secrets] [--force]
                                      draft mcp.toml from your agent configs, or
                                      merge a file
  turno mcp export [--profile <p>] [--json]
                                      print mcp.toml without secret values, for
                                      another machine
  turno mcp install [server...] [--dry-run] [--allow-scripts]
                                      install packages at exact versions
  turno mcp refresh [server...] [--dry-run]
                                      make mcpd relearn tool lists
  turno mcp doctor [--json]           find servers that bypass the gateway
  turno mcp login <server> [--profile <p>] [--scope <s>] [--no-browser]
      [--dry-run] [--json]
                                      log mcpd in to a remote OAuth server, once
                                      per variant
  turno mcp logout <server> [--profile <p> | --all] [--no-revoke]
      [--dry-run]
                                      forget an OAuth login and revoke its token
  turno mcp log [-f] [-n N] [--server S] [--profile P] [--json]
                                      tool calls mcpd relayed (no arguments or
                                      results)
  turno mcp top [--once | --watch] [--json]
                                      memory, sessions and calls of each running
                                      server
  turno mcp savings [--json]          memory mcpd saves compared with no gateway
  turno mcp call <server> [tool] [--args JSON] [--arg k=v ...] [--profile
      <p>] [--json]
                                      call one tool through mcpd, as a profile's
                                      session would
  turno mcp daemon <start|stop|restart|status|logs>
                                      the gateway daemon (same as turno mcpd)
  turno mcp token rotate [--dry-run]  replace the gateway token, then run turno
                                      mcp sync

config prints entries for opencode, gemini, goose, crush, droid, kiro.
import reads ~/.claude.json, .mcp.json, ~/.codex, ~/.cursor and ~/.copilot,
or one file. It only previews, with secrets hidden, until --write.
Docs: docs/mcp.md in the turno repository.

Examples:
  $ turno mcp list --json=name,kind
  $ turno mcp import --write --move-secrets
  $ turno mcp import servers.toml --write
  $ turno mcp export --profile work > servers.toml
  $ turno mcp install
  $ turno mcp sync
  $ turno mcp config --agent opencode
  $ turno mcp refresh github
  $ turno mcp doctor
  $ turno mcp login linear --profile work
  $ turno mcp logout linear --all
  $ turno mcp log -f --server github
  $ turno mcp top --watch --json  # one JSON line every 2 s
  $ turno mcp savings
  $ turno mcp call github
  $ turno mcp call github search_issues --arg query=bug --arg limit:=5
  $ turno mcp call fs read_file --args '{"path": "README.md"}' --profile work --json
  $ turno mcp daemon status
  $ turno mcp token rotate
```

## Subcommands [#subcommands]

### turno mcp list [#turno-mcp-list]

```text
Usage:
  turno mcp list [--json]  servers in mcp.toml and where they run

Examples:
  $ turno mcp list --json=name,kind
```

### turno mcp sync [#turno-mcp-sync]

```text
Usage:
  turno mcp sync [profile...] [--dry-run] [--force]
    write gateway entries into every profile config

Examples:
  $ turno mcp sync
```

### turno mcp config [#turno-mcp-config]

```text
Usage:
  turno mcp config --agent <a> [--profile <p>] [--json]
    print gateway entries for other agents

Examples:
  $ turno mcp config --agent opencode
```

### turno mcp import [#turno-mcp-import]

```text
Usage:
  turno mcp import [file] [--write] [--move-secrets] [--force]
    draft mcp.toml from your agent configs, or merge a file

Without a file it drafts mcp.toml from every agent config on this machine (a
preview until --write; --force replaces an existing mcp.toml). With a file it
merges that file's servers into mcp.toml: an export (turno mcp export), a JSON
file with mcpServers, or a Codex config.toml. Servers already in mcp.toml are
kept unless --force replaces them. With --write, remote servers that answer
with an OAuth challenge get auth = "oauth".

Examples:
  $ turno mcp import --write --move-secrets
  $ turno mcp import servers.toml --write
```

### turno mcp export [#turno-mcp-export]

```text
Usage:
  turno mcp export [--profile <p>] [--json]
    print mcp.toml without secret values, for another machine

Prints mcp.toml with each secret named, never its value: keychain: and env:
references stay, literal secrets become keychain:turno/<server>/<key>
references, and the top of the file lists the turno secret set commands the
other machine needs. A secret inside args or a URL is replaced by <secret>.
--profile keeps only the servers that profile gets, and only its own variant.

Examples:
  $ turno mcp export --profile work > servers.toml
```

### turno mcp install [#turno-mcp-install]

```text
Usage:
  turno mcp install [server...] [--dry-run] [--allow-scripts]
    install packages at exact versions

Examples:
  $ turno mcp install
```

### turno mcp refresh [#turno-mcp-refresh]

```text
Usage:
  turno mcp refresh [server...] [--dry-run]
    make mcpd relearn tool lists

Examples:
  $ turno mcp refresh github
```

### turno mcp doctor [#turno-mcp-doctor]

```text
Usage:
  turno mcp doctor [--json]  find servers that bypass the gateway

Examples:
  $ turno mcp doctor
```

### turno mcp login [#turno-mcp-login]

```text
Usage:
  turno mcp login <server> [--profile <p>] [--scope <s>] [--no-browser]
      [--dry-run] [--json]
    log mcpd in to a remote OAuth server, once per variant

For servers declared with auth = "oauth" in mcp.toml. mcpd keeps the tokens in the secret store
(Keychain or Secret Service) and refreshes them; agents reach the server through mcpd.
--profile logs in the variant of that profile ([server.<name>.variant.<profile>]); without one,
the login serves every profile that has no variant of its own.

Examples:
  $ turno mcp login linear --profile work
```

### turno mcp logout [#turno-mcp-logout]

```text
Usage:
  turno mcp logout <server> [--profile <p> | --all] [--no-revoke]
      [--dry-run]
    forget an OAuth login and revoke its token

Examples:
  $ turno mcp logout linear --all
```

### turno mcp log [#turno-mcp-log]

```text
Usage:
  turno mcp log [-f] [-n N] [--server S] [--profile P] [--json]
    tool calls mcpd relayed (no arguments or results)

One line per tool call: time, outcome, duration, server, tool, profile, agent and sizes.
-f keeps printing new calls; --json prints one JSON record per line.
Turn the log off with call_log = false under [mcpd] in config.toml.

Examples:
  $ turno mcp log -f --server github
```

### turno mcp top [#turno-mcp-top]

```text
Usage:
  turno mcp top [--once | --watch] [--json]
    memory, sessions and calls of each running server

Refreshes every 2 seconds in a terminal (Ctrl-C quits); prints one snapshot otherwise.
--watch keeps refreshing anywhere; with --json it prints one snapshot per line (NDJSON).
Exits 5 when mcpd is not running.

Examples:
  $ turno mcp top --watch --json  # one JSON line every 2 s
```

### turno mcp savings [#turno-mcp-savings]

```text
Usage:
  turno mcp savings [--json]  memory mcpd saves compared with no gateway

Compares mcpd plus its servers now with an estimate where each live agent session
starts its own copy of every stdio server its profile uses.

Examples:
  $ turno mcp savings
```

### turno mcp call [#turno-mcp-call]

```text
Usage:
  turno mcp call <server> [tool] [--args JSON] [--arg k=v ...] [--profile
      <p>] [--json]
    call one tool through mcpd, as a profile's session would

For debugging a server without opening an agent. The call goes through mcpd
with the token of --profile (default: the profile this folder resolves to,
else the system one) and this folder, so tool filters and [[projects]] server
sets apply as they would to an agent here. --args takes a JSON object;
--arg key=value adds a string and --arg key:=json any JSON value. Without a
tool it lists the server's tools. Exits 1 when the tool returns isError, 5
when mcpd is not running.

Examples:
  $ turno mcp call github
  $ turno mcp call github search_issues --arg query=bug --arg limit:=5
  $ turno mcp call fs read_file --args '{"path": "README.md"}' --profile work --json
```

### turno mcp daemon [#turno-mcp-daemon]

```text
Usage:
  turno mcp daemon start [--dry-run]    install the service (LaunchAgent or
                                        systemd user unit) and start mcpd
  turno mcp daemon stop [--dry-run]     stop mcpd and remove the service, so it
                                        does not start at login
  turno mcp daemon restart              restart the service (open sessions
                                        reconnect)
  turno mcp daemon status [--json]      running servers, their clients and
                                        memory; why mcpd is down (exit 5)
  turno mcp daemon logs [-n N] [--utc]  last lines of the mcpd log, in local
                                        time
  turno mcp daemon run [--port N]       run the gateway in the foreground (what
                                        the service runs)
  turno mcp daemon token rotate [--dry-run]
                                        replace the gateway token (then turno
                                        mcp sync)

mcpd listens on 127.0.0.1 at mcpd.port (config.toml) and never moves to another port.
start keeps it alive with a LaunchAgent on macOS or a systemd user unit on Linux; stop removes it.

Examples:
  $ turno mcp daemon start
  $ turno mcp daemon status --json
  $ turno mcp daemon restart
  $ turno mcp daemon logs -n 50
  $ turno mcp daemon stop --dry-run
  $ turno mcp daemon run --port 47900
  $ turno mcp daemon token rotate
```

### turno mcp token [#turno-mcp-token]

```text
Usage: turno mcp token rotate [--dry-run]

Writes a new token (mode 600), restarts mcpd, and asks you to run turno mcp sync.

Examples:
  $ turno mcp token rotate --dry-run
  $ turno mcp token rotate && turno mcp sync
```