Skip to Content

Reference

mcp.toml

Every key of ~/.config/turno/mcp.toml: the MCP servers behind the gateway.

View source

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.

KeyExampleWhat 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
exclusivefalseone 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.

KeyExampleWhat 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.

KeyExampleWhat 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.

KeyExampleWhat 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_port33418fixed 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

~/.config/turno/mcp.toml
[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)
A remote server with OAuth
[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 several

Values 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.

On this page