ReferenceCommandsMCP servers and outside services
turno mcp
MCP servers behind the lazy gateway, and the gateway daemon itself.
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 rotateSubcommands
turno mcp list
Usage:
turno mcp list [--json] servers in mcp.toml and where they run
Examples:
$ turno mcp list --json=name,kindturno mcp sync
Usage:
turno mcp sync [profile...] [--dry-run] [--force]
write gateway entries into every profile config
Examples:
$ turno mcp syncturno mcp config
Usage:
turno mcp config --agent <a> [--profile <p>] [--json]
print gateway entries for other agents
Examples:
$ turno mcp config --agent opencodeturno mcp import
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 --writeturno mcp export
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.tomlturno mcp install
Usage:
turno mcp install [server...] [--dry-run] [--allow-scripts]
install packages at exact versions
Examples:
$ turno mcp installturno mcp refresh
Usage:
turno mcp refresh [server...] [--dry-run]
make mcpd relearn tool lists
Examples:
$ turno mcp refresh githubturno mcp doctor
Usage:
turno mcp doctor [--json] find servers that bypass the gateway
Examples:
$ turno mcp doctorturno mcp login
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 workturno mcp logout
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 --allturno mcp log
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 githubturno mcp top
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 sturno mcp savings
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 savingsturno mcp call
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 --jsonturno mcp daemon
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 rotateturno mcp token
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