DocsGuides
Many sessions eat my RAM
Put your MCP servers behind one gateway, so each one runs once instead of once per session.
This guide moves the MCP servers you already use behind turno's gateway, so opening another agent session stops starting another copy of each server.
Why it happens
Every coding-agent session starts its own copy of every MCP server in its config. With eight sessions and six common servers that is 56 processes and 3,163 MiB before any tool is called. Behind the gateway each server starts once, only when one of its tools is called, and stops when idle.
Move your servers behind the gateway
Preview what turno would import
turno mcp importIt drafts mcp.toml from the servers your agents already use: ~/.claude.json, .mcp.json in the current folder, ~/.codex/config.toml, ~/.cursor/mcp.json, ~/.copilot/mcp-config.json, and the config inside each turno profile. It is a preview until --write: secrets are shown masked, nothing is stored and nothing goes online.
Write it, with the secrets in the secret store
turno mcp import --move-secrets --write--move-secrets stores env and header secrets in the macOS Keychain or the Linux Secret Service and writes keychain: references in their place. Secrets in a server's args or URL stay literal, since they cannot come from the store.
Start the gateway and point every profile at it
turno mcp daemon start && turno mcp syncThe gateway runs as a login service (launchd on macOS, systemd --user on Linux). turno mcp sync writes one HTTP entry per server into every profile's config, pointing at 127.0.0.1.
Pin the versions (optional, recommended)
turno mcp installIt installs each package at an exact version, without install scripts, with a lockfile per server. Until then npx runs the server, with a warning in its log.
What you see
turno mcp list shows the servers and where they run. Before any tool is called, none is running:
turno demo ~ % turno mcp list
MCP 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
turno demo ~ % turno mcp daemon status
mcpd pid 92050 · port 52151 · 68 MB · 0 client sessions
no servers running (they start on first use)
turno demo ~ % turno mcp top --once
mcpd pid 92050 · v0.2.0 · up 4s · 68 MB own, 149 MB with servers · 0 sessions from 0 agents
! memory pressure warn: idle servers stop after 5m 0s (mcpd.idle_under_pressure)
no servers running (they start on first use)
Once sessions are open, three commands watch it:
turno mcp top # memory, sessions, calls in flight, idle time and restarts per running server
turno mcp savings # mcpd's memory now against the same sessions without the gateway
turno mcp log # the last 20 tool calls: time, outcome, duration, server, tool, profile, agentturno mcp savings compares the gateway plus every server it runs with an estimate of the same live sessions without it: each session would start its own copy of every stdio server its profile uses. The tool call log never holds a call's arguments or its result, only their sizes.
Servers that cannot be shared
A stateless server (docs, search, an issue tracker) shares one process safely. A server that keeps state per conversation, or that only one session can use at a time, needs another scope:
Those scopes give back some of the saving, on purpose. See Scopes.
When memory is tight
mcpd stops a server after it sits idle (30 minutes by default for a shared server). When the system reports memory pressure, the idle limit shrinks to idle_under_pressure (5 minutes by default), and to a quarter of that when pressure is critical:
[mcpd]
idle_under_pressure = "5m" # false turns it offPlugin servers
Servers that come from Claude Code plugins start in every session and bypass the gateway. turno mcp doctor lists them. To route one through the gateway, disable the plugin and declare [server.plugin_<plugin>_<name>] in mcp.toml, so tool names stay the same.
Measure it yourself
The numbers above come from one machine. Run the benchmark on yours, with your own servers, before you quote one.