mcp.toml
Every key of ~/.config/turno/mcp.toml: the MCP servers behind the gateway.
This page lists every key of ~/.config/turno/mcp.toml, the file that says which MCP servers run behind the gateway. turno mcp import drafts it from the servers your agents already use, and turno config check parses it.
A server that turno starts
[server.<name>] with a command is a stdio server: mcpd starts it the first time one of its tools is called.
| Key | Example | What it does |
|---|---|---|
command | "server-bin" | stdio server |
args | ["--flag"] | its arguments |
env | { TOKEN = "keychain:turno/name/token", REGION = "eu", OTHER = "env:SOME_VAR" } | its environment: keychain: and env: values are read when it starts |
cwd | "/abs/path" | default: project root (project), session folder (session), home (shared) |
package | "server-pkg@1.2.3" | optional: turno mcp install pins it to an exact version; until then npx runs it (with a warning in the logs) |
scope | "shared" | shared | project | session (default shared) |
idle | "30m" | stop after this long without calls (default 30m shared, 20m others; a session server stays while its session's process lives, unless memory pressure is critical) |
call_timeout | "10m" | optional: cancel a single request that runs longer (off by default; it also cuts calls waiting for the user to answer a form) |
stop_grace | "5s" | optional: wait after closing stdin before SIGTERM (then 2s and SIGKILL); default 5s for turno-browser-mcp, 2s for every other server |
exclusive | false | one client session at a time (shared scope only) |
lease | "5m" | exclusive: how long an idle holder keeps it |
profiles | ["*"] | which profiles get this server (and may open it) |
tools | { allow = ["get_*", "list_*"], deny = ["*_delete"] } | optional: which tools sessions see |
builtin | "accounts" | a server that runs inside mcpd (no process); accounts is the accounts bridge |
What changes for one profile
[server.<name>.variant.<profile>] holds what differs for one profile, usually the account. Each variant runs as its own process.
| Key | Example | What it does |
|---|---|---|
env | { TOKEN = "keychain:turno/name/token-work" } | added to the server's env; a key here wins |
command | "server-bin-work" | optional: another program for this profile |
args | ["--account", "work"] | optional: replaces the server's args |
cwd | "/abs/path" | optional: another working folder |
tools | { deny = ["*"] } | replaces the server's allow / deny, key by key, for this profile |
A remote server
[server.<name>] with a url is a remote server. With secret headers or auth = "oauth" it goes through mcpd; without either it is written straight into each profile. It also takes profiles, idle, call_timeout and, when it goes through mcpd, tools.
| Key | Example | What it does |
|---|---|---|
url | "https://example.com/mcp" | a remote server, reached over HTTP |
headers | { Authorization = "keychain:turno/remote/auth" } | secret headers: proxied by mcpd |
type | "http" | or "sse" for the legacy HTTP+SSE transport |
auth | "oauth" | instead of an Authorization header: mcpd logs in (see below) |
OAuth settings
[server.<name>.oauth] is optional: discovery fills in the rest.
| Key | Example | What it does |
|---|---|---|
scope | "read write" | instead of what the server asks for |
client_id | "abc123" | a client you registered by hand (pre-registration) |
client_secret | "keychain:turno/linear/client-secret" | its secret, only as a reference |
callback_port | 33418 | fixed loopback port, when the client was registered with one |
client_metadata_url | "https://example.com/turno-client.json" | a Client ID Metadata Document you host |
authorization_server | "https://auth.example.com" | when the server lists several |
The annotated file
[server.<name>]
command = "server-bin" # stdio server
args = ["--flag"] # its arguments
env = { TOKEN = "keychain:turno/name/token", REGION = "eu", OTHER = "env:SOME_VAR" }
# its environment: keychain: and env: values are read when it starts
cwd = "/abs/path" # default: project root (project), session folder (session), home (shared)
package = "server-pkg@1.2.3" # optional: `turno mcp install` pins it to an exact version; until then npx runs it (with a warning in the logs)
scope = "shared" # shared | project | session (default shared)
idle = "30m" # stop after this long without calls (default 30m shared, 20m others;
# a session server stays while its session's process lives,
# unless memory pressure is critical)
call_timeout = "10m" # optional: cancel a single request that runs longer (off by default;
# it also cuts calls waiting for the user to answer a form)
stop_grace = "5s" # optional: wait after closing stdin before SIGTERM (then 2s and SIGKILL);
# default 5s for turno-browser-mcp, 2s for every other server
exclusive = false # one client session at a time (shared scope only)
lease = "5m" # exclusive: how long an idle holder keeps it
profiles = ["*"] # which profiles get this server (and may open it)
tools = { allow = ["get_*", "list_*"], deny = ["*_delete"] } # optional: which tools sessions see
[server.<name>.variant.<profile>] # what changes for one profile (a different account)
env = { TOKEN = "keychain:turno/name/token-work" } # added to the server's env; a key here wins
command = "server-bin-work" # optional: another program for this profile
args = ["--account", "work"] # optional: replaces the server's args
cwd = "/abs/path" # optional: another working folder
tools = { deny = ["*"] } # replaces the server's allow / deny, key by key, for this profile
[server.<remote>]
url = "https://example.com/mcp" # a remote server, reached over HTTP
headers = { Authorization = "keychain:turno/remote/auth" } # secret headers: proxied by mcpd
type = "http" # or "sse" for the legacy HTTP+SSE transport
auth = "oauth" # instead of an Authorization header: mcpd logs in (see below)[server.linear]
url = "https://mcp.linear.app/mcp"
auth = "oauth"
[server.linear.variant.personal] # this profile logs in with another account
# (optional key: tools)
[server.linear.oauth] # all optional
scope = "read write" # instead of what the server asks for
client_id = "abc123" # a client you registered by hand (pre-registration)
client_secret = "keychain:turno/linear/client-secret" # its secret, only as a reference
callback_port = 33418 # fixed loopback port, when the client was registered with one
client_metadata_url = "https://example.com/turno-client.json" # a Client ID Metadata Document you host
authorization_server = "https://auth.example.com" # when the server lists severalValues that start with keychain: are read from the secret store when the server starts, and env: reads mcpd's own environment. How scopes, variants and filters behave: The gateway and Scopes.