MCP
How Fiber uses MCP servers: what it starts, what the model sees, how a call is
judged, and what happens when a server fails. It is settled by
MCP client; the reasoning and
the rejected alternatives are
ADR 0008. What reference
agents do is in research/mcp-client/.
Vocabulary is GLOSSARY.md. MCP server, tool call, effect, workspace, driver,
driver command, session and event mean what it says there and nothing else.
What Fiber does with MCP
Fiber is an MCP client. The client is built into the binary, as the wire
protocols in docs/model-routing.md are. Fiber serves no MCP
for delegating to Fiber
(ADR 0005).
Fiber speaks two transports:
- stdio, for a server Fiber starts as a child process
- streamable HTTP, for a remote server
It has no legacy HTTP with server-sent events (HTTP+SSE).
A remote server that needs OAuth uses MCP's OAuth flow, which the client
carries (ADR 0008). A person logs in
to a server with fiber mcp login <server>, and fiber mcp logout <server>
deletes the stored token. Both look up the server's URL from its
configuration. fiber mcp login follows MCP's authorization flow: it reads the server's protected-resource and authorization-server metadata, registers itself as a client, and opens the browser on a PKCE authorization with a loopback callback, then stores the token; with no callback within 15 minutes it fails authentication_failed and stores nothing. A server a repository declares that is not approved is refused mcp_server_unapproved with the advice fiber approve, since the URL it would open is the repository's choice. Login uses the first authorization server the server's protected-resource metadata lists; a server with no such metadata is its own authorization server, at its URL's origin. Login refuses an authorization server whose metadata does not list S256 among its code challenge methods, because MCP's authorization flow requires PKCE. The token is stored by that URL, not by the server's name, at
credentials/mcp/<hash>, where the hash is the lowercase hex SHA-256 of the
canonical URL's bytes. The file records the URL itself (docs/state.md,
"What each part holds"). Fiber canonicalizes the URL by lowercasing the scheme
and host, dropping the scheme's default port and any fragment, and keeping
the path (including a trailing slash) and query byte for byte. Two server names
share a token only when their canonical URLs are equal. A token is
only ever sent to the URL it was issued for, whatever name a configuration or a
repository gives the server, and one login serves every project that uses
that server. Token refresh follows the provider
rule in docs/model-routing.md, "Credentials": lock the credential file,
re-read it, refresh once. A headless start with no valid token counts as
the server failing to start (see Starting servers).
Fiber sends the stored token as Authorization: Bearer on every request to
that URL, and none when nothing is stored. HTTP 401 during initialize,
notifications/initialized, or a tool or prompt list fails the start
mcp_server_failed. An unusable stored login or a rejected refresh fails it
with the same code. Every door gives the advice fiber mcp login <server>;
a required server instead fails the run mcp_required_server_failed.
A call that meets HTTP 401 mid-session fails with the same login advice.
A session DELETE answered HTTP 401 is ignored.
Fiber is an MCP server in one place: fiber mcp serve, which a delegate on
another harness uses to send session messages (docs/delegates.md,
"Delegates on another harness"). Not built yet: see #600.
Tools and their names
Each tool a server offers becomes a Fiber tool named mcp__<server>__<tool>.
A name longer than a protocol
allows is cut short and given a short hash suffix, so two long names stay
distinct.
Measured limits are in research/mcp-tool-names/: 128 characters on
Anthropic Messages, Codex Responses, OpenAI Responses and Google Generative
AI, and no limit found below 1,024 on a completions relay. Fiber cuts a name
longer than 128 characters to 128, ending in _
and 8 hex characters of SHA-256 over the full name.
MCP tools register through the tool seam like any built-in
(docs/architecture.md, "Tool seam"). The seam's rule applies unchanged:
registering an existing name replaces it, and the replacement is recorded in the
session log. An extension can replace any MCP tool, or mcp_resources, by
registering its name. An extension's replacement of an MCP tool holds when
the server's tools load later, and that later load adds no entry to
preamble_built's replaced for the name.
The tool set is fixed when the preamble is built (docs/tools.md, "Which
tools the model sees"). A resumed session declares its servers' tools from
their cached lists, as any session does at start ("Starting servers"). Tools
are sorted by name, with every schema's keys sorted (docs/prompt-cache.md,
"Bytes"). The set changes only when a preamble is built: at start, on a model
switch, and on reload. Changing tool definitions
mid-session misses the whole prompt cache.
Deferred tools
On a model that supports deferral, MCP tools are declared deferred by default:
the model sees each tool's name and loads its full definition with
tool_search when it needs it. On any other model every tool is declared in
full; OpenAI's allowed_tools restricts calls but still sends each definition.
A server can be marked declare_in_full, so its tools are always declared in full.
Why deferral keeps the cache is docs/prompt-cache.md. Which models defer,
tool_search, and which tools the model sees in general are
docs/tools.md, "Which tools the model sees".
Effects
An MCP tool's effects come from the hints its server declares for it, in the
vocabulary of docs/permissions.md:
| Hint | Effect |
|---|---|
readOnlyHint true | reads, reversible |
destructiveHint true | writes, irreversible |
destructiveHint false | writes, reversible |
openWorldHint true, or absent | adds network |
| any remote (HTTP) server | adds network |
neither readOnlyHint nor destructiveHint | executes, irreversible |
A tool with no hints at all therefore declares executes and network,
irreversible, so auto sends every call to it to the reviewer. Configuration
can override any tool's hints.
The hints are believed, on the same grounds as an extension's declarations. The
person installed the server, and docs/permissions.md says of extensions: "An
extension runs with the account's full rights, so misdeclaring buys it nothing
it could not do directly."
MCP hints are per tool, not per call. That is weaker than docs/permissions.md
asks: "Classification is per call, not per tool." MCP offers nothing per call,
so Fiber cannot do better. Every call to one MCP tool declares the same effects,
whatever its arguments.
An MCP tool declares no paths. A reads call takes the permission fast path. A
writes call never does, because both write fast paths need the paths a
call writes. The credential deny (docs/permissions.md, "Credentials") cannot
see what an MCP tool touches, as it cannot for a shell command it does not
recognize.
Prompts and resources
A server's prompts become prompt templates. They appear in the terminal's /
list beside skills, tagged with the server's name, and a person runs one by
typing its /name with arguments. Fiber asks the server for the prompt's text
and sends it as the person's message (docs/system-prompt.md, "Skills").
The words after the name fill the prompt's arguments in the order the server
lists them, one word each, and the last argument takes the rest of the text.
An argument with no text is left out. A required one left out rejects the
prompt invalid_arguments, naming what it needs, and the server is not
asked. For a prompt with no arguments, the text after the name follows the
prompt's text after a blank line, as for a skill.
Fiber sends the text of every message the server returns, in order, joined by a blank line, whatever its role; an embedded text resource counts as text. An answer with other content, such as an image or a resource link, or with no text, is not sent.
When Fiber cannot get the prompt's text, the prompt is rejected
mcp_prompt_failed, naming the cause, and nothing is sent to the model.
Getting the text waits for the server as a tool call does, under its startup
deadline and call timeout; no turn is running yet, so cancel does not reach
it, and a shutdown does.
A server's resources are reached through one tool, mcp_resources, with two
actions:
list, which lists the resources a server offersread, which reads one resource
mcp_resources is declared only when at least one configured server offers
resources. Its effect is reads, plus network for a remote server.
A server offers resources when its initialize reply advertises the resources capability. list with no server names the servers that offer resources and starts none. With a server, it lists one page of that server's resources, and an answer with a nextCursor is continued by passing it as cursor. read reads one resource by its URI, whether or not list showed it, and its content is mapped as a tool result's is ("Calls"). mcp_resources is listed as built in, and its definition counts toward the built-in budget (docs/tools.md, "Size budget in CI"). An extension replaces it as it replaces an MCP tool ("Tools and their names").
Calls
Each call has a timeout, 10 minutes by default, the same as the shell's
timeout_ms (docs/tools.md, "Timeout"). Configuration can change it per
server. A call that times out ends failed with code timeout.
Cancelling a turn sends MCP's notifications/cancelled for each call in
flight and stops waiting. The call ends failed with code
mcp_cancel_requested: Fiber asked the server to stop, and the server may still
act. MCP says a server receiving that notice should not respond, so Fiber never
learns whether the server stopped, and the call is never cancelled
(docs/tools.md, "Cancellation").
A result goes through the tool contract in docs/tools.md:
- text goes to
content - a resource link becomes one line of text giving its URI, name and MIME type;
mcp_resourcesreadfetches it ("Prompts and resources") - an embedded text resource becomes text
- an embedded image takes the path
readtakes for an image (docs/tools.md, "read") - an embedded PDF is saved to
artifacts/, and the model gets one line giving its path and size. It reads it withread, which handles PDFs (docs/tools.md, "read"), as it does a PDFweb_fetchsaves - other binary content is written to
artifacts/; audio is written there when it has data, and the model gets one line giving its MIME type, size and path - unsupported or unreadable top-level content parts in tool results and resource reads become the text “Unsupported content.”
- an image is processed once (
docs/model-routing.md, "Image limits") and goes tocontentas an image part, written toartifacts/ - an image that cannot be read, or is over 50 megapixels, ends the call
failedwith codeunsupported_fileand the decoder's message (or the pixel count) - the 16 KiB cap applies, and a cut result keeps its full bytes in an artifact
- a result the server marks as an error ends
failedwith codetool_error
Starting servers
Settled by MCP servers start on first call.
A server starts on the first call to one of its tools, the first mcp_resources call that names it, or the first time a person runs one of its prompts. The model sees its tools from the session's
first request all the same: they are declared from the server's last tool
list, cached in Fiber home at cache/mcp/<server>.json, with its last prompt
list (docs/state.md). The cache is keyed by a hash of
the server's declaration: its command, arguments, environment, or URL. The
first call waits for the server to start and list its tools, up to its startup
deadline. The handshake lists tools only when the server advertises the
tools capability, and prompts only when it advertises prompts. It records whether the server advertises resources, and the cache keeps that with the lists; a cached file without that record counts as offering none. A server
advertising only prompts starts with no tools. The deadline is 5 seconds by default, and configuration can change
it per server.
Some servers start with the session:
- a server marked
required. Arequiredserver that misses its deadline, or fails to start, stops the session starting, and a headless run exits with code 1 and error codemcp_required_server_failed. - a server with no cached list for its current declaration: the first time it is used, and after its declaration changes. It starts to get the list, and stays running. A cached file without a prompt list counts as no cached list.
The first request to the model waits for these, and a person can type while they connect.
A server that fails to start is recorded as the durable event
mcp_server_failed (docs/events.md), whose error.message is Fiber's own
sentence and says what to do, such as how to log in, so a person and a
headless caller read the same advice. For a server started on a call, the
call fails with that error and the server is treated as one that died ("When
a server dies"). For a server started with the session for want of a cached
list, its tools are left out for the whole session.
When a started server lists different tools from the cached list, the
session keeps the tools it declared, because a tool set that changes
mid-session misses the whole prompt cache. The cache is updated, so the next
session declares the new list. The session keeps the prompts it listed at
start, as it keeps its tools. A call to a declared tool the server no longer
has fails with mcp_tool_removed.
The 5-second deadline:
- The MCP specification sets no number. It says only "Implementations SHOULD establish timeouts for all sent requests".
- The owner's three local servers took 82 to 105 ms median, 143 ms at most,
from launch to their tool list (macOS arm64,
research/mcp-client/). - A cold
npx -ystart or a slow OAuth exchange can miss it. That server's configuration raises it.
A stdio server starts in the session's workspace, in its own process session
and process group, so a terminal's Ctrl+C never reaches it and a shutdown
signals everything it started (docs/invocation.md, "Shutdown").
Each server pipe takes one parked thread, and a remote server one, plus one for each request in flight, as docs/architecture.md ("The threads") already budgets.
When a server dies
A server that dies mid-session is restarted once, on its next use: a tool
call, prompt, or resource read. Each death is recorded as mcp_server_failed,
and a restart that brings it back as mcp_server_ready. If it dies again, it
stays dead for the rest of the session. Its tools
stay declared, so the prompt cache holds, and every call to them fails with code
mcp_server_unavailable.
A remote server dies when a request's connection fails, or a response ends
without its answer or runs past 4 MiB. A remote server that ends its
session, answering HTTP 404 to a request that carries the session it gave,
has not died: the call that saw it fails with mcp_server_unavailable, and
the next call starts a new session without using the restart. A 404 to the
first request of a new session counts as a death, so a server that answers
404 to everything does not start new sessions forever.
A server's notice that its tool list changed is ignored until reload. A tool the
server removed fails with code mcp_tool_removed. A tool the server added is
not declared.
Reload
reload is a driver command (docs/invocation.md). The terminal and every
driver have it, because docs/architecture.md gives the terminal no privilege
a second client lacks.
Reload:
- Re-reads configuration.
- Keeps unchanged, healthy servers connected, and asks each for its tools, and its prompts when it advertises them, again.
- Restarts changed servers and servers that died.
- Starts every server not yet started this session, to get its tools.
- Updates each server's cached tool and prompt lists.
- Reloads extensions (
docs/extensions.md). - Declares the new tool set.
It costs one prompt-cache miss. The log records it as the durable event
reloaded (docs/events.md).
Servers, their state and the per-server commands
mcp_servers is a driver command (docs/invocation.md) that answers with
every configured server: its name, the layer that declares it (global,
project or repository), its state, the failure's sentence when it
failed, its tool count, and for a repository's server whether it is
approved. The state is one of:
not-started: declared but not started this session, and no failure recorded. Servers start on first use ("Starting servers"), so a server nothing has called yet isnot-started, cached tool list or not.ready: running, with its tools declared.failed: the last start failed, and the row carries themcp_server_failederror.messagesentence ("Starting servers").needs-login: the last start failedNotLoggedInwith no latermcp_server_ready.
The tool count is the rows the tools driver answer declares for that
server (docs/tools.md, "Seeing the tools"), so the two views never
disagree; a not-started server shows no count until it lists.
mcp_reconnect is a driver command that restarts one failed server, as
reload restarts changed and dead servers above, and answers with its
outcome. It restarts only the server it names. A reconnect for a server that
is already starting or ready starts nothing and is still accepted, so
reconnects in quick succession start the server once. It is rejected busy while
a turn runs, invalid_arguments for a server nothing declares, and
mcp_server_unapproved for a repository's server nobody approved, with the
advice fiber approve, since the session would never start it ("A
repository's servers").
mcp_login is a driver command that runs for one server the login fiber mcp login runs ("What Fiber does with MCP"): it opens the browser on the
PKCE authorization with a loopback callback and waits for the callback,
then stores the token and starts the server. While the login waits, that
server's mcp_servers row carries auth_url, the login URL to open by
hand. The command is accepted at once and answered when the login ends:
authentication_failed when the callback never comes or the exchange
fails, storing nothing. It is rejected invalid_arguments for a server
nothing declares, mcp_server_unapproved for a repository's server nobody
approved, with the advice fiber approve, and busy when a login for that
server is already in flight.
Elicitation, sampling and roots
A server can ask the person a question in the middle of a call. This is MCP
elicitation, and Fiber answers it. An elicitation is an interaction like any
other: Fiber raises it on the event stream as one of the interactions
docs/architecture.md already names, logged as interaction_requested and
interaction_resolved (docs/events.md, "Interactions"), and any driver
answers it with reply.
Fiber advertises form elicitation. The server sends a form of typed fields. Fiber asks each field in turn, in the order the server lists them:
| Field type | Interaction |
|---|---|
| boolean | confirm |
| enum | select |
| string, number or integer | text input |
A typed answer that is not a number for a number field, or not a whole number for an integer field, or that is outside the field's limits, is rejected invalid_arguments, and the field stays pending. An elicitation Fiber cannot show, such as one with a field of another type or a malformed schema, is answered with a JSON-RPC error, and nothing is logged. A declined optional field is left out of the answers and the rest is still accepted; a declined required field declines the whole elicitation. Each field's prompt names the server that asks.
When no answer is possible, Fiber declines, which is a response MCP defines.
That is the same case as an escalation's block (docs/permissions.md,
"Headless"): a session started by fiber ask, a delegate, or one that has
been sent close. Otherwise a pending elicitation waits for a client within the call's
timeout ("Calls"); an elicitation does not extend it. An elicitation in a
delegate is declined, because a delegate never waits on a person
(docs/delegates.md, "Lifetime").
On stdio, an elicitation carries nothing that links it to the call that raised
it: the MCP TypeScript SDK 1.29.0 passes relatedRequestId to its transport
(shared/protocol.js:337), and the stdio transport's send(message) drops it
(server/stdio.js:63). Each session has its own servers ("Where servers
run"), so an elicitation always belongs to the session that started the
server. When that session has more than one call in flight on the server, its
log records the elicitation with the action_id of each. An elicitation that arrives with no call in flight on its server is declined, and nothing is logged. Fetching an MCP prompt is not a call: an elicitation that arrives during one is declined.
Fiber does not advertise sampling and does not answer a sampling request.
Fiber does not advertise roots.
A repository's servers
A server declared in a repository's configuration runs a program, so it
follows the rule for all code a repository ships (docs/extensions.md, "Code
a repository ships"): the session that would start it offers it before its
first model request, showing the server's declaration, and any client can
answer (docs/tui.md, "Approving what a repository ships"). With nobody to
ask, an unapproved server is skipped with a notice, and a required one
fails the run with mcp_server_unapproved. fiber approve, run in the
repository, approves it outside a session. A remote server a repository
declares is approved the same way; its approval covers its declaration, URL
included.
An approved server starts with the session as any server does. One approved
in the session's own offer starts once the offer is answered, before the
first model request; a required one that then fails ends the run with
mcp_required_server_failed. Its tools are declared then; its prompts join the / list at the next
reload or process start.
The approval covers the server's exact declaration and each file its
command or args names inside the repository. Fiber copies those files into
Fiber home and starts the copy, so a changed declaration or a changed file
needs a new approval. Approvals are recorded per machine (docs/state.md,
"What each part holds").
fiber mcp add --repo writes the declaration to the repository and records
the approval of that exact declaration for the person who ran it. Another
person who gets the declaration with the repository has no approval on their
machine, and is asked.
An imported server is not a repository's server: it lands in the global layer, so no repository approval attaches to it, and the approval flow above is unchanged.
The approval does not cover what the program fetches or reads while it runs.
A declaration that fetches its program at start, such as npx -y, can run
different code later under the same approval, and a server that loads other
files of the repository loads them as they are now.
The tool-list cache ("Starting servers") is keyed by the declaration alone. It is a different hash from the approval's, which also covers the pinned files.
Error codes
The mcp_* codes are listed with every other code in docs/errors.md.
Configuration
Each server has:
- a command, arguments and environment, for a stdio server; a secret goes in
the environment as
{ "secret": "<name>" }(docs/configuration.md, "Keys") - a URL, for a remote server
required- a startup deadline
- a call timeout
- whether its tools are declared in full (
declare_in_full) - per-tool hint overrides
- which tools are enabled and which are disabled
The keys are docs/configuration.md ("MCP servers").
A url that carries a user name or password is a configuration error naming
the server, config_invalid: the server is not started, and a required one
fails the session.
fiber mcp add declares a server and fiber mcp remove removes one. Each
writes the global configuration, or the per-project file with --project, or
the repository's .fiber/config.json with --repo (docs/invocation.md,
"Commands and flags"). fiber mcp list lists every declared server, the layer
that declares it, and for a repository's server whether it is approved. Any
other field is set with fiber config set.
An import from another harness (docs/configuration.md, "Importing") lands
here too: each imported entry becomes a user-scope server in the global
layer, with the source field map command to command, args to args,
string env values to env, url to url, and required only when the
source declares it. A secret value, auth block or token is refused to the
left-behind list, never stored. An imported server starts unapproved, as any
server the person declares does; approving what a repository ships is
unchanged ("A repository's servers").
Where servers run
Every session is one process (ADR 0009), and every session starts its own servers, a delegate included. Nothing is shared between sessions.
- A server starts in the workspace of the session that started it, so a delegate in a worktree gets servers that work in that worktree. The owner's cursor-delegate server works in the folder it started in unless a call names another, and node_repl keeps a JavaScript kernel whose variables persist between calls. Neither would be correct shared between sessions.
- A server takes 43 to 93 MiB written in Node and about 1.2 MiB written in
Rust (macOS arm64,
research/delegate-memory/README.md, "MCP servers"), once per session that calls it. Fiber assumes the heavy end: a delegate that calls two Node servers adds about 100 MiB. A server a session never calls costs it nothing, because servers start on their first call. A server that costs too much to run once per session is its author's to make smaller; Fiber does not share servers to hide the cost. - A delegate starts its own servers as any session does ("Starting servers"). Servers are not moved into the hub: a hub restart would restart them under running sessions, and the two above would be wrong shared.