DocsConcepts
The gateway
mcpd is one local process that every session of every agent reaches, and that starts each MCP server once.
This page explains what the gateway (mcpd) does between your agents and your MCP servers.
Every agent config points at one place
turno mcp sync writes each server into every profile's config as an HTTP entry that points at mcpd:
"calendar": {
"type": "http",
"url": "http://127.0.0.1:47821/mcp/calendar",
"headers": {
"Authorization": "Bearer <the work profile's token>",
"X-Turno-Profile": "work",
"X-Turno-Pid": "${TURNO_SESSION_PID:-0}",
"X-Turno-Cwd-B64": "${TURNO_SESSION_CWD_B64:-}"
}
}The servers themselves live in one file, ~/.config/turno/mcp.toml (reference):
[server.calendar]
command = "cal-mcp"
package = "@calcom/cal-mcp@1.4.0" # installed by `turno mcp install`
env = { CAL_API_KEY = "keychain:turno/calendar/api-key" }
scope = "shared" # one process for every sessionWhat it does
- Answers from a cache.
initialize,tools/list,prompts/listandresources/templates/listcome from a cache, so a session that never calls a tool never starts the server. - Starts a server on its first real call, and relays requests, notifications, progress and cancellation.
- Shares the process between sessions where it is safe, according to the server's scope.
- Stops it when idle: after
idlewithout calls (30 minutes by default for a shared server, 20 for the others), sooner when memory is low. - Cancels a call upstream when the client cancels it or goes away, so an interrupted tool does not keep the server alive.
- Backs off a server that fails to start: after 3 failed starts in a row it answers at once with the last lines of the server's log, and retries with a growing delay.
- Reloads
mcp.tomlwhen it changes, and tells open sessions when what they see changed. - Sends every tool call through one pipeline: the profile's tool filter, then the call log, then a session id. Each relayed call carries
_meta["io.turno/session"], an opaque id that is the same for every call of one agent session and different for every other, so a shared server can tell sessions apart.
It speaks MCP 2025-11-25 and 2026-07-28 on the same endpoint.
What you see
turno mcp list # servers in mcp.toml and where they run
turno mcp daemon status # running servers, clients, memory; or why mcpd is downMCP servers ────────────────────────────────────────────────────────────────────
server kind scope idle profiles state auth details
docs stdio shared 30m all ○ stopped - /private/tmp/turno-vhs/bin/node
issues stdio shared 30m all ○ stopped - /private/tmp/turno-vhs/bin/node; variants: work
mcpd pid 92050 · port 52151 · 68 MB · 0 client sessions
no servers running (they start on first use)One token per profile
Each profile gets its own gateway token, derived from a master token that never goes into an agent config. mcpd reads the profile from the token, so a session with the work token cannot open a server whose profiles leave work out. turno mcp token rotate replaces the master token, which invalidates every profile token; then turno mcp sync writes the new ones.
mcpd listens on 127.0.0.1 only, and rejects any request that carries an Origin header, so a web page in your browser cannot reach it. More in Security and privacy.
One server, two accounts
A variant holds what changes for one profile, usually the account. Each variant runs as its own process, so two profiles can reach two accounts of the same service:
[server.issues]
command = "issues-mcp"
[server.issues.variant.work] # the work profile reaches a different account
env = { ISSUES_TOKEN = "keychain:turno/issues/work" }Which tools a session sees
[server.issues]
command = "issues-mcp"
tools = { allow = ["get_*", "list_*"], deny = ["*_delete"] }Patterns match whole tool names. With allow, only matching tools stay; deny then removes matching ones. A filtered tool is absent from tools/list, and a call to it gets an error.
Secrets
Values that start with keychain: are read from the macOS Keychain or the Linux Secret Service when the server starts; env: reads mcpd's own environment. Store a secret with turno secret set <service>: the input is hidden and never printed.
Remote servers
[server.linear]
url = "https://mcp.linear.app/mcp"
auth = "oauth" # mcpd logs in once per account: turno mcp login linear
[server.docs]
url = "https://docs.example.com/mcp" # remote, no secrets: written straight into each profileA remote server with auth = "oauth" or secret headers goes through mcpd, so no agent logs in to it on its own. You log in once per account:
turno mcp login linear # the login every profile without a variant uses
turno mcp login linear --profile personal # the personal variantThe tokens go to the secret store, never to a file or a log. A remote server without secrets is written straight into each profile and never touches mcpd.
The daemon as a service
turno mcp daemon start keeps mcpd alive with a LaunchAgent on macOS or a systemd --user unit on Linux; turno mcp daemon stop stops it and removes the file, so it does not come back at login.
mcpd listens only on mcpd.port (47821 by default). If something else holds that port, mcpd does not move: it fails and names the owner. If mcp.toml stops validating, mcpd keeps serving the last copy that did and reports the error in turno mcp daemon status and turno doctor.
Watching it
turno mcp log -f --server github --profile work # follow new tool calls, filtered
turno mcp top # memory, sessions and calls per running server
turno mcp savings # memory now against the same sessions without the gatewayThe call log holds tool names, profiles, agents, durations, sizes and redacted errors, never a call's arguments or its result. Turn it off with call_log = false under [mcpd] in config.toml.