Skip to Content

DocsConcepts

Scopes

A server's scope says how many processes it gets: one for everyone, one per repository, or one per session.

View source

This page helps you choose the scope of each server in mcp.toml: how far one process is shared.

Does it keep state per conversation,like a throwaway browser?yessessionscope = "session"one process per agent session, stopped when it endsnoDoes it read the folder it runs in,like a code index or a linter?yesprojectscope = "project"one process per git repositorynoCan only one session use it at a time,or does it ask the user questions?yesexclusiveexclusive = trueshared, one session at a time (a signed-in browser)nosharedscope = "shared" (the default)one process for every session: API clients, docs, search

The three scopes

ScopeOne process perUse it for
shared (the default)server and variantstateless API clients, indexes that cover every repository
projectgit repository of the sessionservers that read their working folder
sessionagent sessionservers that keep per-conversation state, such as a throwaway browser
~/.config/turno/mcp.toml
[server.calendar]
command = "cal-mcp"
scope = "shared"                     # one process for every session

[server.devtools]
command = "chrome-devtools-mcp"
scope = "session"                    # one per agent session, stopped when it ends

turno mcp list shows the scope of each server in its scope column.

Exclusive: shared, one session at a time

exclusive = true is not a fourth scope; it is a shared server that one client session uses at a time. An idle holder keeps it for lease (5 minutes by default). It is what a browser with a saved identity needs: one Chrome per identity.

~/.config/turno/mcp.toml
[server.browser-school]
command = "turno-browser-mcp"
args = ["--identity", "school"]
scope = "shared"
exclusive = true
lease = "10m"
idle = "30m"

Servers that ask the user

Some servers ask the user a question in the middle of a call (MCP elicitation) or ask the client's model for a completion (sampling). mcpd relays those to the session whose call is in flight. When calls from several sessions are in flight on a shared server, it refuses the request instead of guessing: use scope = "session" or exclusive = true for those servers.

What scope changes

sharedprojectsession
Working folder (cwd) by defaultyour homethe project rootthe session's folder
Stops after (idle) by default30 minutes20 minutes20 minutes, and it stays while its session's process lives
Memoryleastone process per repositoryone per session

A session server whose session still runs is kept while memory pressure is at warn; under critical pressure it stops like any other once it has been quiet, and the next call starts it again.

The more a server is shared, the more memory you save. session and exclusive give back some of that saving, in exchange for state that does not leak between conversations.

Variants are not a scope

A variant ([server.<name>.variant.<profile>]) is about accounts, not sharing: each variant runs as its own process, so two profiles can reach two accounts of the same service. A shared server with a work variant runs at most two processes: the default one and the work one.

Every key is in the mcp.toml reference.

On this page