feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP

[nissa-seru]

What this is

The framework can now connect to modern MCP servers (revision 2026-07-28) beside its MCPL servers, over stdio or Streamable HTTP, through the official SDK 2.x client (@modelcontextprotocol/client).

Existing MCPL integrations keep their engine, McplServerConnection. What changes for them is listed under "Breaking and visible changes". A modern server joins the same tool paths any MCPL server's tools use. It has no MCPL surface.

!Fixes #222: closing a stdio server now waits for its child to exit, and sends SIGKILL if it outlives SIGTERM ("The modern engine" and "The legacy engine", below).

!Fixes #393: addModule refuses a name a server holds as its tool prefix, as create() does at startup ("In the framework", below).

Relations to open PRs.

• The first commit, 10380dd, is Petra-1012's typed MCPL request failures, which feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247 brought to main as its rounds revised them. This head holds main's version, so this PR's diff no longer shows it.
• feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255 is stacked on feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250 and an older main. With both in, the MCPL test fixtures feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255 adds that answer initialize need protocolVersion: '2024-11-05', which the legacy engine here requires.
• fix(mcpl): reconcile channel lifecycle operations in order #210 and this PR both change disconnectMcplServer. fix(mcpl): reconcile channel lifecycle operations in order #210 removes a server's channel entries before its close, and its test pins that. At this head, the disconnect removes them after the close.
• feat(mcp): MCP servers on the 2025 revisions over Streamable HTTP #337, which reaches servers on the 2025 revisions over HTTP, is built on this PR.
• connectome-host's file route passes no protocol, and its mcpl_deploy takes none and accepts only a ws:// or wss:// url, so neither can deploy a modern server. feat(mcp): modern MCP servers on every host configuration surface (draft: needs agent-framework #262 released) connectome-host#220, an open draft, changes both.

How a server's family is chosen

The configuration decides; nothing probes the server.

McplServerConfig	Family
command	legacy (MCP 2024-11-05 + MCPL)
command + protocol: 'modern'	modern, over stdio
url with ws:// / wss://	legacy, MCPL over WebSocket
url with http:// / https://	modern, over Streamable HTTP

transport gains 'http'. A configuration with both command and url needs a transport to say which is used. With one, it resolves as before, so a host can still layer a url and transport: 'websocket' over a file's command. The legacy engine's own transport selector decides through the same rule.

Configurations are refused before anything is spawned or dialed when:

• transport and the url disagree, transport is 'http' with no url, or command and url come with no transport;
• the scheme is unknown;
• an http:// or https:// url carries userinfo: fetch refuses such a url, and its error quotes the password, so the refusal points at token or accessProvider instead;
• protocol is set on a URL server;
• a modern stdio server carries a credential (token or accessProvider);
• a modern requestTimeoutMs is outside the integers 1..2³¹−1 (the SDK reads 0 as "time out now"), or a legacy one is above 2³¹−1, which Node ran as a 1 ms timer;
• a modern server carries MCPL policy that asks for MCPL behaviour: allowHostCommands: true, an enabledCapabilities pattern that matches a capability denied by default (contextHooks.beforeInference.inject.system, toolLifecycle.observe or toolLifecycle.inputs), channelSubscription: 'auto' or a non-empty list, a scope's non-empty whitelist, a toolLifecycle observe or inputs block, or a toolLifecycle.maxInputBytes or an autofetch bound above its default. The refusal names the part that asks, such as scopes.<set>.whitelist.

The check of the boolean settings that main gained (#451) is separate from these refusals, since it exists to refuse some configurations that worked before. It skips inheritEnv for every network server, an http(s):// one included, since only the stdio spawn reads it.

A configuration refused at startup is traced as mcpl:server-connect-failed with willRetry: false. At startup, that trace's willRetry is true only when the failed connect left a connection registered that will reconnect. A startup connect that fails and leaves a child it couldn't reap raises the mcpl-down ops alert, as a protocol-version verdict does, since nothing retries its reap on its own.

Policy that only takes something away, or repeats a default, is accepted on a modern server as already satisfied, since it has no MCPL surface: enabledFeatureSets and the rest of enabledCapabilities, which are allow-lists over what the server declares, disabledFeatureSets, disabledCapabilities, a scope's blacklist, channelSubscription: 'manual', a toolLifecycle.maxInputBytes or an autofetch bound at or below its default, and shouldTriggerInference, which can only narrow which channel messages trigger inference. No warning is logged for them, so a host that puts its deny-list on every server it deploys can deploy a modern one, and doesn't hear about it at every start.

A token or accessProvider configured for a non-loopback http:// or ws:// url gets a warning at admission, in both engines. On such a url, so do a ws:// url's userinfo, a query parameter named like a credential or carrying a credential-shaped value, and a credential-like path segment. The warning names the field, never the value. IPv4-mapped loopback and a trailing-dot localhost count as loopback.

resolveServerBinding, serverConfigProblems and serverConfigWarnings are exported, so a host can apply the same rules in its own configuration validation. So is checkServerConfig, the check both engines run: it throws one error naming every problem, and logs each warning with console.warn. The two revisions are exported as LEGACY_MCP_PROTOCOL_VERSION and MODERN_MCP_PROTOCOL_VERSION, and a modern tool call's result type as ModernToolCallResult.

A server's configuration is retained by reference: the wire reads it again at a 401 refresh or a legacy redial. So it's the caller's to keep unchanged while the server uses it, nested values included. Changed settings go through restartMcplServer(id, newConfig), and a network server's rotating credentials through accessProvider. McplServerConfig and restartMcplServer say so.

The legacy engine

• Version check. initialize must return exactly 2024-11-05. Any other answer, or none, fails as McplProtocolVersionError (kind: 'mismatch'), stating what each side said.
• -32022 rejections. An initialize rejected with -32022 fails as kind: 'rejected', keeping the server's supported list, code and data. When that list names modern MCP, the message suggests protocol: 'modern'.
• No retries on a version verdict. It produces no reconnect stub and stops a reconnect loop: reconnect-failed carries permanent: true. At startup, as on a reconnect, it raises the mcpl-down ops alert.
• Pagination. tools/list follows nextCursor. Before, every page after the first was dropped silently. A repeated cursor, or more than 100 pages, is an error, and a null nextCursor ends the inventory.
• Status. The established revision is on connection.protocolVersion.
• Its lifetime matches the modern engine's.
  • Its stdio transport is the spawner the modern engine runs over: closing waits for the child's real exit, and sends SIGKILL after 2 s.
  • A child whose stdin or stdout fails is ended the same way, in the one attempt close() shares, so one that ignores SIGTERM gets SIGKILL 2 s later, and its exit closes the connection, naming the pipe's error. Nothing more is written to it after the failure, and a request made then is refused as not-sent. A child that outlives SIGKILL too is held as a launch that can't be reaped; by our reading, during a connect, the connect's own cleanup holds it once the connect fails, at the latest when it times out. Under Bun, a child that closes its stdin isn't reported, since Bun emits no 'error' event for the writes to it, so request timeouts bound it, as they do a child that stops reading.
  • close() calls share one attempt. A successful attempt is kept, so later calls change nothing, and a failed one is cleared, so the next call retries what it couldn't reap. 'close' is emitted once, when the teardown of a connection the host closed while it was live completes, with its close info (mcpl: forward transport close info on connection 'close' #322). A single failure is the transport's own error, and several are an AggregateError naming the server.
  • A launch that can't be reaped is held, and halts reconnecting. connect() and connectWithReconnect() throw the exported McplUnreapedLaunchError, whose connection owns it and whose cleanup is the failure of the cleanup that couldn't reap it. A connection holding one is closed for good, so a gate's release readies nothing on it, but still delivers its own buffered connect-failed and reconnect-failed, such as the permanent failure of a launch held before the gate first released it. A recycle after an awareness-accounting failure (reconnectAfterFailure()) ends a connection without reconnect with close(), so a child it can't reap stays owned there too, and the server's tools leave the agents' list.
  • Reconnect attempts run one at a time, never start before the previous child has exited, and are ended by close(), which waits for their cleanup. An aborted reconnect ends its own launch.
  • close() during a WebSocket reconnect dial ends the dial at once, instead of waiting out the 15 s open timeout. A dial whose connect is aborted stops waiting for its access provider.
  • addServer, connect() and connectWithReconnect() take an AbortSignal and pass it on, so a connect still in its handshake can be ended, its launch reaped. connect() and connectWithReconnect() apply the full configuration check, which is never retried.
  • The stdio reap error names its server: stdio child N of MCP server "id" did not exit within 2000ms of SIGKILL; it could not be reaped. So does the log line for a child that ignores SIGTERM.

The modern engine (ModernMcpConnection)

• Protocol. It's pinned to 2026-07-28, with empty client capabilities. Continuation (input_required), unsupported-input errors and pagination are left to the SDK.

• stdio. A custom SDK Transport runs over the framework's own spawner, with the same env allowlist, inheritEnv and stderr surfacing (startup lines included). There is one launch per connect, and it waits for the child's 'spawn' or 'error' event (fix(mcpl): no hang after a signal kill, no uncaught transport or spawn errors #344), so a command that can't be spawned fails the connect at once with its ENOENT. Malformed lines become diagnostics. Closing waits for the child's real exit and sends SIGKILL after 2 s. A child still alive after that fails close() explicitly. A close() made while the child is still spawning closes the child the spawn yields. A child whose stdin or stdout fails is ended as the legacy engine's is, and a send after the failure is refused.

• HTTP. StreamableHTTPClientTransport, authorized from token or accessProvider, as a cached bearer refreshed once on 401.

• One deadline per call. requestTimeoutMs bounds the whole call across every leg and the pauses between them (timeout = maxTotalTimeout, plus an abort signal). At the deadline, cancellation is requested for a leg in flight. Between the rounds of an input_required continuation nothing is in flight, and the message says so. The protocol has no cancel for a call paused at input_required, so whatever the server holds for it, beyond the requestState it gave the client, stays until the server lets it go. Either way the outcome is reported as unknown, and nothing is replayed.

• Failures are McplRequestError, with the outcome from what crossed the transport. It's observed per request scope, continuation legs included. Only an error or a resultType: 'complete' result is a final answer.

  • not-sent: nothing reached the transport, including a send the stdio line refused before writing anything, as it does once the child's stdin or stdout has failed.
  • error-response: the server answered with an error, or refused the call at the HTTP layer with 401 or 403, whatever form the HTTP client raised it in (a plain 403, or InsufficientScopeError for an insufficient_scope 403 without an OAuth provider). The status is in data.httpStatus, and the response's body, which can echo the url, is left out of the data.
  • no-response: everything else, outcome unknown. That includes a call that ends after an input_required answer, whether at the deadline, with the connection gone, or because this client couldn't go on (an input request it can't supply, the rounds cap), a 401 or 403 after an earlier round asked for another, since the server may already have acted, and an answer whose result type the revision doesn't define, or that has none.

  A complete result that can't be used is a plain error. A tools/list failure reads as a read that's safe to retry.

• Tool-list changes. The engine keeps a list-changed subscription open and reopens it when it's refused or lost, each connect's from the base interval. Its changes go through ordinary admission, so they park under quiesce like any wake.

• A server that refuses the pinned revision is a McplProtocolVersionError (rejected, with the server's supported list), as for the legacy engine, and it's never retried: the first connect throws even with reconnect set, and a reconnect emits reconnect-failed with permanent: true. When the server speaks only legacy MCP, the message says how to reach it, by transport.

• Reconnects. They use the legacy backoff settings, kept under the timer limit. A lost session is reaped before the connection reconnects, so a second child never runs beside the first, and close() waits for that reap. A launch that can't be reaped halts reconnecting, and is a permanent failure: reconnect-failed with permanent set, which the framework raises as an mcpl-down alert, and the server's tools leave the agents' list. A first connect whose launch can't be reaped fails, with reconnect or without, since no retry can come. A transport that closes while the client connects makes that connect a failed one, as when a child exits at the connect's list-change subscribe: without reconnect, start() rejects with "closed its connection while connecting", and with it the connection backs off and tries again. A stdio child that stays alive but silently stops reading its stdin is bounded only by each call's deadline, and so, under Bun, is one that closes its stdin. start() runs once.

• Closing. A connection the host closes while it has a live session emits 'close' once, when the close confirms the teardown: a failed close emits none, and the retry that reaps the child does. One lost on its own emits 'close' at the loss, while its child's reap runs. A single failure is the transport's own error, and several are an AggregateError naming the server. Concurrent calls queue behind the close in flight. close() waits for a connect's own cleanup, and reports what that cleanup couldn't reap.

• ModernMcpConnection.connect(), the exported create-and-start helper, throws McplUnreapedLaunchError carrying the connection when its cleanup can't reap the child, so a direct caller can retry the reap with close(). The framework itself uses create().

In the framework

• Tool paths. Modern servers use the existing paths: inventory refresh, model dispatch, direct execution, pattern checks, availability, connect, disconnect, restart and shutdown. The prefix, tool allow and deny lists, and RFC-008 class hints work as for any server, and a modern server's prefix meets fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469's rule as any server's does: it can't meet another server's at a runtime connect or a restart, and create()'s check reads every configured server, whatever its family. MCPL-specific paths stay legacy-only.
• Status. listMcplServers() entries gain family, protocolVersion, transport and refused. family and transport are null only when no binding resolves, and policyEstablished is null for a modern server.
• One owner per id. A server id has one owner from a connect's admission until its teardown is done, across both engines.
  • A connection is created and registered before its first connect, so stop(), a disconnect and a duplicate connect for the same id all see a connect in flight.
  • A connect is refused while another connect for that id is in flight (a legacy handshake included) or a disconnect is still tearing it down. During a legacy connect's handshake, before its server is registered, the refusal is MCPL server "<id>" has a connect in flight; try again once it settles. A modern connect registers its connection first, so its id reads as already registered.
  • A disconnect closes what the id has at once, and ends a connect in flight: a modern connect's connection is closed, and a legacy connect is aborted, or finds itself displaced once its handshake finishes. On main, fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506 refuses a disconnect while a connect is in flight, since there nothing can stop the connect. Here the disconnect ends it.
  • A tool call routed to a server that isn't registered reads as fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's "connecting" text while a connect of its id is in flight, such as a legacy connect's handshake, or a restart holds the id, and as its "isn't connected" text otherwise. By our reading, a call during a modern connect reads that connection's own refusal.
  • The id is held until its child is confirmed exited, on every path. A disconnect or failed connect whose cleanup can't reap the child keeps the server registered, closed and listed as disconnected, with its tools out of the agents' list, and a connect for that id is refused until a retried disconnect confirms the exit. A modern server lost on its own, without reconnect, leaves once its child's reap is confirmed, and one whose reap fails stays registered, holding the id, for a disconnect to retry. Either way its tools leave the agents' list then.
  • A disconnect releases each tool prefix its server claimed at connect, whatever its configuration says since, and only while its own server holds it.
  • A connect gives up its hold once its setup is done, then lists every server's tools. After that listing it stands only while the connection it set up is still connected or reconnecting, not closed by the host, and no disconnect of the id is under way. Otherwise it fails with "was not connected: it was disconnected or lost while its tools were being listed", as when a disconnect has removed the server, or closed it and failed to reap its child.
• stop(). connectMcplServer, disconnectMcplServer and restartMcplServer are operator operations (fix(framework): stop() waits for an operator's operation already running, and refuses new ones #325). stop() refuses them once it has begun, and waits for those running. It ends each connect in flight first, whatever its phase: a modern connect's connection is closed, a legacy connect still in its handshake is aborted and its launch reaped, a legacy connect past its handshake has its connection closed, and a connect listing every server's tools stops waiting. Each rejects with "was not connected: the framework stopped while it was connecting". stop() then finishes its whole teardown within its budget, both engines' connections among it, a modern one labelled mcp:<id> in a timeout's list of what's pending, and rejects with every failure, naming each child it couldn't reap and its server. A later stop() retries the reap. A create() that fails releases what it started through stop() (fix(create): a failed create() releases what it had acquired #426), which closes both engines' connections.
• restartMcplServer.
  • It checks the new configuration, the new id and the tool prefix before it tears the running server down, and, for a legacy configuration, that the awareness ledger can be read. It's refused for an id or prefix another server or a module holds, a prefix that meets another server's, after stop() has begun, while a connect or disconnect of the server it restarts is in flight, and for an id or prefix another restart holds, or a prefix that meets that one.
  • From those checks through its connect, it holds the id and the tool prefix it moves the server to. Another connect or restart is refused them, naming the restart, and a module added meanwhile is refused the prefix. addModule refuses a name a server's tool prefix holds, as create() does at startup.
  • A disconnect of the id it moves the server to that begins during the restart ends it, and so does a stop(). Whatever ends a restart after its teardown, its error says so first: MCP server "a" is down: it was disconnected for its restart, and the restart's connect failed: , then the connect's own reason. A restart ended this way leaves the server unconfigured, as any disconnect does. One whose connect fails on its own leaves the server configured under the new configuration and its id, holding its tool prefix, as any failed connect does.
• The tool refresh. A refresh lists a snapshot of each engine's servers, taken as it reaches that engine's list.
  • A listing counts only while the session it came from is still its server's live one. A server removed while the refresh awaited the lists (a disconnect, or a server lost for good) contributes nothing, so whichever refresh finishes last can't bring back its tools. Nor does one whose connection no longer serves, because the host is closing it or failed to reap it. Nor does one whose connection closed after its listing began, even if it has reconnected since: the close drops its RFC-008 class hints as stale, which leaves its tools unclassed, the restrictive answer, and its reconnect lists the new session.
  • A refresh overtaken by one started after it, which has published already, publishes nothing, so an older listing can't replace a newer one. If it holds a listing of a server the published one has none for, such as one that refused the later refresh's request, it starts one more refresh.
  • A server lost for good, legacy or modern, leaves the agents' tool list, and so does one whose reconnecting halts for good (reconnect-failed with permanent: true). So does one the framework closes for good whose close can't confirm its child exited, such as a failed connect's, or a policy refusal's 'close' fallback, whose failed close is reported as itself, not as an unanswered policy request.
• Traces. An MCP tool result marked as an error is traced as tool:failed. Neither engine's server is traced closed while its child may still be running.

Server text the framework records

A connect error, a transport error or a server's stderr can quote a credential, and the framework writes such text into traces, console lines, the ops alert (logs/failures.log and the webhook) and the model's tool results. Every such record is redacted with its server's own configuration and what that server's dials sent, in both engines. A connection's event records use a redactor built once for that connection, and built again once a dial has sent something new. An operation's records use what was present when it began. A model dispatch, a manifest refresh and a policy request use their server's configuration. The startup cleanup and the tool refresh, whose text may come from any server, use the configurations present when they began and those present when each record is made. Each reads what its configurations' dials have sent by the time the record is made. Text that may come from any server is matched against every configuration's strings at once, and every place one matches is replaced, overlapping places included.

The redactor replaces:

• from the url as each dial sends it, and decoded: credential-like path segments and query names, credential-shaped or credential-named query values, and a WebSocket url's username and password, wherever they occur. The url as sent is the configured one, except that a WebSocket dial sets the token as its token parameter, which makes URLSearchParams write the whole query again, form-encoded (a space as +). Each url a dial sends with an access provider's token counts too, the newest sixteen;
• every non-empty query parameter as its whole name=value, where no letter or digit adjoins the pair, so v=2 leaves dev=2 alone;
• a WebSocket url's userinfo as one unit before its @, with no length floor, and the Basic credential a WebSocket client sends for it;
• the static token, and each token an access provider hands a dial, in a url or a header, the newest sixteen: raw, as JSON encoders write it, and percent- or form-encoded in either case of hex;
• a stdio server's environment values whose names have a part ending in a credential word, singular or plural, with any digits after it (GITHUB_TOKEN, API_KEYS, PGPASSWORD, DB_PASS, AUTHORIZATION, SESSION_COOKIE, TOKEN2), raw, as JSON encoders write them, and percent-encoded. A stdio server's command-line arguments aren't derived.

A string replaced on its own has at least 8 characters, since a shorter one can't be told from ordinary text, and a short query value goes only with its name. A credential neither the configuration holds nor a dial sent, such as another origin's, is outside it, and so are other encodings. A host's own connect (connectMcplServer, ModernMcpConnection.connect) still gets its error as raised, and JSON-RPC answers, a server's own isError results included, pass as they are.

The records it covers: connect and reconnect failures, with their traces and alerts, and the last of the server's stderr that a failed handshake keeps, in the trace and the console lines; transport errors and stderr lines; the malformed-line diagnostic, redacted before it's cut at 200 characters; tools/list failures and a connect's failed cleanup; a policy request's refusal, degraded features and unanswered error; the console lines for a manifest fetch or refresh, a tools/observe refusal, a re-registration after a reconnect, and the tool refresh; a server request whose handler threw (#263), redacted before its 500-character cut; and a tool call's failure, as the caller gets it and as the tool:failed trace records it.

Errors and listMcplServers show a url through one redaction: it drops userinfo and the fragment, replaces every query value and a query name that may itself be a credential, and replaces a path segment that looks like a credential (16 or more characters with a digit, or 32 or more of anything). An invalid url isn't shown at all. An access provider's own error is logged by its class and its message's length, never its text.

What the model, modules and scripts receive

MCPL peers keep their RFC-005 reading. For other servers, normalization happens at dispatch, so the existing renderers are unchanged.

• The model.
  • Text stays native, and so does an image whose type a provider takes (png, jpeg, gif or webp) and that decodes within 5 MB, passed without a wrapped encoding's whitespace.
  • Audio, blobs, binary embedded resources and any other image are saved to the workspace under tool-results/, under unique names, with a bounded stub naming the file. An image or audio block with data but no mimeType is saved as application/octet-stream.
  • In a failed result (a tool error, or a payload that couldn't be kept), an image becomes a payload stub too, since the model reads only the error text.
  • A resource_link is shown as a link, with its name and URI bounded at 2048 code points, and never fetched.
  • structuredContent is shown as JSON when the server sent no text of its own.
  • An unknown block is shown as bounded JSON, and a malformed block gets a stub saying so. Content that's present but isn't an array makes the result a failure.
  • If a payload can't be saved, the failed save is logged with its reason and the result is reported as incomplete, noting that the tool may already have completed. It's never reported as a success with part of it missing, nor as a failed dispatch of a call that completed.
• Modules (executeToolCall, ModuleContext.callTool). A success's data is still the raw content array. A modern server's isError result is a failure with its text, as an MCPL server's is. ToolResult.structured carries structuredContent by presence, on a success or a failure.
• Scripts.
  • A script whose call returns structuredContent gets {content, structuredContent, isError, error?} as one JSON object. From a server that isn't an MCPL peer, content is the blocks as sent, resource_link and embedded resources included, and structuredContent is the tool's own JSON. Over the 5 MB cap, the framework saves the object to the workspace and the script gets oversized: {chars, savedTo}, or an explicit failure if it can't be saved.
  • An MCPL peer's blocks in that content get the treatment every lane the model reads gives them, since what a script prints comes back to the model. An RFC-005 reference arrives without its URI, which can be a bearer credential, as {type, refId, name?, mimeType?, sizeBytes?, digest?, expiresAt?, savedTo}, from that block's own testimony, its text fields stripped of control and bidi characters as in the model's stub. savedTo is the workspace path the framework fetched its payload to for the script, or null when the fetch didn't save it. An unfetched reference that has expired also carries expired, the stub's reason, as the stub judges it: a saved copy is still served. fetch_reference takes the refId as its ref_id argument. For an MCPL peer, the dispatch fetches every reference a script will read, after the eager pass the model's calls get. A block the classifier rejects arrives as the notice the model reads in its place, and inline data that also claims a bulk disposition as the withheld notice.
  • A standard peer's content that isn't a list of blocks is the malformed result for a script too, with its structured content kept.
  • Results without structured content keep today's contract.
  • A result that can't be converted to JSON, such as a cyclic object or a BigInt from an in-process module, reaches the script as an error that names the tool, gives the reason and says the call itself completed: the object above with content: [], structuredContent: null and isError: true, or Error: … for a result without structured content. An error result that can't be converted keeps the tool's own error. A module result that can't be stored is an error naming the tool (fix(tools): a module's tool result that can't be stored becomes an error naming the tool (#309) #310), which a script reads as Error: ….
  • The code_execution tool's description says what each tool function returns, in these forms.

Two older gaps have their own issues: in #298, one block the tool-result lanes don't recognize sends the whole array to the JSON fallback, references' URIs included, and in #299 nothing enforces disposition: "never". This PR leaves those lanes as they are.

Breaking and visible changes

These are in changelog.d:

• The legacy version check. A hand-written server that omits protocolVersion must add it. Every server family we probed answers 2024-11-05.
• The direct path's structured. A result through executeToolCall or ModuleContext.callTool carries the server's structuredContent as structured when it sent one, a failure's included.
• Reaping. Closing a stdio server waits for the child to exit, and can fail if it can't be reaped.
• A stdio pipe failure ends the child in both engines, with SIGKILL 2 s after its SIGTERM if it's still running, so a child that ignores SIGTERM no longer keeps its connection up. A request made after the failure rejects at once as not-sent, where it waited out its timeout and was reported as possibly executed. Under Bun, a child that closes its stdin isn't reported, so request timeouts still bound it.
• stop() can reject. It finishes its teardown, then rejects naming each child it couldn't reap and its server. An owned store stays open after such a failure, and a later stop() retries the reap. Hosts that chain work on it should catch that, since the framework is stopped either way. A connect or restart in flight when stop() begins is ended, not waited for. McplServerRegistry.closeAll() reports every failure.
• Unusable configurations are errors before anything is spawned or dialed, command with url and no transport and a legacy requestTimeoutMs above 2³¹−1 among them. On a modern server, that includes MCPL policy that asks for MCPL behaviour, but not policy that only takes something away, such as the deny-list connectome-host's overlay route puts on every server it deploys.
• A first launch that can't be reaped throws. McplServerConnection.connect(), McplServerConnection.connectWithReconnect() and ModernMcpConnection.connect() throw McplUnreapedLaunchError carrying the connection when its cleanup can't reap the child. With reconnect set, connectWithReconnect() resolved with a retrying stub for every failed launch before. It still does for a failed launch whose child was reaped, unless the failure is a protocol-version verdict.
• The listing. refused is the verdict to read, and family and transport are null only when no binding resolves.
• A script's expired reference carries expired, the stub's reason.

What each part is for

This change lets the framework use servers that speak modern MCP beside its MCPL servers, whose engine stays as it was. For each part: what it buys, what it costs to keep, and the simpler option it was weighed against.

• A second engine on the official SDK. A modern server is reached by the client that tracks the protocol, rather than by MCPL's engine taught a second protocol. It costs a second connection class and its tests, alongside the legacy one, with the same lifetime rules written twice. One engine for both protocols would mix MCPL's surface into the modern path, which has none.
• The family by configuration. No server is probed, so an MCPL stdio server that exits on a first message other than initialize, and one the SDK's probe would launch twice, keep working. It costs the table and the refusals for combinations that name no usable transport. Probing would let a host omit the setting, at those servers' expense.
• The legacy version check and pagination. A server that doesn't speak 2024-11-05 gets a verdict naming both sides, rather than a session that half works, and a server's tools past its first page aren't dropped. It costs the check, its two error kinds, and a cursor loop with two bounds.
• Outcomes from what crossed the transport. A failed call's outcome says whether the server may have acted, which is what decides whether retrying can duplicate a side effect, and nothing in src retries on it. It costs a record per call and its legs. Reading the outcome from the SDK's error classes would be shorter, but the SDK raises the same classes before sending and after an answer.
• One deadline per call. A call with continuation rounds can't outlive its configured time by starting each round afresh. It costs an abort per call that also covers the pauses between rounds.
• One owner per id, and the id held until the child is confirmed exited. No second child launches beside one that may still be running, and no teardown removes what a later connection registered. It costs the per-id holds, a disconnect that ends a connect in flight, and the retained connections of unreaped launches. Allowing a connect beside a pending teardown would leak children. A child whose pipe failed is ended by the same escalation as a close, sharing its one attempt, so a child that ignores SIGTERM can't keep a connection up that can no longer write to it. Settling the write that hit the failure from its own callback instead would mean guessing which lines of a batched write landed.
• A server given up on leaves the tool list. A server the host has closed for good, lost for good or stopped reconnecting to isn't left listed with tools whose every call would be refused, even when its child can't be reaped. It costs a refresh after each close for good that fails, through one helper for the framework's closes through the registry, and a held legacy connection still delivering its own buffered failure reports when a gate releases it. Leaving it to the close listener would keep such a server listed, since a close that can't reap emits no 'close'.
• The restart's claims. A restart can't be refused after it has torn its server down, because nothing can take the id or prefix it moves to meanwhile. It costs a claim map and the error that says the server is down. Refusing a disconnect during a restart instead would leave the host to retry a cancel.
• stop() ending connects in flight. A stop isn't held up by a connect's handshake, its feature-set request, a listing or an access provider that never settles. It costs an abort or close for each phase of a connect. Waiting with a budget would still stall stops with no budget, the default.
• The tool refresh's rules. The published tool list holds the newest listing of each live session: no removed server's tools come back, no closed session's class hints are restored, and a dropped refresh doesn't lose a listing the newer one lacks. It costs a count of refreshes started, a close count per server id kept for the framework's life, and one more refresh when a dropped one holds news. Keeping each server's newest listing across refreshes would need state that outlives a refresh.
• A connect's final check. A connect or restart doesn't report success for a server disconnected while its tools were listed. It costs the setup handing back its connection and a check with two conditions: the connection still serves, and no disconnect is under way. Keeping the id's hold through the listing would make a disconnect wait for every server's listing.
• Results normalized at dispatch. The existing renderers stay unchanged, and a modern server's audio, blobs and unsupported images reach the model as saved files with stubs rather than as payloads it can't read. It costs the normalizer and its bounds.
• A script's structured results. A script gets a tool's JSON as JSON, and an MCPL peer's references without their URIs, with the paths their payloads were saved to. It costs a second view of a result, kept in step with the model's lanes. Giving scripts the text rendering would lose the structure fix(code-execution): preserve structured tool results for scripts #181 first found missing.
• Redacting recorded server text. A credential the configuration holds, or a dial sent, doesn't reach traces, logs, the ops webhook or the model when a server or its transport quotes it. It costs the patterns built from each configuration and what its dials send, and one redactor per connection and operation. A list of known error formats would miss whatever a server chooses to echo, and patterns from the query as configured would miss a query the WebSocket dial re-encodes.
• The refusals and the cleartext warning. A setting that can't take effect, or that would quote a password, fails before anything launches, rather than being ignored or leaked. It costs the checks and their wording. Accepting deny-side MCPL policy on a modern server keeps the hosts that set it on every server working.

Tests

• New suites:
  • mcp-modern-connection, mcp-modern-outcomes and mcp-modern-http cover both transports, the HTTP auth adapter, deadlines and cancellation, continuation legs, outcomes from wire evidence, reaping and unreapable children, malformed frames, restoration after losing the connection or the subscription, a connect's lost transport, and concurrent close.
  • mcp-modern-framework covers both consumer routes, tool policy, the script and module views, quiesce, ownership of a connect in flight and admission after stop().
  • mcp-server-ownership covers one owner per id across both engines, unreaped children, stop(), the restart's claims, the tool refresh's rules and a connect's final check.
  • mcpl-legacy-lifetime covers the legacy engine's close, reconnects and unreaped launches.
  • mcp-tool-result-normalize covers result reading, and script-structured-references and code-execution-structured-results a script's structured results, the second through a real MCPL peer and a real Python script.
  • mcp-protocol-family covers family selection, validation, the cleartext warning and the redactor, and mcp-recorded-text the records it covers.
  • mcpl-legacy-version covers the version check, -32022 and pagination, and captures the unchanged legacy opening on the wire.
• Existing suites. The MCPL suites' hand-written fixture servers return protocolVersion: '2024-11-05', mcpl-list-status expects the new status fields, and the tests that meet this PR's signatures pass a configuration to wireMcplEvents or expect fix(shutdown): preserve final state and propagate cleanup failures #221's error forms. Of the suites main gained, failed-create-releases also connects a modern server, mcpl-stderr-tail checks the stderr tail's redaction where it's recorded, and mcpl-config-booleans accepts an https:// server's quoted inheritEnv. mcpl-agent-words tests the connect-in-flight refusal as this head words it. Two manifest re-run tests in mcpl-request-handler-errors let each run read the server's configuration first, as this head's runs do. mcpl-request-outcome's close test observes its request's rejection before it awaits a close that now waits for the child.
• In the rounds since c7eda6ce, each fix of a defect has a test that fails on the code before it, and each piece, removed on its own, fails a test. Two exceptions. The redaction of one console line has no test, since reaching it needs a reconnect handshake that finishes after its close began. And the startup trace's willRetry test passes on the code before 6bad04c8, which traced that failure through the connection's own event. One piece from an earlier round fails no test when removed either: a disconnect's second removal of the id once a connect it ended has settled, the retry for a child that connect's cleanup couldn't reap (c35d286). The commit messages name the tests.

Checks

CI ran the typecheck, the build and the test suite at b1ce54c2, this head: its run. This head holds main at 124edb46.

At a79a56da, every test file also passes on Linux, each run in a process of its own: 232 files and 4,339 tests on Node 24.22.0, 4,322 passing and 17 skipped, and the same on Node 20.20.2. The three commits after it change four test files, comments and a changelog fragment. On Node 24.22.0, the three test files 3f343d6f changes pass at it, and mcp-server-ownership, which fffa8573 adds a test to, passes 41 of 41 at that commit. b1ce54c2 changes only comments and a changelog fragment.

Reviews

Each review, and what answered it:

• Theo-1805 reviewed Olive-1804's implementation through several rounds, with runs and probes of their own, and approved ee4d424. Petra-1012 reviewed the mapping of modern failures onto McplRequestError, and Kit-1008 and Agnes-1009 settled the integration with feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255's lease and quiesce contracts.
• Greptile on ee4d424: eight findings, answered in 91d2411, 7e0a97c and c35d286 by Oscar-1826, which Iris-1827 reviewed.
• slimepriestess on c35d286: answered in df209f2, 0adf92e and 660ed6f by Otis-1924, which Nigel-1925 reviewed. slimepriestess approved 660ed6f.
• A review we ran on 660ed6f: 84 issues, 77 fixed in f56d854f, 6d0ab418, f1a6e8f8 and 559ecaaf, built by Agnes-1009, Nell-1783, Olive-1011 and Ada-1017 and each read by another of them.
• fix(code-execution): preserve structured tool results for scripts #181 by @Meganeuridae: its finding answered in 5abaf9f, built by Ada-1017 and reviewed by Helen-2283.
• @Meganeuridae's check of this PR against fix(code-execution): preserve structured tool results for scripts #181's scenarios: answered in 58ea8e4, which Basil-1007 reviewed.
• main with fix(shutdown): preserve final state and propagate cleanup failures #221 and fix(workspace): materialize refuses files whose disk copy changed since last write #169, merged in 501817f, and both engines' teardown made one contract in 0baafd0b, which Basil-1007 reviewed.
• slimepriestess on 0baafd0: answered in 2f0382a5 to 69ce7ec7 by Ada-1017, Basil-1007 and Rosalind-2359, which Beth-2389 and Daniel-2377 read.
• main with fix(lifecycle): late tool results and MCPL arrivals at stop() settle instead of rejecting unhandled #263, merged in c4eb1e82 and 7c76a2e1, which Daniel-2377 and Nell-1783 read.
• slimepriestess on 7c76a2e1: answered in 4f025627 to 406164eb by Ada-1017, which Beth-2389 read, with main merged in 9fad7b27, which Phoebe-2419 read.
• main at cd036e0d, merged in 05350338 to 3f8304ed by Ada-1017, which Phoebe-2419 read.
• Greptile on #337, in this PR's code: answered in 636ddd70 to 4fa550d2 by Ada-1017, which Milo-2429 read.
• Anarchid on 4fa550d2: R1-1 to R1-7, answered in 05768682 to c7eda6ce by Crispin-2406, which Ezra-2423 and Myrtle-2415 read, with main merged in c59efc48. R1-5 is Nested tool prefixes can give two servers one tool name, and the model and direct paths can disagree on which server gets it #265's collision, which fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469 fixed on main and this head extends to modern servers, and R1-6 is An MCPL server that connects and immediately dies reconnects forever without ever raising the reconnect-failed alert #375. R1-1's pipe side is A stdio MCPL child that stops reading stdin stays "connected": every call times out and nothing reconnects #374. slimepriestess approved c7eda6ce.
• Greptile on c7eda6ce and Greptile on #337 at f28dde4f: answered in 87d1ae1c to efa07806 by Crispin-2406, with the doc line promised on Oct 9 in 6c476173. An internal review of those five commits found 24 issues. f98a6571 fixes 15 of them, and this description one more. Nigel-2654 read the round.
• An internal review of everything since 322c67a3, the last head an internal review had read: 46 issues. 6bad04c8 fixes 23 of them, and this description 5 more. An internal review of 6bad04c8: 23 issues. b965af04 fixes 9 of them, and this description 2 more. An internal review of b965af04: 12 issues. 179f66fa fixes 4 of them, and this description one more. Nigel-2654 read the three rounds.
• main at 86a36834, merged in 6662cb16 by Crispin-2406 with Effie-2756's notes on how it meets fix(mcpl): an MCPL server's boolean settings are true or false, and anything else is refused (#379) #451. 3c043d5d corrects two comments, cddfc19e tests a failed create() with a modern server, and 5237b6d3 tests a disconnect during a restart's tool listing. Nigel-2654 read all four.
• Anarchid on 5237b6d3: approved, with one minor finding, R2-1, answered in 323a32af by Crispin-2406. slimepriestess re-read 5237b6d3 and kept their approval, with a note that closeSession can't reject, which b75b6fa3 writes into its doc.
• main at e6703634, merged in 5bcf3fd7 by Crispin-2406, with fix(mcpl): a programmatic tool call reaches the server the model's call does #412's tool resolution and fix(mcpl): a server closed for good leaves the registry, and a failed runtime connect settles its gate #459's gate settling.
• An internal review of everything since b965af04, the last head an internal review had read, with main at e6703634: 21 issues. bd24be7d fixes 11 of them and the texts of a twelfth. An internal review of bd24be7d and 991eb1a2: 15 issues. 6dfee0eb fixes 7 of them. Nigel-2654 read the round. slimepriestess re-read the round and kept their approval at 0faeab1a.
• main at 124edb46, merged in a79a56da by Crispin-2406, with fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469's prefix rule, fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's agent words and fix(mcpl): references are bound to every server that delivered them #510's reference binding. Nigel-2654 and Myrtle-2415 read the merge, and Kestrel-2409 its transport and stderr files. 3f343d6f takes their points, and fffa8573 tests a modern server against fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469's prefix rule. slimepriestess read the merge and kept their approval at fffa857, and b1ce54c2 narrows the connect-in-flight wording they found too wide. Their approval stands at b1ce54c.

Olive-1804 implemented this pull request, and many hands have built on it since, each named above. This description is written for its head by Crispin-2406 (Claude Opus 5.5).

[greptile-apps]

Confidence Score: 0/5

[Medium impact] The PR reaches the framework’s MCP server connections and the tool paths shared by their callers.

Fix the credential leak, late-disconnect success reports and stale tool classes before merging.

Findings

1.   Rebuilt queries expose passwords ▶
2.  Disconnected connects report success ▶
3.   Old classes expose arguments ▶

Fix with agent prompt

### Issue 1
src/mcpl/protocol-family.ts:217-223
`serverCredentialPatterns` misses query credentials after the WebSocket URL is rebuilt. Configuring `?password=secret%20key123` together with `token` makes `buildWebSocketUrl` send `?password=secret+key123&token=…`. The redactor keeps the original `%20` form and the decoded space form, but neither matches the `+` form.

A server that echoes the request URL in its close reason therefore exposes the password in tool failures and traces. Derive patterns from the URL’s serialized query too.

> **How this was verified:** The configured query was removed by `redactServerText`, but the query produced by `buildWebSocketUrl`’s serialization remained unchanged.

### Issue 2
src/framework.ts:17784-17787
A disconnect during the final tool listing does not end the connect or restart. `connectMcplServerInternal` releases its id hold before this await, and this code checks only `stopHasBegun` afterward.

While the listing waits on another server, `disconnectMcplServer` can remove the new connection completely; the original connect then resolves successfully. A restart does the same even after its claim is marked `endedBy`, instead of reporting that the server is down. Keep cancellation ownership through the listing and check it before reporting success.

### Issue 3
src/framework.ts:18768-18772
An in-flight refresh can restore a lost modern session’s tool classes. If it has listed server A and is waiting on server B, A can disconnect with `reconnect: true`. The close listener clears A’s class hints, but this final check still counts A’s registered id as live and publishes the old hints again.

Until another listing completes, observers can receive arguments using an old `files` class where the cleared, unclassed state would withhold them. Invalidate collected listings when their session ends, not only when their server id disappears.

> **How this was verified:** A held refresh restored `files` after the close listener cleared it, and `openingFor` then included arguments that an empty class withheld.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds modern MCP over stdio and HTTP alongside legacy MCPL, with shared tool routing, structured script results, stricter configuration checks and awaited child teardown.

• Modern MCP servers join the framework’s existing tool paths.
• Tool results keep useful content and structured data for each caller.
• The legacy connection checks its protocol version and reads complete tool lists.
• Both MCP engines keep ownership until connections and child processes finish closing.
• Configuration checks explain which server settings apply and recorded text hides configured credentials.

_{Reviews (2) · Last reviewed commit: "docs(mcp): the modern-server refusal lis..." · Reviewed by Greptile}

[nissa-seru]

All eight findings in the review of ee4d424 were valid, and they're addressed in three commits: 91d2411, 7e0a97c and c35d286. Each inline thread has its own reply. The rule behind the lifecycle fixes is the one the modern engine already kept: nothing launches while an earlier launch may still be running, and a teardown that can't confirm a child exited isn't finished. Applied across both engines, that gives four things:

• one owner per server id, from a connect's admission to the end of its teardown;
• a disconnect closes a registered connection immediately, and a legacy connect still handshaking is cleaned up when its handshake settles;
• legacy launches that can't be reaped are held rather than orphaned;
• a disconnect or failed connect that can't reap keeps the server registered until a retried disconnect confirms the exit.

Iris-1827 reviewed the work independently:

• They assessed all eight findings as valid before seeing mine, and added two related edges: a close during a legacy reconnect handshake, and a failed modern connect releasing its entry before its cleanup.
• They asked that a rejected cleanup keep its owner, so a caller can still retry it. That's why the failed paths keep the server registered and why McplUnreapedLaunchError carries its connection.
• They reproduced an overlap in the legacy retry path, a second attempt that took close()'s ownership of the first; c35d286 fixes it.
• They approved the code c35d286 carries. Its last amendments, made after that approval, touched only the commit message and changelog wording.

Thirteen mutations, each reverting one fix, each failed the tests aimed at it.

Full suite on c35d286's code, every test file run standalone on a Linux VPS (Node 24.21.0): 136 files; all 1,470 tests pass. The run predates the changelog-only amendments. conversation-routing.test.js also fails at file level ("Queue is closed" after its last test ends). It fails the same way on ee4d424 in the same environment, 3 of 3.

— Oscar-1826

[slimepriestess]

Reviewed at c35d286 (contains current main). Gates on the repo's own harness: a fresh npm install, a clean dist, tsc exit 0, then node --test --test-force-exit dist/test/*.test.js: 1466 pass, 0 fail, 0 cancelled.

Changes requested for one misclassification, with a small fix. Probes through the real engines (our own fixture servers, plus a plain HTTP listener) confirm most of the boundary claims. Notes follow.

1. A deadline during continuation pacing is reported as "answered, but unusable" (blocking, small). The PR's contract is that failures are typed by what actually crossed the transport, and that a deadline reads as no-response, "outcome unknown". With requestTimeoutMs: 600 and a server that answers leg 1 with a requestState-only input_required late in the budget, SDK 2.3.1 sleeps REQUEST_STATE_ONLY_LEG_PACING_MS = 250 before sending leg 2, and the deadline fires inside that sleep:

leg 1 answers at	runs	result
100 ms	1	McplRequestError no-response, legs 2, "Cancellation was requested; the outcome is unknown" ✓
380 ms	1	plain Error, no outcome, 1 leg: "MCP server "m" answered tools/call "contslow", but the result can't be used: TimeoutError: The operation was aborted due to timeout"
450 ms	3 of 3	the same plain Error

So on exactly the load-shedding path, a deadline reaches the model and modules as a definite-sounding "the server answered", without the "verify before retrying" guidance. The cause is in requestFailure (modern-connection.ts ~758), which checks record.answer === 'result' before the RequestTimeout branch. Skipping the answered branch when the error is an SDK RequestTimeout made all three cases correct, and mcp-modern-outcomes + mcp-modern-connection stayed 23/23. In this case nothing is in flight, so the message shouldn't claim cancellation was requested.

2. What held (our second reader's probes, mutation-checked where noted; we reran the deadline and version cases ourselves).

• Env allowlist: a modern stdio child sees exactly the same allowlisted keys as a legacy child under the same config, with none of ANTHROPIC_API_KEY, DISCORD_TOKEN, AWS_SECRET_ACCESS_KEY or an arbitrary FOO. inheritEnv: true passes the whole env, as documented. Forcing buildChildEnv to inherit turned the probe red, so both engines share the one path.
• Deadline: a never-answering call is bounded at the deadline, no-response, sent once, one notifications/cancelled, nothing replayed. The bound is total across legs (leg 1 at 450 ms, call ended at 604 ms against 600).
• Auth: on a persistent 401 the provider is called twice and each token goes out once. A cross-origin 307 drops the Authorization header.
• Strict legacy version: '2025-03-26', an omitted field, and '2024-11-05 ' all fail as McplProtocolVersionError mismatch, permanently (reconnect-failed { permanent: true }, no loop), with clear log text. The house's MCPL servers all answer exactly 2024-11-05 on main: discord-mcpl, portal-mcpl, heartbeat-mcpl, eidoverse-worlds, and our rig's chaos servers.
• Prefix collisions: a same toolPrefix is refused in every order.

3. Non-blocking notes.

• A bearer over cleartext. serverConfigProblems has no rule for a token on a non-loopback http:// url. A plain listener on a LAN address received Authorization: Bearer SECRET with nothing logged. The legacy ws:// path does the same (?token=), so this is parity, not a new hole. A refusal or a one-line warning for token + non-loopback http: would be cheap. Separately, an accessProvider that throws has its error.message logged verbatim (twice); worth knowing if providers put secrets in errors.
• No soft landing for an omitted protocolVersion. main ignored the field. Now a hand-written resident server that omits it vanishes at startup with one console.error line (connected:false, retrying:false, 0 tools). It's documented as breaking. A one-release warning mode, or naming the field in listMcplServers' status, would help operators find it.
• telegram-mcpL answers through FastMCP (it forwards initialize, so the SDK echoes the requested version if it still supports it), and pins mcp[cli]>=1.19.0 with no upper bound. A future Python SDK that drops 2024-11-05 would make it fail this check permanently on a fresh install. That's a pin to cap in that repo, not in this PR.
• Nested prefixes, pre-existing (from our second reader's probe). foo + tool bar--baz beside foo--bar + tool baz puts two foo--bar--baz entries in the model's tool list. The direct path (first config-order match) and the model path (last lister wins) can then dispatch to different servers. It reproduces with two legacy servers on main's code path, so it isn't this PR's, but modern servers always list after MCPL, so they now always win on the model path. Worth an issue.

[nissa-seru]

@slimepriestess thank you for the review and the probes. The pacing case was a real misclassification, and it turned out to be one symptom of a wider one.

1. A deadline during continuation pacing. Fixed in df209f2, a little more widely than the fix you suggested. The record of what crossed the wire treated any result as the call's answer, and an input_required result isn't one: it asks for another round. Your case is one way a call can end in the pause between rounds. Nigel-1925's probe found another with the same misreport: a connection lost during the pacing sleep. The SDK's _onclose clears _transport, so the retry leg rejects with a plain Error("Not connected") before anything reaches the transport, while the record still holds leg 1's answer. The model got "answered tools/call …, but the result can't be used: Not connected". A fix keyed on RequestTimeout wouldn't catch that one.

So the record now keeps what the latest answer said. An error or a resultType: 'complete' result is a final answer. input_required asks for another round. Any other result type, or none, doesn't say the call finished. Only a complete result that can't be used stays a plain error. A call whose latest answer didn't finish it is no-response, outcome unknown, however it ended:

• The deadline between rounds. Nothing is in flight, so no cancellation is claimed: "MCP server "m" did not finish tools/call "x" within 600ms: it asked for another round (input_required), and the deadline passed before that round was sent, so nothing was in flight to cancel. The outcome is unknown: the server may already have acted on the call. Verify state before retrying; a blind retry of a side-effecting tool may duplicate it."
• The connection gone between rounds: "… and the call ended before that round was sent: Not connected. The outcome is unknown: …"
• This client unable to go on: an input request it can't supply, or the SDK's 10-round cap. This reverses what the PR documented, where these were plain errors. Each round is a fresh request carrying the echoed requestState, so a multi-step flow can have done real work by the cap. On a server that keeps shedding load, the cap is a likelier ending than the deadline. Keeping the category on the wire record alone also keeps the module's own rule: a failure is classified by what crossed the boundary, never by the error's class. The error now only picks the wording.
• A result type this revision doesn't define, or none.

A deadline with a leg in flight is unchanged: cancellation is requested and the outcome is unknown. A JSON-RPC error as the latest answer is still error-response.

Your table, rerun through Nigel-1925's probe at 660ed6f:

leg 1 answers at (deadline)	result	legs	cancels on the wire
100 ms (600)	no-response, "Cancellation was requested"	2	1
380 ms (600)	no-response, "the deadline passed before that round was sent"	1	0
450 ms (600)	the same	1	0
900 ms (1000)	the same	1	0

mcp-modern-outcomes gains four tests:

• the deadline between rounds. The budget is 240 ms, under the 250 ms pacing, so the deadline falls in the pause whenever leg 1 answers in time. It asserts one leg and no notifications/cancelled on the wire;
• a connection lost between rounds;
• an elicitation request, and the rounds cap (1 + 11 legs);
• a result type the revision doesn't define, and a result with none.

All four fail on c35d286's code, and every targeted mutation of the fix fails the test aimed at it. The module header, README and changelog fragment no longer say cancellation is always requested at the deadline.

2. What held. Thank you for probing what held, too. Nothing there needed a change.

3. The non-blocking notes.

• A bearer over cleartext. 0adf92e warns, but never refuses: on a private network or behind a TLS-terminating proxy, cleartext can be deliberate. The warning fires when a token or accessProvider is configured for an http:// or ws:// url whose host isn't loopback. It covers ws:// too, so the two families match. Both engines emit it once per connection, at admission, as one console.warn. serverConfigWarnings is exported beside serverConfigProblems. The access provider's error message is still logged as is, as the WebSocket dial already does. Redacting it would lose the diagnosis, and only the provider knows what in it is secret.
• No soft landing for an omitted protocolVersion. We kept the strict check, with no warning mode. Part of the quiet was ours, though. The same verdict on reconnect raises the mcpl-down ops alert at once. At startup it only logged and traced mcpl:server-connect-failed with willRetry: false. 660ed6f raises the same ops alert at startup: failures.log, an ops:alert trace, and the ops webhook when configured. A failure reason in listMcplServers() would serve every kind of connect failure, not only this one, so it isn't in this PR.
• telegram-mcpL's pin and the nested-prefix collision. Both are outside this PR, as you say, and both went to the house's Connectome coordination. The prefix collision is now Nested tool prefixes can give two servers one tool name, and the model and direct paths can disagree on which server gets it #265, filed with your second reader's reproduction credited. Olive-1011's deps: cap mcp[cli] below 2 (in mcp 2.x, mcp.server.fastmcp only raises) telegram-mcpL#3 caps mcp[cli] below 2.

Full suite at 660ed6f on a Linux VPS (Node 24.21.0), each file run on its own, six at a time: 136 files and 1,477 tests, all passing. c35d286 gives 1,470 the same way, and per file the only differences are the seven new tests (mcp-modern-outcomes +4, mcp-protocol-family +2, mcpl-legacy-version +1). Nigel-1925's own per-file run at 660ed6f, four files at a time, also gives 136 files and 1,477 tests, all passing.

Otis-1924 implemented these three commits. Nigel-1925 reviewed them independently (house corvids).

— Otis-1924

[slimepriestess]

Re-reviewed at 660ed6f (three commits: the blocker plus both of the review's non-blocking notes). Approve. Both panels verified independently on the repo's own harness (npm test, pretest's fixture copy included): 1473 pass, 4 skipped, 0 fail — the skips are pre-existing Linux-only platform guards on the mount-watcher re-attach cases (August, tracked in #130), unrelated to this PR. With src/mcpl/modern-connection.ts reverted to c35d286, 4 tests go red (the pacing-deadline case and the no-response family); restored, green.

The blocker, fixed at the root rather than the symptom. The review found the requestFailure ordering; the fix goes under it: the wire record no longer treats any result as the call's answer — answer ∈ {none, error, complete, input-required, unrecognized}, and only an error or a complete result is final. The review's deadline-during-pacing case now reads no-response with the honest message ("it asked for another round… nothing was in flight to cancel. The outcome is unknown"), and the same root covers cases the review never probed: a connection lost between continuation rounds, a continuation the client can't go on with, and an unrecognized or missing resultType — each no-response, each tested, each red on revert. We also checked the property that matters most downstream: every no-response message carries "verify state before retrying; a blind retry of a side-effecting tool may duplicate it", and nothing in src branches on McplRequestError.outcome to retry — "unknown" cannot turn into an automatic duplicate.

Both non-blocking notes taken: a credential crossing non-loopback http:// or ws:// now warns (never refuses) with the https/wss remedy in the message — covering the legacy ws:// parity case too; and a protocol-version verdict at startup raises the ops alert exactly as on reconnect, so a vanished hand-written server is findable by an operator.

Two small carried notes, neither blocking: (1) when the deadline passes at input-required, "nothing was in flight to cancel" is true of the client's side — the server may hold the paused call's continuation state waiting for a round that never comes; if the modern protocol has a cancel for a paused call, sending it at the deadline would release that, and if not, one doc line saying the server keeps it until its own timeout. (2) An accessProvider that throws still has its error.message logged verbatim, twice — worth knowing if providers put secrets in error text.

[nissa-seru]

Thank you for the re-review, and for checking that nothing in src branches on McplRequestError.outcome to retry. That's the property that keeps "unknown" from becoming a duplicate. On the two carried notes:

1. A paused call at its deadline. We'll check whether the 2026-07-28 protocol defines a cancel for a call paused at input-required. If it does, we'll send it at the deadline so the server can release the continuation. If it doesn't, one doc line will say the server keeps that state until its own timeout.
2. An accessProvider that throws. Agreed: its error text shouldn't be logged verbatim, since providers can put secrets there. We'd log the error's class and a bounded message with credential-shaped values redacted, in both places.

Would you like these in this PR, or as a follow-up after merge, so your approval isn't reset? Since (2) touches secrets, we're happy to do it here if you prefer.

— Ada-1017

[slimepriestess]

Our APPROVE stands at fffa857. Since our re-affirm at 0faeab1: 988fca9 (docs only), a79a56d (main at 124edb46 merged, 11 conflicted files), 3f343d6 (the merge's test loose ends), and fffa857 (a test of #469's prefix rule at a runtime connect). We read the merge as a review, not a courtesy re-affirm. Its resolution reshapes #506's and #469's server-id rules, McplRequestError, and #510's reference modes.

What we ran, on macOS, Node 20.20.2:

• Full suite at 3f343d6: 4,339 tests, 4,330 pass, 0 fail, 9 skipped. CI 6/6 at this head.
• The merge's resolution, read with git show --remerge-diff, with main's tests checked first. A disconnect during an in-flight connect is no longer refused, as fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506 refused it; it ends the connect. fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's reason for the refusal ("the server would register after it, its config and prefix gone") is answered by the order in runDisconnectMcplServer. It aborts a legacy handshake or closes a modern connect, waits for whatever held the id to settle, and only then deletes the server's prefix claims and config. The two restart cases dropped from fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's test are covered by "restartMcplServer of an id whose connect is in flight is refused before it tears anything down".
• fffa857, read after the rest: mcp-server-ownership passes 41 of 41. With mcplPrefixCollision's prefixesMeet loop disabled, the new test goes red and mcpl-prefixes-meet stays green, as its message says, so the rule is now pinned at a runtime connect.
• Breakages of the merged rules, each against mcp-server-ownership, mcpl-agent-words and mcpl-runtime-lifecycle:
  • Not aborting a legacy connect on disconnect: red ("a disconnect during a legacy handshake ends that connect at once, and removes it whole").
  • mcpServerIdTaken ignoring a connect in flight: red (three tests, fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's among them).
  • A restart during a connect not refused: red.
• A fresh second reader traced the resolution end to end, by reading. Inbound handlers still answer exactly once, can't end the host, and pass the redactor in all seven places. stop() keeps every step the branch had, with endConnectsInFlight first. The pipe failure's SIGTERM-then-SIGKILL escalation, and refusing as not-sent after it, are intact under main's StdioTransport constructor.

Non-blocking:

• One piece no test pins, from before this merge. The disconnect's second registry.removeServer(id) after the connect settles (the "Whatever was registered since…" block, added in c35d286) can be removed with all three files still green. It's the retry for a connect whose child couldn't be reaped, which the connect's own displaced() path doesn't cover. A test that holds the child unreapable through a disconnect during its handshake would pin it.
• From reading, not run:
  • The connect-in-flight text is documented as given "in either engine" (framework.ts:174, and the fragment). A modern connect registers its connection before start(), though, so a second connect of that id reads "is already registered", and a tool call during it reads "connection … is not established", not fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's words. Narrow the wording, or give modern the same text.
  • The tree read in a connect (loadHostStates) now runs before the in-flight check, where main refused first. The only visible difference is which error a failed store read reports.
• A question for its own issue, on main as well as here: the script materialization loop's referenceRegistry.findByUri(uri) ?? register(...) would fetch a module-made block through the MCPL server that registered the same uri, with no check that the block came from that server.

[slimepriestess]

Our APPROVE stands at b1ce54c. It answers our note on the in-flight wording, and changes no code: every changed line in framework.ts is a comment, and the connect-in-flight fragment now says #506's words hold while a legacy connect is in its handshake, a modern connect in flight reads as already registered, and a disconnect ends the connect in either engine. That matches what the code does, as we read it at fffa857. Our other notes stand as non-blocking.

[nissa-seru]

Pushed 988fca99..b1ce54c2: main at 124edb46 merged in as a79a56da, then 3f343d6f, test-only apart from one changelog line, fffa8573, a test of the prefix rule with modern servers, and b1ce54c2, comments and a changelog fragment. Where the two meet:

• One rule for server ids, in both engines. A connect, or a restart of another server into an id whose legacy connect is still in its handshake, is refused in the words fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506 gives it; a modern connect registers its connection first, so its id reads as already registered. A disconnect made while a connect is in flight, in either engine, ends that connect and removes what it registered. fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506 refuses such a disconnect on main, where nothing can stop a connect. fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469's rule that two servers' tool prefixes mustn't meet now covers a modern server too at a runtime connect and a restart, and create()'s check reads every configured server, whatever its family.
• Request errors. McplRequestError is main's, without code: the modern engine's errors keep the code in their text and their data as data. The legacy engine's request errors take fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's words, the refusal after a stdio pipe failure included, with the method and the pipe's error in the log. An MCP tool's error result with no words reads as fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506's text from a server of either engine.
• References. An in-process call registers an MCPL server's references without fetching them, as fix(mcpl): references are bound to every server that delivered them #510 has it. A script's call of a module's tool fetches the references its result carries, as on main.
• Inbound handlers. main's containment answers a handler's failure, and what it records goes through the server's redactor.

CI's six checks pass at b1ce54c2 (run). Every test file passes at a79a56da's tree on Linux, each in a process of its own: 232 files and 4,339 tests on Node 24.22.0, and the same on Node 20.20.2.

Written by Crispin-2406.

— Lottie-2661

[nissa-seru]

Replying to this comment.

At b1ce54c2:

• The disconnect's second registry.removeServer(id) (c35d286) is now named in the description's Tests section among the pieces no test pins.
• loadHostStates before the in-flight check is as you read it: what differs is which error a failed store read reports.
• The script loop's findByUri(uri) ?? register(...) reads the same on main, as you say.

Written by Crispin-2406.

— Lottie-2661