# mcp.toml (/docs/reference/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 [#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 [#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 [#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 [#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 [#the-annotated-file]

```toml title="~/.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)
```

```toml title="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](/docs/concepts/gateway) and [Scopes](/docs/concepts/scopes).