MCP servers
Fontaine can use tools from Model Context Protocol servers. A server runs as a child process (stdio) or is reached over streamable HTTP, and each tool it lists becomes a tool the model can call. MCP tools go through the same permission pipeline as every other tool; nothing a server says about itself changes how they are judged.
In the terminal UI, /mcp lists the servers and whether each is connected (with how many tools,
resources and prompts it listed), pending (being reconnected), failed, left off or not loaded,
and /mcp reconnect restarts them; see Reconnecting. fontaine mcp adds, lists, shows and removes
servers from the command line; see The fontaine mcp command.
Declaring servers
Servers are declared under [mcp.servers.<name>] in a settings file, or with
fontaine mcp add. Set exactly one of command (stdio) or url
(streamable HTTP). Scopes says which files may declare them.
[mcp.servers.github]
command = "github-mcp-server"
args = ["stdio"]
env_vars = ["GITHUB_TOKEN"]
[mcp.servers.docs]
url = "https://mcp.example.com/docs"
| Key | Meaning |
|---|---|
command | The program of a stdio server. It starts in the primary workspace root. |
args | Its arguments. Stdio only. |
env_vars | The names of environment variables to pass through. Stdio only. |
env | Literal variables set on the server, after the pass-through and [env] layers, replacing a variable of the same name. Stdio only. |
url | The endpoint of a streamable HTTP server. It is reached through the proxy, extra CA roots and client certificate of [network]. |
headers | Static headers sent on the server’s protocol requests, as a map. HTTP servers only; never sent to an OAuth authorization server. See Authentication. |
headers_helper | Path to an executable run at connect time; its KEY: VALUE stdout lines become headers, overriding static headers of the same name. HTTP servers only, and never in the project scope; see Authentication. |
A server name contains letters, digits, _ and -, and has no __ and no leading or trailing _.
Environment. A stdio server does not inherit Fontaine’s environment. It gets a short base set
(PATH, HOME, USER, LANG, the temporary-directory variables and, on Windows, the system
variables it needs to find programs) and the variables named in env_vars. Values never appear in
configuration, and the API keys of your model accounts and the telemetry credentials are not
passed unless you name them. Every entry of [env] is set on the server as
well, replacing a copied variable of the same name, and a server’s own env map lands last,
replacing a variable the other layers set. env values are literal: they are not expanded and
cannot reach into the process environment. A plugin’s .mcp.json env values, in
contrast, are expanded at load, and the variables a plugin references are named in the install
summary. The server’s standard error is not shown in the terminal UI; it goes to
the debug file (--debug-file).
Scopes
A server is declared in one of three scopes, as in Claude Code.
| Scope | Where | Trust |
|---|---|---|
local | mcp-local.toml in the config directory, under [projects."<root>".servers.<name>]; private to you, in one workspace | Yours: starts at once, no workspace trust or approval |
project | .mcp.json in the repository root, and [mcp.servers] in .fontaine/settings.toml; shared through the repository | The repository’s: workspace trust, then your approval |
user | [mcp.servers] in the user file (config.toml); every workspace | Yours |
<root> is the canonical launch directory, the one the project files are read from. A local file
entry is read only for its own workspace. The file lives in your config directory, which the
floor protects, so a repository cannot write it.
These sources load too, and fontaine mcp list and get show them under their own labels:
project-local (an untracked .fontaine/settings.local.toml of a trusted root, which starts at
once), cli (the --settings file) and plugin (a plugin’s .mcp.json, which
starts without the workspace-trust gate: install approved it, in the terminal UI and headless runs
alike). Extra workspace roots (--add-dir) never contribute servers.
Precedence by name: --settings > local > project-local > project > user. This is Claude
Code’s local > project > user, with Fontaine’s project-local and --settings layers kept in their
places. Within project, .fontaine/settings.toml wins over .mcp.json, and the collision warns
once at startup. A plugin’s server whose name collides with a configured server is an error that
names the plugin.
A plugin’s servers start and stop live with the plugin: /plugin install, /plugin enable and
/reload-plugins start the servers of a plugin they load, and /plugin disable, /plugin uninstall, /plugin update and a reload that changes a plugin stop its servers before its
checkout changes and start the new definitions after. A server of a plugin that did not change
keeps running. On unload the server’s tools leave the toolset first, so no new call starts;
calls already running get up to ten seconds to finish before the connection closes, and one that
is still running then ends with a transport error. A plugin that fails to load on reload (such as
a server name that collides) leaves the current set running. See
Plugins.
A malformed mcp-local.toml or .mcp.json, or an entry in one that cannot be used, is a warning
(at startup, in fontaine doctor and in fontaine mcp) and is skipped, so fontaine mcp can still
run to repair it.
Servers in the SDK host
An application using Agent SDK mode can hand Fontaine MCP servers it runs itself
(createSdkMcpServer, create_sdk_mcp_server); Fontaine reaches them through the SDK’s
mcp_message requests, not a process or a URL. Their tools register like any other MCP tool, as
arbitrary, so every call crosses the full gate and their results are untrusted output the scanner
reads. A readOnlyHint never skips the guardian.
Tool names
A tool create_issue of the server github is registered as mcp__github__create_issue, the
name permission rules use. A character in a tool name that the
rule grammar cannot name becomes _. When a server announces that its tool list changed, Fontaine
fetches the list again and registers the new tools the same way; tools that went away are removed.
Besides tools, a server can offer resources and prompts. A server may
also ask you for input while a tool runs, as described below.
Tool search
A server with many tools puts every definition (description and input schema) into every request.
Fontaine can keep those definitions out of the request until the model asks for them, as Claude Code
does: the model sees only the tool names, grouped by server, in the system prompt, and loads the
definitions it needs by calling the built-in tool_search tool.
[mcp] tool_search in configuration picks when this happens:
auto(the default) defers MCP tools when their definitions are estimated at more than a tenth of the model’s context window (10,000 tokens when the window is unknown)./contextuses the same estimate.onalways defers them.offnever does.
When tools are deferred, tool_search takes query, either keywords matched against tool names and
descriptions or select:name1,name2 for exact names, and max_results. /context lists the
deferred names and the loaded definitions separately. A subagent sees and loads only the deferred
tools its own tool set holds, and what it loads never reaches its parent’s requests or the reverse.
How a loaded tool reaches the model depends on the provider:
anthropicaccounts use Anthropic’s own tool search. Every deferred tool’s definition is sent once, in every request, markeddefer_loading, so the model does not see its definition until a search loads it, andtool_searchanswers withtool_referenceblocks that name the tools it loaded. The request prefix never changes when a tool is loaded, so loading no longer restarts the provider’s prompt cache. The references stay in the conversation, so a resumed session does not have to search again. A compaction that summarises a search result away, or a context-editingexclude_toolslist that dropstool_search(it is in the default list), lets the references go, and the model searches again. Claude 3 and the first Opus 4, Opus 4.1 and Sonnet 4 models do not support the feature and use the route below.[mcp] native_tool_search = falseturns it off for every account. If a host behind ananthropicaccount rejects the fields (a gateway that does not knowdefer_loadingortool_reference), Fontaine warns once, resends that request without them, and uses the route below for the rest of the session. The fallback is not saved.- Every other provider loads definitions on the client side: from the next request on, the loaded tools are advertised like any other. A loaded tool appears at its usual position in the tool list, which is sorted by name within each server, not after the tools loaded earlier, so the provider’s prompt cache restarts from the first position that changed. Loaded tools are remembered for the session only: after a resume or a compaction the model searches again.
Deferral changes nothing about permissions. Deferred tools are registered and guarded exactly like
loaded ones: they are arbitrary tools, your rules and hooks match their mcp__<server>__<tool>
names, and every call is judged by the same gate. A call to a deferred tool whose definition was
never loaded is not run and is not judged: the model gets a note to search first. On the
anthropic route every deferred tool is advertised, so such a call is run and judged like any other
call. tool_search
itself is read-only (it reads only the in-memory list of definitions), and loading a definition
grants nothing. The setting is not a loosening key, so a repository’s settings may set it. When the main
model uses the claude-subscription provider Fontaine never defers, because the Claude CLI owns the tool list
(see Claude subscription).
Resources
A resource is data a server exposes behind a URI. After a server connects, Fontaine pulls its
resource listing once — only when the server declared the resources capability — and again
each time the server announces a resources/list_changed notification; a failed pull keeps
the previous listing. The model sees resources through two always-registered built-in tools:
list_mcp_resourceslists every resource of every connected server that declared the capability:server,uri,name,descriptionandmime type, or an explanation when none did. Both tools arearbitrary, like everything MCP: the listing is the cached, server-declared text Fontaine pulled at connect and on each list change (no server request per call) and a read is a server round trip, so every call is floor-gated and guardian-judged.read_mcp_resourcereads one resource byserveranduri. Text contents come back as text; a blob is noted by its mime type and size, like an image result. A result over the MCP output limit is saved to a file whose path the result names, and every result passes the result scanner like any tool result: server content is untrusted.
In the terminal UI the @ mention popup also lists resource URIs, labelled with their server.
Accepting one inserts @<uri> into the message (or @<uri>@<server> when more than one
connected server exposes the same uri, so the model can tell the duplicates apart), which is
sent as typed; the mention is inert text. The model reads the content through
read_mcp_resource — this keeps every byte of server content behind the permission pipeline,
instead of inlining it into your message at send time. While at least one resources-capable
server is connected, the system prompt tells the model what an @<uri> token names.
Prompts
A prompt is server-supplied text the user can inject into the conversation as a slash
command. After a server connects, Fontaine pulls its prompt listing once — only when the
server declared the prompts capability — and again on a prompts/list_changed
notification. Every listed prompt becomes a /mcp__<server>__<prompt> command, cleaned to
the rule grammar the same way tool names are, and the / menu shows it with its declared
argument names as the hint. Running the command calls prompts/get on the server and starts
a turn with the fetched text; the transcript shows your invocation, so the guardian judges
the turn against what you typed. Arguments are key=value pairs:
/mcp__repo__greet name=Ada mood=calm
A missing required argument, a pair that is not key=value, or an unknown key fails the
command with a notice naming the prompt’s declared arguments and an example invocation, and
no turn starts. The answer is used only when every message it carries is user-role text;
an answer with an assistant-role message or non-text content (an image, audio, an embedded
or linked resource) fails the command instead of folding server-controlled content into
your turn. Prompt text is server-controlled, but it enters the conversation only when you
type the command — the same trust boundary as running a skill. It is not scanner-staged: it
arrives as your own message, like a skill’s expansion. Prompt commands exist only in the
terminal UI; headless fontaine -p understands no slash commands beyond /goal.
A server that cannot be started, or that never answers the handshake, is reported (a notice in the
terminal UI, a line on stderr in a headless run) and left out; the session goes on without it.
Starting a remote server is retried first when the failure looks temporary: a refused or reset
connection, a timeout, a 5xx or a 429. Fontaine tries up to three more times, after 1, 2 and 4
seconds, and all the attempts of one server share a 30 second deadline, so a refused server delays
startup by about 7 seconds and an unresponsive one by at most 30. Authentication, not-found and
protocol errors, and a stdio server that fails, are not retried. The servers start at once, so a
slow one does not delay the others. A server that failed to start can still be restarted by hand
with /mcp reconnect.
The trust model
-
Every MCP tool is
arbitrary. It is registered behind the same gate as the built-in tools and, likeshellandwebfetch, never earns the read-only fast path. Inmanualit asks, inautothe guardian judges it, indontAskand headless runs it is denied unless an allow rule covers it. The one exception is a tool its server marks as requiring your approval: it always needs a person’s approval and no allow rule pre-approves it, so it is denied indontAskand headless runs. -
What a server declares is only text, with one exception. A tool can claim to be read-only, idempotent or non-destructive. Those hints are passed to the guardian as untrusted text inside the
tool_callblock of its request, labelled as the server’s own claim, and never as a fact or a gate:server_declared_annotations (the server's own claim, not a fact): {"title":"Lookup","readOnlyHint":true}A
readOnlyHintnever skips the guardian. The exception is therequiresUserInteractionmarker below, the only declared value that changes a decision, and only toward asking. -
Rules are the way to pre-approve.
mcp__github,mcp__github__create_issueandmcp__github__*inallow,askordenywork like any other rule. Allow rules come from user-trust scopes only, so a repository can never allow its own server’s tools. No rule pre-approves a tool its server marked as requiring your approval. -
Credentials stay out of stdio. A stdio server does not inherit your model-account keys, the telemetry credentials or any other secret: it gets the base set and what you name. A streamable HTTP server in the project scope likewise never receives credential variables through
${VAR}expansion. Authenticating to a remote server is a different thing and is described below: it stores an OAuth token bound to that one URL, never a credential of yours.
Requiring approval for a tool
A server can mark a tool as needing a person’s approval on every call, as Claude Code allows, by
setting _meta["anthropic/requiresUserInteraction"] to the JSON Boolean true in that tool’s
tools/list entry:
{
"name": "grant_access",
"description": "Grant a user access to a project",
"inputSchema": {"type": "object"},
"_meta": {"anthropic/requiresUserInteraction": true}
}
Fontaine treats the marker as an implicit ask rule on that one tool, at the floor of the
permission pipeline. The tool asks wherever a person can answer, auto included,
and the prompt offers no “allow for this session” or “always allow”. An allow rule or a hook’s
allow does not skip it, and no guardian verdict approves it. In dontAsk and in headless runs the
call is denied. The audit record carries tier = ask_rule and
rule = anthropic/requiresUserInteraction; it never names the server or the tool. Any other value
("true", 1, false) is ignored. A deny rule still wins.
Once a server has marked a tool, the marker holds until that server’s connection ends (the next session), even if a later tool list drops it. A marker added by a later tool list takes effect when Fontaine refreshes the list.
Servers a repository defines
A server in a repository’s .fontaine/settings.toml or in its .mcp.json is an executable the
repository chose. A repository written for Claude Code works as it is: Fontaine reads its root
.mcp.json (mcpServers) as project scope. In the terminal UI:
- Before anything it defines can start, an untrusted workspace root gets the trust prompt. If you decline, the session runs without the repository’s servers and hooks, and the question comes back next session.
- In a trusted root each repository-defined server is then approved on its own, the first time it
would start: the prompt shows the command line or URL and, for a command, the names of the environment variables it asks to receive (never their values). Your approval is recorded in
<data dir>/trust.tomlfor that root, that name and that exact definition, so a server whose command, arguments, environment variable names or URL change is asked about again, and a repository cannot approve its own servers.
A headless run (fontaine -p) starts them without asking, as Claude Code’s -p does, unless
[headless] require_trust = true and the workspace is not trusted. In both
surfaces a project server’s tools are ordinary arbitrary tools, except that a tool can mark itself
as requiring your approval: a repository can add a server, but it
cannot make a call of that server run without the same approval any call needs, and it can only
make that approval stricter.
.mcp.json
Each entry takes type (stdio or http; absent means stdio for a command entry and http
for a url entry), command, args, env, url, headers and headersHelper. An entry
with type sse or ws is skipped with a warning, since those transports are not supported
yet. headers and headersHelper behave as in the key table: http only,
and a helper is refused in the project scope.
${VAR} and ${VAR:-default} in command, args, env values, url and headers values
are expanded when the server starts, from Fontaine’s environment. ${CLAUDE_PROJECT_DIR} is
the session’s workspace root, never a value inherited from a parent process. Because the text stays as written, the
approval prompt shows ${GITHUB_TOKEN} and never the value, lists the variables the definition
references next to its environment names, and the approval survives a rotated token but not a
changed reference.
- A credential variable is never expanded. A repository’s definition may not reference a
variable that holds a credential Fontaine knows of: the keys of your model accounts and the
telemetry credentials, the scanner’s Hugging Face token,
MICROMEGAS_*and OTLP header variables (the set tool subprocesses are scrubbed of), the web-search key and the well-known provider variables such asANTHROPIC_API_KEY. Such a reference fails that server’s start with an error naming the variable. In a headless run a repository’s server starts without asking, andurl = "https://host/${ANTHROPIC_API_KEY}"would otherwise hand a model key to a host the repository chose. (Claude Code expands any variable.) - An unset variable with no default fails only that server. The error names the variable, and the other servers start. (Claude Code fails the whole config parse.)
- Definitions in the TOML files are not expanded.
[[trusted]]
root = '/home/me/code/myrepo'
[[approved_servers]]
root = '/home/me/code/myrepo'
name = "github"
digest = "9f2c1c8e1a7d4b1f"
Authentication
A streamable HTTP server can require OAuth 2.1, as the MCP authorization spec describes. Fontaine drives the flow with the protocol library’s own auth stack; nothing about it changes how the server’s tools are judged.
fontaine mcp login <name> signs in to one configured server:
- It discovers the server’s protected-resource metadata and authorization-server metadata, registers itself with the server (dynamic client registration; Fontaine has no hosted client identity of its own), and prints the authorize URL to open in your browser.
- The server redirects to Fontaine’s loopback listener on the fixed port 3111, where the sign-in completes; the listener gives up after 5 minutes. PKCE protects the exchange.
- The token is stored under the server’s name in
<data dir>/credentials.toml, in a[mcp]table, through the same owner-only writer and cross-process lock as your other credentials. The entry also records the URL the token was issued for: a declaration whoseurldiffers from the stored one never receives the token, and fails with a message namingfontaine mcp login <name>— so a project reusing a user-scope server’s name cannot ride on its login.
While a token is valid it is sent as Authorization: Bearer and refreshed as it expires; a
refresh and a concurrent fontaine mcp login coordinate through the credentials lock, so they
cannot clobber each other. fontaine mcp logout <name> deletes the entry, including the
registration; the next login simply registers again.
A server that answers 401 while no usable token is stored fails permanently with
authentication required; run fontaine mcp login <name> — reconnecting cannot fix that, and a
headless run never starts the flow for you. The /mcp listing’s auth column
shows ok, required or n/a per server, and /mcp reconnect after a CLI login picks the new
token up.
Headers are the other way a remote server knows you. headers declares static headers on
an HTTP server (fontaine mcp add -H KEY=value, or headers = { ... } in a settings file;
headers in .mcp.json). They are sent on the server’s protocol requests only — never to an
authorization server’s token, metadata or authorize endpoints, which are a different origin and
use their own client — and a repository’s ${VAR} references in header values expand at start
under the same credential rules as its URL. headers_helper (headersHelper in .mcp.json)
names an executable run at connect time whose KEY: VALUE stdout lines become headers,
overriding static headers of the same name; Fontaine runs it only for scopes you control and
refuses it in the project scope, where a repository Fontaine merely opened must not make
Fontaine execute a script. Changing headers or headers_helper on an approved server
invalidates the approval, exactly like changing its URL.
The fontaine mcp command
fontaine mcp manages servers outside any session. You typed the command, so it needs no
permission; nothing it does starts a server the terminal UI would ask about first.
fontaine mcp add [-s local|project|user] [-t stdio|http] [-e KEY=value]... [--env-var NAME]... [-H KEY=value]... <name> <command-or-url> [args...]
fontaine mcp list [--connect=no]
fontaine mcp get <name> [--connect=no]
fontaine mcp remove <name> [-s local|project|user]
fontaine mcp login <name>
fontaine mcp logout <name>
addwrites the server to the scope’s file (localby default;projectwrites.mcp.jsonin Claude Code’s shape) and prints the confirmation andFile modified: <path>. A stdio server needs--before its own flags:fontaine mcp add github -- github-mcp-server stdio.-esets a literal variable on the server (env).--env-var NAMEpasses a variable of Fontaine’s environment through by name (env_vars), since Fontaine otherwise scrubs it; in.mcp.jsonit is written as"NAME": "${NAME}".-eand--env-varare for stdio only;-H KEY=valuedeclares a header for http servers only, repeatable, and is stored in the declaration. Adding a project server records no approval: the next terminal session asks. A name already in that scope is an error.-t sseis not supported yet (it is refused with a message naming the issue), and there is noadd-json.listprints one line per server,<name>: <command or URL> - <status>, in name order. The status isconnected (N tools),failed: <reason>,pending approval (run fontaine to approve)for a repository’s server you have not approved, ornot started: workspace not trusted. It starts exactly the serversfontaine doctorwould and no others, so a repository’s server is never started by the command.--connect=noskips the probes and the status readsnot checked.getshows one server: its scope and file, status, type, command, arguments, the names of the variables passed through, theenvkeys (values are shown as***), and the URL. It ends with the command that removes it (for a plugin’s server,fontaine plugin uninstall).removeremoves the server from the one writable scope that declares it. If several do, it exits 1 and lists the-scommand for each.-s projectremoves it from.mcp.jsonand from.fontaine/settings.toml. Plugin,--settingsandsettings.local.tomlservers are not writable scopes; the error names the file to edit or the plugin to uninstall. An approval left intrust.tomlis inert.loginsigns in to a streamable HTTP server with OAuth, as described below;logoutdeletes the stored token.
Exit status: 0 on success; 1 for an unknown name, a duplicate, an ambiguous remove or an I/O
error; 2 for a usage or configuration error.
Protocol versions
Fontaine starts each server by asking it for server/discover and falls back to the older
initialize handshake when the server does not know that request. A server that supports only
protocol 2026-07-28 and rejects initialize therefore connects. A legacy server that answers the
probe with “method not found” falls back at once; one that never answers it delays the connection
by up to 10 seconds before the fallback. The whole start, including the first tool list, shares
the 30 second connection deadline. A server whose tools/list fails does not connect: the attempt
ends at that 30 second deadline, the server is reported as failed, and /mcp reconnect restarts it.
Requests for input
A server can ask you for input while a tool runs (MCP elicitation). Fontaine supports the form mode: the terminal UI shows a dialog with the server’s message and one row per field the server asked for (text, number, whole number, yes/no, a choice, or several choices), checks what you type against what the server required, and sends your answer back to that server. You can fill the form in, decline it (the server carries on without the input) or cancel it (the server stops what it was doing). The keys are in the terminal UI.
Fontaine also serves the URL mode: a server can ask you to open a link. The terminal UI shows the
server’s message, the link and a warning that it goes to an external site the server chose, and
opens it in your default browser only when you confirm with y. Only http and https links are
accepted; any other scheme is declined before you are asked. The link is never opened on the
server’s say-so, and there is no “always allow”: every request is confirmed. The keys are in
the terminal UI.
- Only the terminal UI shows a dialog. A headless run, AFK mode,
the doctor probe and a call made by a subagent answer
cancelwithout showing anything, unless anelicitationhook answers first (not for the doctor probe or a subagent’s call). A hook never accepts a link: that is always confirmed in the terminal UI. The dialog closes, and is answeredcancel, when the call that caused it ends. - Your answer goes to the server and nowhere else. It never reaches the model, the transcript, the audit log or telemetry, and the dialog says so. Don’t enter secrets you wouldn’t give that server. The server’s message is cleaned of control characters before it is shown.
- It decides nothing. Answering never changes a permission decision; the call that led to the request was already approved like any other.
A server can ask for input in either of the two forms the protocol has: as a request to the client while a call runs, or, at protocol version 2026-07-28, as a result that says the call needs input first. Fontaine serves both with the same dialogs and the same limits. For the second form it retries the call with your answer, and the server may ask again; a call is given up after 10 requests in total. A server that asks for something other than a form or a link (a model sample or the list of roots) fails the call, because Fontaine offers neither.
Long-running tool calls (tasks)
At protocol version 2026-07-28 a server that supports the tasks extension can answer a tool call with a handle to a task it keeps running, instead of the result. Fontaine declares the extension when it connects and handles the handle itself: it asks the server for the task’s state at the interval the server suggests (never faster than every 50 ms or slower than every 5 s; once a second when the server names none) until the task ends, and the model sees the tool’s result or error as for any other call. Only tool calls can become tasks; a task handle for a prompt or a resource fails that call.
- The call’s timeout and your interrupt apply. When the call times out or you interrupt it, Fontaine tells the server to cancel the task. Fontaine also cancels the task when it has to give up on the call itself.
- A task can ask for input. A task that needs you is served through the same dialogs as any other request for input, and your answer goes to the task. The same limit applies: the tenth request for input fails the call, after nine answers.
- A failed or cancelled task is an error. The server’s error is shown as the call’s error. A completed task whose result is an error result is a normal tool error.
Reconnecting
A remote (streamable HTTP) server that drops mid-session is reconnected. Fontaine notices when a
tool call fails because the transport is dead, or when the connection ends, closes it and retries up
to five times, waiting 1, 2, 4, 8 and 16 seconds before the attempts. Each attempt has a 30 second
limit. While it retries, /mcp shows the server as pending (reconnecting, attempt N of 5) and its
tools are withdrawn; a success registers them again and says so in the terminal UI. An
authentication or protocol error stops the retries at once, since waiting cannot fix it. After the
last attempt the server is marked failed:
MCP server `docs` disconnected · run /mcp reconnect docs
In a headless run (fontaine -p, including the stream-json surface) a remote server whose five
attempts failed on a transient error is not given up on: Fontaine keeps retrying in the background,
waiting 32 seconds and then a minute between attempts, for 30 minutes from the moment the connection
was lost, and registers the tools again when one connects. /mcp shows the server as
pending (retrying in the background) meanwhile, and the stream-json mcp_servers status says
pending. A permanent error, or the end of the 30 minutes, marks it failed with the warning above.
An interactive session marks a stdio server that exits failed straight away and does not start its
process again; /mcp reconnect does. A headless run has no one to ask, so a stdio server that
exited mid-session is started again the next time the model calls one of its tools: its tools stay
registered, the call goes through the permission gate as usual, and only an allowed call starts the
server (from the definition it was first started with, never re-read from configuration) and then
runs on it. Until then /mcp lists it as failed: the server exited · restarts on next call. A
server is restarted at most three times per run; after that its tools are withdrawn and it stays
failed (exited more than 3 times). A restart that fails returns the connection error as that
call’s error and leaves the tools in place for a later call. A server that failed to start in the
first place is not restarted this way.
/mcp reconnect <name> restarts one server, connected or not, at once and without waiting;
/mcp reconnect all restarts every failed server. Only servers Fontaine tried to start this
session can be restarted, including ones that failed at startup. A server you left off, or that
the workspace not being trusted keeps from loading, is never started this way, so the command cannot
get around workspace trust or your approval. It is not available while a turn runs.
Large outputs
A successful tool result that is too large is saved to a file instead of entering the model’s
context. The limit is 50,000 characters or MAX_MCP_OUTPUT_TOKENS tokens (default 25,000, counted
as the result’s bytes divided by 4), whichever is hit first. The result is written in full to
<scratch>/mcp-results/<tool>-<n>.txt, in the session’s scratch directory, and the model gets this
instead:
Output too large (60000 chars, ~15000 tokens), saved to <path>. Use read or grep on that file to see it.
The model reads the file with read or grep like any file in the workspace, and the content is
screened then like any other read. The file is removed with the session. A tool can raise the
character limit for its own results by setting _meta["anthropic/maxResultSizeChars"] to a positive
integer in its tools/list entry, up to 500,000; the token limit still applies. Anything else is
ignored.
If the session has no scratch directory, or the file cannot be written, the result keeps its first
and last halves of the limit with a [… N chars cut …] marker between them; Fontaine warns once
when a save fails. A result a server flags as an error (isError) longer than 11,000 characters keeps its
first and last 5,000 characters with the same marker. A result that carries an image is passed
through unchanged. A result under both limits but over 10,000 tokens comes through in full, with a
warning that names the tool and the size, as Claude Code warns. MAX_MCP_OUTPUT_TOKENS is described under
environment variables.
Telemetry
Starting a server emits an mcp_server_connection event, and so does each reconnect attempt, and
each call a fontaine.mcp.call span. Answering a request for input emits an mcp_elicitation
event with the action (accept, decline or cancel) and the server, never the message or the
answer.
Server and tool names appear in them, and in every other tool field, only when
log_tool_details = true; otherwise they read third-party. See Telemetry.