Implemented on dev/0.10.0.
This plan changes MCP configuration, ownership, error handling, and user-facing connection boundaries. It preserves the current protocol-mode product behavior while simplifying the integration around the stable-v2 SDK.
- Keep
mcp.serversas the only persisted central server collection. - Keep
mcp.servers.<name>.targetas shorthand alongside expanded server definitions. - Remove
mcp.targets; do not retain two collections with implicit precedence. - Treat the
mcp.serversmap key as the server's sole identity. - Reject shorthand entries that also specify a competing connection source.
- Make
mcpa real namespace for MCP defaults, client policy, and diagnostics. - Separate reusable server definitions from live agent attachments.
- Track whether a definition came from central config, an AgentCard, or a runtime command instead of mutating loaded settings.
- Use a shared declaration model for central config and AgentCards, while applying AgentCard trust policy separately.
- Validate the work through a small set of end-to-end configuration and runtime scenarios, not parallel collections of normalization micro-tests.
- Use one SDK client gateway for persistent and request-scoped connections, including one OAuth escalation policy.
- Preserve typed SDK/HTTP failures until recovery has been decided; render user guidance only at the command/UI boundary.
- Make attachment transactional: a failed connection never publishes a definition, mutates loaded settings, or damages an existing attachment.
- Normalize startup
--url/--npx/--uvx/--stdio, terminal/connect,/mcp connect, and ACP through one target grammar and materializer.
The current configuration accepts both:
mcp:
targets:
- name: docs
target: "https://example.com/mcp"
servers:
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "."]mcp.targets and mcp.servers.<name>.target describe the same concept through
different collection shapes. This causes several problems:
- the list form has weaker layered-config and secrets merge behavior;
- durable names may be inferred from targets instead of being explicit map identities;
mcp.serverssilently wins when both collections resolve to the same name;- schema and editor tooling cannot describe arbitrary list-derived keys well;
- normalization immediately discards the user's shorthand source form;
- runtime code cannot reliably explain where a definition came from;
- AgentCards use another, narrower declaration model and then promote entries into a process-global registry.
The nesting under mcp remains worthwhile only if it becomes a coherent MCP
policy namespace rather than a wrapper around two competing server lists.
The configuration review was followed by a direct audit of the stable-v2 MCP runtime, command handlers, CLI adapters, and focused tests. The following are current implementation facts, not hypothetical concerns.
MCPClientConnectioncomposes the publicmcp.client.Clientrather than reimplementing negotiation, discovery/adoption, MRTR, cache behavior, or ordinary protocol requests.- Modern subscriptions use the SDK's public
Client.listen()andSubscriptionLost. - URL elicitation and the directory-read extension are isolated additions on top of the SDK client.
- Stdio startup diagnostics retain bounded recent stderr and distinguish common executable/cwd failures.
- Runtime connect already has useful OAuth progress events, cancellation behavior, auth redaction, and structured command outcomes.
protocol_modemaps cleanly to SDK modes; modern request resumption remains SDK-owned.
These seams should be retained. The refactor should remove duplication around them, not replace them.
ServerSessionTerminatedError.SESSION_TERMINATED_CODE is currently 32600.
Stable MCP v2 emits the public mcp_types.INVALID_REQUEST value, -32600, with
message Session terminated when a legacy Streamable HTTP session receives the
relevant 404.
The current comparison in
src/fast_agent/mcp/client_connection.py:MCPClientConnection._interactive_operation
therefore cannot recognize the stable-v2 error. Automatic legacy session
replacement is bypassed even when reconnect_on_disconnect is enabled.
The correction must:
- import the public SDK/types constant rather than copy its numeric value;
- match both the code and the SDK session-termination message so unrelated invalid requests are not treated as disconnects;
- apply only to the legacy protocol path;
- prove one replacement and at most one safe replay with a real HTTP simulator.
This is an immediate correctness patch, independent of configuration migration.
MCPAggregator._execute_session_method catches nearly every exception and may
convert it through error_factory before _execute_on_server can classify
OAuth, transport, or session recovery. The outer recovery policy therefore sees
some infrastructure failures but receives ordinary result objects for others.
Recovery must operate on the original typed failure before any agent-facing
CallToolResult(is_error=True) or other fallback result is created.
Server-declared tool errors remain ordinary MCP results. Infrastructure errors remain exceptions through the final permitted recovery attempt, and only the terminal boundary converts them when the calling API requires a result.
Current startup and command paths classify some failures using strings such as
"401 unauthorized", "oauth", "timeout", and registration-404 phrases:
MCPConnectionManager._is_http_auth_challenge_error
MCPConnectionManager._is_oauth_timeout_message
commands.handlers.mcp_runtime._classify_connect_failure
This is fragile after exception groups and traceback formatting have erased types. A single recursive exception walker should inspect:
HTTPStatusError.response.status_codeand headers;MCPError.code, message, and data;- known OAuth exception types;
ExceptionGroupmembers and__cause__/__context__.
String matching remains only a compatibility fallback for third-party exceptions that expose no structured signal. It must not be the primary source of retry decisions.
Persistent initialization in MCPConnectionManager, temporary initialization
in ServerRegistry.initialize_server, and operation recovery in
MCPAggregator each own part of auto-OAuth escalation.
This makes it difficult to prove that:
- the first auto attempt is credential-free;
- only a genuine HTTP authentication challenge enables OAuth;
- escalation happens at most once;
- explicit auth headers remain authoritative;
- probe and persistent behavior are identical.
OAuth transport/provider behavior should continue to use the SDK provider. Fast-agent should own exactly one connection-attempt policy around that SDK provider.
MCPConnectionManager.disconnect_server() removes the runtime from
running_servers, sets its shutdown event, and returns before the lifecycle
task has exited. Reconnect and manager shutdown compensate with fixed
asyncio.sleep(0.1) and asyncio.sleep(0.5) delays.
This permits overlap between old and replacement clients and makes cleanup timing dependent on the host. Each managed runtime needs a completion signal. Disconnect must await SDK client, transport, process/HTTP client, callbacks, and lifecycle-task completion before reporting success. Reconnect starts only after that barrier; no correctness path uses a fixed sleep.
Unexpected shutdown failures should remain observable. Manager __aexit__
must not broadly swallow them after logging.
ServerRegistry.registry aliases Settings.mcp.servers directly.
get_server_config() mutates the selected model to fill name.
MCPAggregator._resolve_attach_server_config() inserts ad-hoc settings and
persists attachment-local reconnect overrides before connection and discovery
succeed.
Consequences:
- a failed
/connectcan leave a configured-looking registry entry; - a reconnect override can change later attachments;
- card/runtime publication mutates loaded central settings;
- an existing same-name entry can be replaced before the replacement is known to work.
Declarations must be immutable inputs. A runtime definition and attachment are published together only after successful connection/discovery, or staged in a transaction that can be rolled back without reconstructing prior maps.
Aggregator recovery methods import fast_agent.ui.console and print reconnect,
authorization, and failure text. That couples MCP semantics to one surface and
causes terminal, ACP, and startup behavior to diverge.
The runtime should emit typed lifecycle/progress events. Terminal, ACP, and CLI adapters render the same event and failure data for their medium.
Startup --url uses cli.commands.url_parser and startup stdio flags use
cli.runtime.request_builders; /mcp connect and terminal /connect use
mcp.connect_targets.
Observed differences include:
- malformed startup stdio input is printed and skipped instead of failing the requested run;
/mcp connect docschanges meaning depending on current registry contents;- terminal
/connectis an alias, but ACP does not expose it; - help omits accepted options such as
--protocolin some places; - status command meaning differs across terminal and ACP;
- generic initialization guidance says
Check fast-agent.yaml?even for an ad-hoc URL or command; - URL normalization silently appends
/mcpwhen the supplied URL does not end in/mcpor/sse.
All public adapters should produce the same source-aware connect request and consume the same structured outcome.
flowchart LR
Sources["YAML / AgentCard / CLI / slash command"]
Parser["MCP declaration + target parser"]
Policy["Origin trust + defaults"]
Catalog["Origin-aware definition catalog"]
Attach["Transactional attachment service"]
Gateway["SDK client gateway"]
SDK["mcp.client.Client"]
Runtime["Managed runtime"]
Events["Typed lifecycle events/failures"]
Surfaces["Terminal / ACP / CLI"]
Sources --> Parser --> Policy --> Catalog
Catalog --> Attach --> Gateway --> SDK
Gateway --> Runtime
Runtime --> Events --> Surfaces
Attach --> Events
- preserves source form;
- parses a target once;
- validates source exclusivity;
- applies defaults and origin-specific trust;
- produces immutable effective
MCPServerSettings; - has no registry, SDK, lifecycle, or UI dependencies.
- stores immutable declarations/effective settings with origin and owner;
- performs collision checks;
- does not open MCP clients;
- does not mutate
Settings; - does not track tools, prompts, or connection health.
ServerRegistry.initialize_server() moves out of this layer. The existing
ServerRegistry is either reduced to this responsibility or replaced by an
explicit MCPServerCatalog.
- is the only place that creates transport contexts and
MCPClientConnection; - uses public SDK
Client, OAuth provider, exceptions, constants, and subscription APIs; - owns one connection-attempt/OAuth-escalation policy for persistent and request-scoped clients;
- returns typed initialization metadata and preserves original exceptions;
- does not publish definitions or render user messages.
- owns live SDK client/transport/process resources;
- has explicit
starting,ready,stopping, andcompletedlifecycle barriers; - guarantees one runtime per attachment identity;
- awaits teardown before replacement;
- leaves modern request resumption and protocol negotiation to the SDK.
Legacy keepalive remains fast-agent policy only where the SDK has no equivalent durable behavior. It is not run for modern clients.
- resolves a catalog definition or stages an ad-hoc definition;
- applies attachment-local policy without rewriting the definition;
- opens and discovers through the gateway/runtime manager;
- atomically publishes the live attachment and resource indexes;
- rolls back every staged change on failure or cancellation;
- removes session-owned definitions when their final attachment is removed;
- retains central/card definitions after detach.
Keep SDK and transport exceptions intact inside the gateway/runtime. At the product boundary, normalize them once into a small immutable value:
MCPFailure
server_name optional until naming/materialization succeeds
origin central | card | session
surface harness_startup | configured_attach | startup_url |
startup_stdio | terminal_connect | acp_connect
input_ref redacted target token or configuration path
stage parse | auth | launch | initialize | discover |
operation | reconnect | shutdown
kind invalid_input | unauthorized | oauth_failed |
timeout | protocol | session_lost | transport |
process | server | cancelled | internal
summary
detail
retry never | user_action | safe_once
remediation
cause original exception, for logs/debugging only
Do not turn this into a second exception hierarchy mirroring every SDK type. Classification is a boundary adapter; protocol detail continues to come from the SDK.
Renderers consume MCPFailure and lifecycle events. They redact credentials and
choose terminal, Markdown/ACP, or CLI formatting without changing recovery
semantics.
| Failure | Action |
|---|---|
| Invalid target/configuration | No retry; show the exact invalid path/token |
| Startup HTTP 401 in auto mode | Enable SDK OAuth provider and retry once |
| Explicit auth rejected | No OAuth override; report that supplied credentials were rejected |
| OAuth callback/registration failure | No automatic loop; preserve typed cause and next action |
Legacy SDK Session terminated |
Replace runtime once when enabled; replay only the rejected operation |
| Generic disconnect during list/read discovery | Reconnect once and replay |
Generic disconnect/timeout during tools/call |
Do not replay automatically; the tool may have run |
CallToolResult.is_error |
Return as server-declared result; no reconnect |
Other MCPError |
Preserve code/message/data; no retry unless explicitly classified |
SubscriptionLost |
Re-listen/refetch with bounded backoff; do not compete with SDK request resumption |
| Shutdown/cancellation | Await cleanup; do not start recovery |
The important invariant is that retry is decided by failure type and operation
replay safety, never by arbitrary text or a blanket ConnectionError catch.
Retain the convenient existing forms:
fast-agent --url https://example.com/mcp
fast-agent --url https://one.example/mcp --url https://two.example/mcp
fast-agent --npx "@modelcontextprotocol/server-filesystem ."
fast-agent --uvx "mcp-server-fetch"
fast-agent --stdio "python server.py --flag"
These become thin adapters over the same target parser and materializer used by runtime connect. They must:
- fail the command when a requested target is malformed; never print-and-skip;
- report the inferred server name and resolved target;
- produce the same auth, naming, target, and transport semantics as
/connect; - make
--urlrepeatable in input order, with comma-separated values accepted for one compatibility window; - apply the existing startup
--authvalue to every startup URL and state that scope in help; use central config or separate runs when targets need different credentials; - add
--mcp-protocol auto|modern|legacyfor startup ad-hoc targets rather than overloading an unrelated generic--protocol; - parse every explicit startup target before attaching any of them;
- if an explicitly requested CLI target cannot attach, fail startup and clean up all CLI-owned attachments from that request rather than silently running without it;
- resolve inferred-name collisions deterministically by input order and report every selected name;
- use one redaction path for command output and logs.
Automatic /mcp URL suffixing is convenient but not obvious. During one
compatibility window, show the resolved URL and a deprecation notice whenever a
suffix is added. The canonical behavior then becomes using the exact URL the
user supplied. Users who want the common endpoint write /mcp explicitly.
/mcp connect is the descriptive command and /connect is its universal
convenience alias in both terminal and ACP:
/connect https://example.com/mcp
/connect --name preview --protocol modern https://example.com/mcp
/connect @modelcontextprotocol/server-filesystem .
/connect uvx mcp-server-fetch
/connect --name local -- python server.py --server-owned-flag
Canonical grammar:
/connect [fast-agent options] <target>
/connect [fast-agent options] -- <stdio command> [arguments...]
Fast-agent options are:
--name, --auth, --timeout, --protocol, --oauth, --no-oauth,
--reconnect, --no-reconnect
Options before the target are canonical. Existing accepted trailing forms may
remain compatible. -- is required when a server-owned argument conflicts
with a fast-agent option.
Configured definitions use an explicit verb:
/mcp attach docs
/connect docs always means an ad-hoc target/stdio command, regardless of
catalog contents. It never performs a registry lookup to decide grammar.
Use:
/mcp list
/mcp status
/mcp disconnect <attached-name>
/mcp reconnect <attached-name>
/mcp may remain a shortcut for /mcp status. /mcpstatus becomes a
warning-producing compatibility alias before removal.
Disconnect semantics are source-aware:
- central/card definition: remove the live attachment, retain the definition;
- runtime definition: remove the live attachment and session-owned definition;
- failed or cancelled connect: publish neither.
Every surface renders the same facts:
Could not connect MCP server 'preview'.
Target: https://example.com/mcp
Stage: initialize
Cause: HTTP 401 Unauthorized
Next: authenticate with --auth, or retry with OAuth enabled.
Requirements:
- distinguish invalid input, auth, startup, protocol, server, timeout, cancellation, and reconnect failure;
- identify whether the source was configuration, an AgentCard,
--url, or/connect; - never suggest editing
fast-agent.yamlfor a runtime-only target; - include command/cwd and bounded stderr for stdio startup failures;
- preserve MCP error code/message in details;
- never expose tokens, authorization headers, OAuth codes, URL credentials, or secret-derived environment values;
- emit one authorization link and one terminal outcome;
- provide
--debug/logs with the original exception chain without changing the concise default message.
- One central persisted collection with deterministic merge behavior.
- Concise configuration for common URL, package, and command targets.
- Expanded configuration when the source must be controlled explicitly.
- Actionable validation for ambiguous or obsolete input.
- Stable identity independent of target inference.
- Clear precedence between defaults, declarations, secrets, and runtime overrides.
- Explicit ownership and collision behavior across central config, AgentCards, and runtime connections.
- One SDK gateway and one OAuth escalation policy for every client lifetime.
- Typed, source-aware failures with bounded and operation-safe recovery.
- Transactional attachment and completion-based teardown.
- Identical target semantics across startup, terminal, and ACP adapters.
- Concise, actionable, redacted user errors.
- Source-preserving configuration inspection with secret redaction.
- A mechanical, idempotent migration path.
- Fewer tests, with more behavior exercised by each test.
- Changing modern/legacy protocol negotiation or
protocol_modesemantics. - Replacing the official MCP client or FastMCP server integration.
- Restoring detailed HTTP transport diagnostics in this change.
- Moving every MCP-related UI setting merely because its name starts with
mcp_. - Redesigning agent configuration syntax in the first schema PR.
- Moving
load_on_startto attachment policy in the first schema PR. - Supporting a permanent compatibility parser for
mcp.targets.
mcp:
defaults:
protocol_mode: auto
reconnect_on_disconnect: true
include_instructions: true
diagnostics:
enabled: true
timeline:
steps: 20
step_seconds: 30
client:
auto_sampling: true
servers:
huggingface:
target: "https://huggingface.co/mcp"
filesystem:
target: "npx -y @modelcontextprotocol/server-filesystem ."
protocol_mode: legacy
private_docs:
transport: http
url: "https://docs.example.com/mcp"
headers:
X-Tenant: engineering
provider_docs:
management: provider
url: "https://docs.example.com/mcp"The initial namespace has these responsibilities:
| Path | Responsibility |
|---|---|
mcp.defaults |
Defaults for omitted per-server operational policy |
mcp.client |
Policy for capabilities implemented by the fast-agent MCP client |
mcp.diagnostics |
MCP diagnostic collection and presentation policy |
mcp.servers |
Reusable named server definitions |
The first migration moves:
auto_sampling: true
mcp_timeline:
steps: 20
step_seconds: 30to:
mcp:
client:
auto_sampling: true
diagnostics:
enabled: true
timeline:
steps: 20
step_seconds: 30These paths must be consumed, not merely parsed. Existing sampling-mode
resolution reads mcp.client.auto_sampling, and existing timeline/status
rendering reads mcp.diagnostics.timeline. mcp.diagnostics.enabled: false
disables existing MCP activity diagnostic collection and presentation; it does
not disable ordinary connection status or imply the later HTTP instrumentation
work.
The first defaults model contains only settings with unambiguous cross-server meaning:
mcp:
defaults:
protocol_mode: auto
reconnect_on_disconnect: true
include_instructions: trueResolution order is:
- model defaults;
mcp.defaults;- the named server declaration;
- a higher-precedence secrets/config layer for the same declaration;
- an explicit runtime command override, when creating an ad-hoc connection.
An omitted field inherits the preceding layer. An explicitly supplied field,
including false, wins. Defaults are applied when a declaration is
materialized, not copied into source-form output.
AgentCard declarations use the same model in Phase 4. Central policy may supply an omitted operational default, but it must not rewrite the card source or bypass card trust restrictions.
The map-local target form is the concise source syntax:
mcp:
servers:
docs:
target: "https://example.com/mcp"
protocol_mode: modern
filesystem:
target: "npx -y @modelcontextprotocol/server-filesystem ."
env:
LOG_LEVEL: warningThe map key supplies the name. Target parsing must never replace it with a name inferred from the URL, package, or command.
Expanded definitions remain canonical when explicit source control is needed:
mcp:
servers:
docs:
transport: http
url: "https://example.com/mcp"
http_timeout_seconds: 30
filesystem:
transport: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .Expanded form also remains required for source types that cannot be expressed
unambiguously by target, such as a provider connector:
mcp:
servers:
company_search:
management: provider
connector_id: company_search
access_token: "${COMPANY_SEARCH_TOKEN}"For a central definition at mcp.servers.<key>:
<key>is the local registry identity and tool namespace.- A missing nested
nameis normal. - A nested
nameequal to<key>may be read during migration, but canonical output omits it. This compatibility is warning-producing and is removed with the other temporary schema aliases after one minor release. - A nested
namedifferent from<key>is rejected with an error naming both values and directing the user to rename the map key. - Target-derived names are used only for ad-hoc runtime connections that lack
--name; they never alter a persisted map identity. - Duplicate names after layered config merge are one definition assembled by key. Definitions from different ownership domains do not silently override one another.
Use these terms consistently in errors, docs, and UI:
- target: a URL, package reference, or command string;
- server name: the local registry and tool-namespace identity;
- configured server: a reusable declaration;
- attached server: a live connection available to an agent.
Do not use alias in user-facing text unless a distinct alias feature is introduced.
An effective declaration has one connection source.
The source fields are:
- shorthand:
target; - expanded URL:
url; - expanded process:
commandwith optionalargs; - provider connector:
connector_id.
transport is part of expanded source selection. When target is present, it
is inferred and is therefore also mutually exclusive with target.
The following is invalid:
mcp:
servers:
docs:
target: "https://example.com/mcp"
transport: http
url: "https://other.example.com/mcp"The error should say that target cannot be combined with transport or
url, identify mcp.servers.docs, and suggest either shorthand or expanded
form.
target may be combined with settings that do not compete to locate the
server:
- metadata such as
description; - ownership such as
management, where the resolved target is valid for that ownership mode; - protocol selection;
- authentication, headers, and environment;
- timeouts, ping, reconnect, and lifecycle policy;
- roots;
- sampling and elicitation;
- instruction policy;
- process working directory;
- provider loading hints where supported.
After target expansion, the existing client-managed and provider-managed invariants still apply. In particular:
- provider-managed definitions require exactly one URL or connector source;
connector_idremains provider-only;- provider-managed settings reject unsupported client transport options;
- forced modern protocol remains invalid over legacy SSE.
The new Phase 1 validation boundary is specifically that target cannot
coexist with an expanded source or transport. Existing expanded-form
cardinality and transport validators remain in force, but broadening or
tightening combinations that do not involve target is not a prerequisite for
this migration and must not be hidden inside normalization changes.
mcp.servers is a map specifically so ordinary deep-merge rules work by
server name:
# fast-agent.yaml
mcp:
servers:
docs:
target: "https://example.com/mcp"
protocol_mode: modern# fast-agent.secrets.yaml
mcp:
servers:
docs:
access_token: "${DOCS_TOKEN}"The merged docs declaration is validated once after layering. Secrets can add
authentication and other non-source fields. If a higher-precedence layer
introduces a second source field, validation rejects the effective declaration
rather than silently selecting one.
There is no precedence between mcp.targets and mcp.servers because
mcp.targets is removed. A file containing mcp.targets fails with a
migration-focused error.
Central config, AgentCards, and runtime commands are separate ownership domains, not precedence levels:
- one owner cannot silently replace another owner's definition;
- a collision reports both origins;
- runtime target replacement is an explicit disconnect followed by connect;
- reconnect refreshes the same definition and never changes ownership;
- reload removes or replaces only definitions owned by the reloaded source.
A server declaration answers:
How can this server be reached and what connection policy applies?
An attachment answers:
Which agent uses this declaration, and when should it be attached?
The long-term shape is:
mcp:
servers:
docs:
target: "https://example.com/mcp"
agents:
researcher:
mcp:
- use: docs
attach: eagerThis syntax is directional, not part of Phase 1. Existing agent server lists
continue to identify configured servers. load_on_start also remains accepted
on server settings until attachment policy is redesigned. It should eventually
move to the agent/server relationship because eagerness is not an intrinsic
property of a reusable endpoint.
Phase 3 separates configured attachment from ad-hoc connection:
/mcp attach docs
/mcp connect --name preview https://example.com/mcp
attachaccepts a configured catalog name.connectaccepts a target and creates a runtime-owned definition.connectmay infer a temporary name when--nameis omitted, but reports the selected name before attachment./mcp connect docsmust not change meaning based on whetherdocscurrently exists in the registry.- disconnecting an attached configured server removes only its live
attachment; its catalog definition remains available for another
attach; - disconnecting a runtime-owned server removes both its live attachment and session-owned catalog entry;
/mcp connect --name docs ...is rejected whiledocsis owned by central config or a card;- this refactor does not add in-place target replacement. Replace a runtime
definition explicitly with
/mcp disconnect <name>followed by/connect --name <name> <new-target>; --reconnectreconnects and refreshes the already attached definition. It does not change target ownership or replace its declaration.
There is no catalog-dependent compatibility interpretation for bare
/mcp connect <configured-name>. It is an ad-hoc target from the first release
of /mcp attach. The error for users who intended configuration points directly
to /mcp attach <name>.
mcp_connect remains useful for portable, card-owned dependencies:
mcp_connect:
docs:
target: "https://example.com/mcp"
protocol_mode: modernThe current implementation has two problems to correct:
- it uses a narrower schema than central MCP declarations, including no
protocol_mode; - it promotes card entries into a mutable process-global registry, so unrelated cards can conflict.
Phase 4 introduces a shared, source-preserving MCPServerDeclaration model for
central config and AgentCards. Connection materialization produces the existing
validated effective server settings.
AgentCard security remains a separate policy layer. Sharing a declaration model does not imply that cards may use every field:
source declaration
|
v
origin-specific trust validation
|
v
defaults + layered overrides
|
v
effective MCPServerSettings
Phase 4 does not silently broaden AgentCard authority. Its initial allowlist is the currently supported card fields:
target, name, description, management, connector_id, headers, access_token,
defer_loading, auth
plus protocol_mode. The shared declaration model supplies syntax and source
validation; the card-origin policy rejects all other declaration fields with an
origin-specific error. Any later addition—especially local process controls
such as command, args, env, or cwd—requires a separate trust review and
an explicit allowlist change. Existing card installation/trust approval remains
responsible for whether an accepted target may be activated; this refactor must
not bypass it.
Card definitions are internally namespaced by card identity and revision. Their user-visible server name can remain concise within the owning agent. Collisions are checked in the attachment scope where tool namespaces would actually overlap, rather than globally across unrelated cards.
Reload behavior must be ownership-safe:
- reloading one card replaces only that card revision's declarations;
- removing a card disconnects only card-owned attachments no longer referenced;
- central definitions remain unchanged;
- runtime connections remain session-owned;
- conflicting replacement is rejected before disturbing a working attachment.
Configuration inspection needs two views.
Preserves what the user declared:
mcp:
servers:
docs:
target: "https://example.com/mcp"It must not expand the target or materialize inherited defaults.
Explains what the runtime will use:
mcp:
servers:
docs:
management: client
transport: http
url: "https://example.com/mcp"
protocol_mode: auto
reconnect_on_disconnect: true
include_instructions: trueBoth views redact access tokens, authorization headers, OAuth client secrets, and secret-derived environment values. The effective view also reports provenance for inherited values without exposing the contents of secret files.
Source preservation is implemented with the shared declaration model in Phase 4. It should not be approximated by reconstructing shorthand from effective settings because that cannot round-trip reliably.
Before:
mcp:
targets:
- name: docs
target: "https://example.com/mcp"
protocol_mode: modern
- name: filesystem
target: "npx -y @modelcontextprotocol/server-filesystem ."
load_on_start: falseAfter:
mcp:
servers:
docs:
target: "https://example.com/mcp"
protocol_mode: modern
filesystem:
target: "npx -y @modelcontextprotocol/server-filesystem ."
load_on_start: falseBefore:
mcp:
targets:
- "https://huggingface.co/mcp"After:
mcp:
servers:
huggingface:
target: "https://huggingface.co/mcp"The migration tool uses the current inference algorithm once to select
huggingface, writes that result as an explicit key, and reports it. Users
should review inferred names before committing the migrated file.
No source migration is required:
mcp:
servers:
filesystem:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "."]Before:
auto_sampling: false
mcp_timeline:
steps: 40
step_seconds: 15After:
mcp:
client:
auto_sampling: false
diagnostics:
enabled: true
timeline:
steps: 40
step_seconds: 15mcp.targets receives no silent dual-read period in the new schema. Continuing
to merge it with mcp.servers would preserve the ambiguity this change is
intended to remove.
The loader rejects it with:
- the source path;
- a concise before/after example;
- the migration command;
- explicit notice when both collections are present;
- collision details when entries would resolve to an existing map key.
The independent top-level auto_sampling and mcp_timeline settings may be
read for one minor compatibility window because they do not create collection
merge ambiguity:
- old-only input emits one deprecation warning and maps to the new path;
- new-only input is canonical;
- old and new paths together are rejected rather than assigned precedence;
- generated config, examples, and docs contain only the new paths;
- the aliases are removed after the announced window.
Phase 1 adds a raw-YAML migration entry point:
fast-agent config migrate-mcp fast-agent.yaml
fast-agent config migrate-mcp fast-agent.yaml --write
It must run before normal settings validation so obsolete configuration does not prevent migration. It should use round-trip YAML support to retain comments, ordering, quoting, and unrelated content.
The command:
- converts each
mcp.targetsitem tomcp.servers.<name>; - uses an explicit list-entry
name, or reports a currently inferred name; - refuses conflicting duplicate names instead of choosing a winner;
- moves
auto_samplingandmcp_timelinewhen the new paths are absent; - refuses old/new path conflicts and explains the required manual choice;
- redacts secret values in console output;
- defaults to a diff/dry run;
- writes atomically with a backup only when
--writeis supplied; - is idempotent: running it again produces no diff and exits successfully.
The migration command is a Phase 1 requirement. Use round-trip YAML support; do not implement a lossy PyYAML rewrite merely to meet the command name.
Purpose: correct verified failure/reconnect behavior before moving ownership boundaries.
Implementation:
- recognize the SDK's legacy session-termination error with public
mcp_types.INVALID_REQUESTplus the SDK message; - classify recovery before
error_factoryconversion; - define operation replay safety so generic tool-call disconnects are not automatically replayed;
- add lifecycle completion barriers and remove correctness sleeps from disconnect/reconnect/manager shutdown;
- preserve original exception causes through
ServerInitializationErrorwhile retaining concise stdio diagnostics; - replace direct aggregator console printing with lifecycle/progress events consumed by the existing surfaces.
Primary implementation areas:
src/fast_agent/core/exceptions.py
src/fast_agent/mcp/client_connection.py
src/fast_agent/mcp/mcp_aggregator.py
src/fast_agent/mcp/mcp_connection_manager.py
Exit criteria:
- the stable-v2 legacy session-termination signal reaches bounded reconnect;
- generic ambiguous tool-call failure is never replayed automatically;
- disconnect returns only after the old runtime completes;
- reconnect has no old/new runtime overlap and uses no fixed cleanup delay;
- terminal and ACP receive the same recovery events without MCP runtime modules importing terminal UI modules.
Purpose: establish one durable central schema without changing protocol runtime behavior.
Implementation:
- add typed
defaults,client, anddiagnosticsmodels underMCPSettings; - move
auto_samplingandmcp_timelineto their new canonical paths; - update sampling and timeline consumers to read the new canonical paths;
- make
mcp.serversthe only persisted central collection; - reject
mcp.targetswith an actionable migration error; - retain
mcp.servers.<name>.target; - enforce map-key identity;
- enforce target/source exclusivity;
- apply defaults without losing explicit
falsevalues; - update setup config, user docs, examples, integration fixtures, and generated reference material;
- add the migration guide and round-trip migration command;
- replace redundant normalization tests with the Phase 1 scenario contracts.
Primary implementation areas:
src/fast_agent/config.py
src/fast_agent/mcp/connect_targets.py
examples/setup/fast-agent.yaml
docs/docs/mcp/client-servers.md
docs/docs/ref/config_file.md
examples/**/fast-agent.yaml
tests/integration/**/fastagent.config.yaml
Exit criteria:
- no maintained example or doc uses
mcp.targets; - obsolete input fails with a migration-focused error;
- sampling and existing timeline/status behavior consume the nested policy rather than falling back to stale top-level defaults;
- central shorthand and expanded forms build the same effective registry entries where semantically equivalent;
- no protocol-mode semantic changes are required except fixture paths.
Purpose: give persistent and request-scoped MCP clients one initialization, OAuth, and failure boundary.
Implementation:
- introduce the SDK client gateway over
create_transport_context()andMCPClientConnection; - move temporary client initialization out of
ServerRegistry; - route persistent and request-scoped initialization through the gateway;
- centralize auto-OAuth attempt state and permit at most one escalation;
- recursively inspect typed exceptions and exception groups before text fallback;
- normalize terminal failures once into
MCPFailure; - retain original SDK/HTTP/OAuth causes for diagnostics;
- keep modern negotiation, discovery/adoption, MRTR, cache, subscriptions, and request resumption in the SDK.
Primary implementation areas:
src/fast_agent/mcp/client_connection.py
src/fast_agent/mcp/mcp_connection_manager.py
src/fast_agent/mcp/gen_client.py
src/fast_agent/mcp_server_registry.py
src/fast_agent/mcp/http_errors.py
Exit criteria:
- one connection-attempt implementation serves probes and persistent runtimes;
- auto OAuth begins credential-free, escalates only on a typed challenge, and retries at most once;
- explicit auth is not silently replaced;
- startup, OAuth, protocol, timeout, and process failures retain structured classification and cause;
ServerRegistryno longer creates SDK clients;- no product retry depends primarily on flattened traceback text.
Purpose: separate loaded declarations from mutable runtime attachment state.
Implementation:
- introduce a runtime catalog entry containing effective settings and origin metadata;
- model origin as central config, AgentCard, or runtime/session;
- stop inserting card/runtime definitions into loaded central settings;
- stage ad-hoc definitions until connection and discovery succeed;
- keep attachment-local overrides off catalog definitions;
- add
/mcp attach <configured-name>; - reserve
/mcp connect [--name NAME] <target>for ad-hoc targets; - expose
/connectconsistently in terminal and ACP; - route startup
--url,--npx,--uvx, and--stdiothrough the same target parser/materializer; - make malformed startup targets fail rather than print-and-skip;
- standardize
/mcp list,/mcp status, and source-aware error output; - define explicit collision, reconnect, disconnect, and cleanup behavior;
- keep attachment lifecycle in the harness/registry path rather than command or UI adapters;
- update status output to show configured/attached state and origin.
Primary implementation areas:
src/fast_agent/mcp_server_registry.py
src/fast_agent/mcp/mcp_aggregator.py
src/fast_agent/commands/handlers/mcp_runtime.py
src/fast_agent/core/agent_card_runtime.py
src/fast_agent/cli/runtime/request_builders.py
src/fast_agent/acp/slash/handlers/mcp.py
Exit criteria:
- attaching a configured server does not create or rewrite a declaration;
- disconnecting a configured attachment preserves its catalog declaration;
- ad-hoc connections are session-owned and cleaned up deterministically;
- failed/cancelled attach leaves no catalog entry or partial resource indexes;
- collisions identify both owners;
- runtime reconnect cannot overwrite central or card ownership;
- runtime command meaning is independent of current registry contents;
- startup, terminal, and ACP produce equivalent effective settings and equivalent failure kinds for the same target.
Purpose: remove schema drift and preserve source form.
Implementation:
- add a shared, source-preserving MCP declaration model;
- use it for central config and
mcp_connect; - materialize effective
MCPServerSettingsonly after origin-specific trust checks and defaults; - add AgentCard parity fields, including
protocol_mode; - retain the current AgentCard declaration allowlist plus
protocol_mode, rejecting other shared-model fields until separately approved; - namespace card declarations internally;
- scope collisions to actual attachment/tool-namespace overlap;
- implement source and effective config inspection with provenance and redaction;
- consolidate central and AgentCard parser/runtime tests around the shared contracts.
Primary implementation areas:
src/fast_agent/agents/agent_types.py
src/fast_agent/core/agent_card_loader.py
src/fast_agent/core/agent_card_mcp_connect_validation.py
src/fast_agent/core/agent_card_rules.py
resources/shared/agent_cards.md
Exit criteria:
- central and card declarations accept the same syntax unless a documented trust rule forbids a field;
- card field acceptance matches the explicit origin allowlist and does not expand as a side effect of adding central configuration fields;
- source output round-trips shorthand;
- effective output explains defaults and origin while redacting secrets;
- unrelated cards no longer conflict through a process-global name alone.
- move
load_on_startand similar eagerness policy to agent attachments; - introduce the richer persisted
agents.<name>.mcp[].use/attachsyntax; - remove temporary top-level setting aliases after the compatibility window;
- add broader source/effective config tooling outside MCP;
- restore detailed HTTP diagnostics through public SDK seams.
The refactor should be governed by seven scenario contracts. Each scenario may contain several assertions, but it should enter through a real public boundary and prove an externally meaningful invariant.
Phase gates:
| Scenario | First gate | Later extension |
|---|---|---|
| 1. Persisted config/migration | Phase 1 through get_settings and the current registry |
Phase 3 origin-aware catalog |
| 2. Declaration materialization | Phase 1 | Phase 2 gateway assertion for local/provider ownership |
| 3. Ad-hoc surface parity | Phase 3 | — |
| 4. Transactional attachment | Phase 3 | — |
| 5. Auth/startup failure | Phase 2 gateway and typed failure assertions | Phase 3 surface parity and catalog rollback |
| 6. Session loss/replay/teardown | Phase 0 recovery and lifecycle assertions | Phase 2 shared-gateway path |
| 7. AgentCard/inspection | Phase 4 | — |
No test is deleted based on a later-phase assertion before that phase lands.
Use real project and secrets YAML files containing:
- named and unnamed legacy
mcp.targets; - an existing expanded server;
- target shorthand with operational siblings;
- nested MCP defaults/client/diagnostics policy;
- a secret-layer auth value and an explicit
false; - comments and unrelated provider settings.
Run the migration command, then load with get_settings(...) and construct the
real catalog.
Assert:
- the dry-run diff and write are correct;
- comments and unrelated settings survive;
- a second migration is a no-op;
- an unmigrated file receives the actionable rejection;
- conflicting inferred names refuse migration;
- map keys become immutable identities;
- secrets merge by key and explicit values beat defaults;
- nested sampling and timeline policy reaches existing consumers;
- no credential appears in migration, validation, or catalog status output.
This replaces separate tests for each shorthand sibling, default, and migration helper.
Load one valid fixture and a compact invalid-case table through the public settings boundary.
The valid fixture contains:
- client-managed HTTP target shorthand;
- expanded stdio;
- provider-managed URL;
- provider-managed connector;
- shorthand auth, lifecycle, roots, sampling, elicitation, and instruction policy.
Invalid cases cover:
- nested
namedisagreeing with the map key; targetplusurl,command/args, ortransport;- provider connector plus another source;
- unsupported client/provider cross-mode fields;
- forced modern protocol over legacy SSE.
Assert path-specific errors, equivalent effective settings for semantically equivalent shorthand/expanded client definitions, and that provider-managed definitions reach provider conversion without opening a local MCP runtime.
Do not create one test per field or reproduce Pydantic's literal tables.
Run one healthy MCP simulator through:
fast-agent --url <url>;- repeated and compatibility comma-separated
--urltargets with colliding inferred names; - startup stdio convenience;
- terminal
/connect <url>; - terminal
/mcp connect <url>; - ACP
/connect <url>; - explicit package and
-- <stdio command>forms.
Assert:
- every adapter produces equivalent effective settings and inferred names;
- repeated URLs preserve input order, receive deterministic unique names, and share the documented startup auth/protocol scope;
- one malformed explicit startup target prevents all startup attachment, and one attachment failure cleans up every CLI-owned attachment from that request;
- the server attaches once, exposes one namespaced tool, and that tool is callable;
--protocol, auth, timeout, and--behavior are documented and consistent;- malformed startup stdio fails the run instead of being skipped;
- the resolved URL is visible during the suffix compatibility window;
/connect docshas identical parser meaning whether or notdocsis in the catalog;- terminal and ACP render the same semantic connected outcome.
One shared attach-surface fixture should drive these entries rather than six parallel fake-manager suites.
With a configured server docs and a simulator:
/mcp attach docs;- connect a runtime-owned
preview; - reject ad-hoc use of the central
docsname; - force a new runtime connection/discovery failure;
- cancel another connection during startup;
- disconnect and reattach
docs; - disconnect
preview.
Assert:
- loaded settings and catalog declarations are never mutated by attachment;
- attachment-local overrides do not affect later agents;
- failed/cancelled attempts publish no definition, tools, prompts, or capabilities;
- collision rejection never disturbs the existing working attachment;
- configured detach retains the definition;
- runtime detach removes the session-owned definition;
- target replacement requires explicit disconnect followed by connect.
This is the primary Phase 3 ownership contract.
Use a stateful HTTP simulator and controlled stdio child:
- HTTP initializes with 401 plus
WWW-Authenticate, then succeeds with OAuth; - explicit bearer auth is rejected;
- OAuth registration returns 404;
- OAuth callback times out or is cancelled;
- executable is missing;
- cwd is invalid;
- child emits stderr and exits before initialize;
- protocol initialization is rejected.
Exercise at least startup --url, terminal /connect, and ACP /connect.
Assert:
- auto OAuth starts credential-free and escalates exactly once;
- explicit auth is never silently replaced;
- persistent and request-scoped attempts behave identically;
- each terminal failure has the correct origin, invocation surface, stage, kind, cause, and remediation;
- failed startup leaves no runtime/catalog residue;
- stdio errors include command, cwd, OS cause, and bounded stderr;
- terminal, ACP, logs, and progress never expose any credential;
- no ad-hoc error suggests editing
fast-agent.yaml.
Use a stateful stable-v2 Streamable HTTP simulator that records requests, session IDs, and call counts.
Exercise:
- legacy
MCPError(code=INVALID_REQUEST, message="Session terminated"); - unrelated invalid request;
- generic disconnect during
tools/list; - generic disconnect/timeout during
tools/call; - server
CallToolResult(is_error=True); - modern request resumption/subscription loss;
- cancellation during disconnect and reconnect.
Assert:
- the legacy session signal is recognized with the SDK public constant;
- reconnect-disabled preserves the original failure;
- reconnect-enabled replaces the runtime once and performs only the permitted replay;
- unrelated invalid requests never reconnect;
- safe list/read operations may replay once;
- ambiguous tool calls never replay automatically;
- server-declared tool errors remain results;
- modern request resumption is not duplicated outside the SDK;
- disconnect awaits full completion and replacement never overlaps;
- no correctness assertion depends on a fixed sleep.
Load two real AgentCards plus central config through the harness:
- both cards use the same card-local name with different targets in unrelated attachment scopes;
- one card uses
protocol_mode; - one entry attempts a field outside the card trust allowlist;
- one collision occurs in an actual shared tool namespace;
- one card is reloaded and then removed.
Assert:
- unrelated card definitions are internally isolated;
- real namespace collisions report both origins before disturbing the working attachment;
- reload/removal affects only the card revision's declarations and runtimes;
- central and runtime-owned definitions remain unchanged;
- the trust allowlist accepts current fields plus
protocol_modeand rejects unapproved process controls; - source view retains shorthand;
- effective view reports defaults and provenance;
- both views redact credentials;
- source output reloads without semantic drift.
This becomes the Phase 4 gate for shared declarations and source preservation.
The following concentrated files currently overlap in target parsing, normalization, AgentCard validation, and runtime behavior:
tests/unit/fast_agent/test_config_mcp_target_shorthand.py
tests/unit/fast_agent/mcp/test_connect_targets.py
tests/unit/fast_agent/mcp/test_connect_targets_entry_resolution.py
tests/unit/fast_agent/core/test_agent_card_mcp_connect.py
tests/unit/fast_agent/commands/test_mcp_runtime_handlers.py
tests/unit/fast_agent/core/test_agent_card_validation.py
tests/unit/fast_agent/mcp/test_mcp_connection_manager.py
tests/unit/fast_agent/commands/test_url_parser.py
tests/unit/fast_agent/cli/commands/test_runtime_request_builders.py
tests/unit/fast_agent/ui/test_parse_mcp_commands.py
Consolidation rules:
- keep focused command-tokenization tests for genuine parser edge cases;
- keep OAuth and authorization behavior tests at their security boundary;
- keep provider payload tests for intentional provider contracts;
- keep modern/legacy protocol integration tests unchanged;
- retain a small pure test for typed failure classification, but replace phrase-matching retry tables with Scenarios 5 and 6;
- replace repeated target-to-settings mapping assertions with Scenarios 1 and 2;
- replace separate startup URL/stdio and slash target mapping tables with the shared parser edge cases plus Scenario 3;
- replace command handler tests that manually assemble registry state with Scenario 4;
- replace separate AgentCard parsing, promotion, and collision micro-tests with Scenario 7 plus a small trust-policy validation table;
- retain focused pure display invariants, but derive one status/error rendering contract from live simulator transitions;
- remove tests that merely repeat Pydantic literal acceptance already exercised through loaded configuration;
- do not assert private normalization dictionaries or duplicate the target parser's implementation table in tests.
After the scenarios are in place, delete tests only when their behavior is clearly covered. The expected result is approximately 25–35 fewer duplicated micro-tests, not a target test-count reduction at the expense of parser, security, ownership, or integration coverage.
Every phase runs:
uv run scripts/lint.py
uv run scripts/typecheck.py
Also run:
- the scenario contracts introduced by that phase;
- existing MCP protocol, auth, provider-managed, registry, and runtime command suites;
- docs generation/build when configuration reference material changes;
- package install smoke tests when bundled setup or shared AgentCard resources change.
Phase 1 should additionally scan maintained docs, examples, and fixtures for
obsolete mcp.targets, allowing only migration fixtures and historical release
notes.
Each phase is independently mergeable:
- Phase 0 fixes stable-v2 recovery and teardown without changing persisted configuration.
- Phase 1 changes persisted configuration but leaves runtime ownership intact.
- Phase 2 unifies SDK client creation and failures without changing catalog ownership.
- Phase 3 changes runtime ownership and commands using the Phase 1 settings and Phase 2 gateway.
- Phase 4 changes declaration preservation and AgentCard scoping without changing SDK transport behavior.
Rollback boundaries:
- if Phase 0 recovery changes regress, revert its replay/teardown slice while retaining the stable-v2 error-code correction and simulator regression test;
- if namespace migration causes regressions, revert Phase 1 as a unit and keep the migration command in dry-run-only mode;
- if the SDK gateway causes regressions, revert Phase 2 without restoring duplicated public error constants or text-based retry tests;
- if runtime ownership causes regressions, revert Phase 3 without restoring
mcp.targets; - if shared AgentCard declarations cause regressions, revert Phase 4 while retaining the explicit origin metadata from Phase 3.
Do not add a second silent precedence rule as a rollback mechanism. Temporary compatibility must be explicit, warning-producing, and time-bounded.
Detailed MCP HTTP diagnostics were restored after the configuration boundary stabilized, without forking the MCP SDK, through:
- supplied
httpx2.AsyncClientrequest/response hooks for POST JSON versus POST SSE, GET activity, session IDs, andLast-Event-ID; - existing public SDK transport messages for logical request/response correlation where exposed.
Response bodies and streaming SSE events remain unconsumed by diagnostics.
The mcp.diagnostics namespace controls collection and timeline rendering
without coupling schema migration to transport instrumentation.
-
mcp.serversis the only persisted central server collection. -
mcp.servers.<name>.targetand expanded definitions are documented. - Map-key identity and source exclusivity are enforced.
- MCP defaults, client policy, and diagnostics use typed namespace models.
- Maintained setup, docs, examples, and fixtures use the new schema.
- Obsolete input receives an actionable migration error.
- Migration is mechanical and idempotent.
- Stable-v2 session termination uses the SDK public constant and is covered by a simulator.
- Recovery classification precedes result conversion and respects operation replay safety.
- Persistent and request-scoped clients use one SDK/OAuth gateway.
- Disconnect/reconnect awaits lifecycle completion without correctness sleeps.
- Runtime catalog entries carry origin metadata.
- Failed and cancelled attachment is atomic.
- Configured attachment and ad-hoc connection are distinct commands.
- Startup flags, terminal
/connect, and ACP/connectshare target semantics and structured outcomes. - MCP core emits events/failures rather than printing directly to terminal UI.
- AgentCards share declaration syntax subject to separate trust policy.
- Source and effective output preserve intent and redact credentials.
- Seven scenario contracts cover the meaningful configuration and runtime behavior.
- Redundant micro-tests are removed only after scenario coverage exists.
- Lint, typecheck, focused MCP suites, docs build, and package smoke pass.
- HTTP diagnostics restoration landed separately through public hooks.