Communication conflicts

created:      2026-09-30T08:00:00-05:00
last-updated: 2026-09-30T08:00:00-05:00
increment:    1
status:       standard
tags:         area:compare, area:protocol
description:  every place two parties cannot both be satisfied: revision
              against revision, prose against schema, product against
              product, one mcpx surface against another, and mcpx's
              documents against its code.

A conflict here is a place where doing what one side expects breaks another. Some are in the specification itself. Some are between the products mcpx sits between. Some are inside mcpx. mcpx’s design answer to the protocol-level ones (accept liberally, send conservatively, one downgrade() at the edge, two mechanisms for one question) is in ../protocol.md and is not repeated here. This page records the collisions, not the design. mcpx status is as of 05c78b2.

Each entry names both sides, the source for each, and what mcpx does or should do. IDs are stable so issues and register rows can point at them.

A. Revision against revision

A dual-era server has to serve both sides of each of these, per request.

C-01 A request with neither _meta nor a session. 2026-07-28 calls it malformed and requires -32602 with HTTP 400 (2026-07-28/basic/index.mdx:380-382). The legacy HTTP rules say a server that receives no MCP-Protocol-Version “SHOULD assume protocol version 2025-03-26” (2025-06-18/basic/transports.mdx:250-254). The specification never says what a dual-era server should do. mcpx serves it as 2025-03-26 (internal/mcpserver/conn.go:137-146). That is right for a dual-era server, and it should stay. See stateless.md §4.

C-02 Version negotiation. Every legacy revision says the server MUST answer initialize with a version it supports, a counter-offer (2025-03-26/basic/lifecycle.mdx:130-133). 2026-07-28 answers an unsupported version with an error, -32022 (2026-07-28/basic/versioning.mdx:48-67). mcpx applies the 2026 behaviour to legacy initialize: 2024-11-05 and unknown versions get -32022, a code no legacy client knows (internal/mcpserver/server.go:844-859, W1). It should counter-offer on initialize and keep -32022 for _meta requests.

C-03 Resource not found. -32002 through 2025-11-25; -32602 in 2026-07-28, which also forbids emitting -32002 and asks clients to still accept it (2026-07-28/basic/index.mdx:136-142). mcpx sends -32602 to every revision, so legacy clients get the wrong code (internal/mcpserver/server.go:713-716).

C-04 Logging’s default flipped. 2025-11-25: with no logging/setLevel “the server MAY decide which messages to send automatically” (schema/2025-11-25/schema.ts:1545). 2026-07-28: with no per-request logLevel the server “MUST NOT emit notifications/message” (2026-07-28/server/utilities/logging.mdx:62-64). mcpx emits no log messages to hosts at all, so it satisfies both by silence. Its own comment states the 2026 rule backwards (internal/mcpserver/revisions.go:72-73).

C-05 How a server asks. Legacy: a server-initiated request on the open connection. 2026-07-28: input_required and a retried request (2026-07-28/basic/patterns/mrtr.mdx:7-14). Two mechanisms, one question. mcpx bridges them both ways (input-required.md).

C-06 Resource subscriptions. resources/subscribe and unsubscribe through 2025-11-25; subscriptions/listen with a resourceSubscriptions filter in 2026-07-28 (2026-07-28/changelog.mdx:18). The capability flag resources.subscribe survives in the 2026 schema with a new meaning, “supports resourceSubscriptions on listen” (schema/2026-07-28/schema.ts:850, 2026-07-28/server/resources.mdx:58). mcpx accepts both from either era.

C-07 Tasks, core against extension. The 2025-11-25 experimental tasks and the 2026 io.modelcontextprotocol/tasks extension are “not wire-compatible” (seps/2663-tasks-extension.md:944). tasks/result and tasks/list are removed and tasks/update added. failed changes meaning: in core it includes tool results with isError; in the extension those are completed (schema/2025-11-25/schema.ts:1310, seps/2663-tasks-extension.md:835). mcpx serves the core shape to every era and advertises the extension (internal/mcpserver/server.go:1404-1417).

C-08 _meta key prefixes. 2025-06-18 recommends forward DNS (example.com/); 2025-11-25 recommends reverse DNS (com.example/) (2025-11-25/basic/index.mdx:207-210). Neither changelog mentions it. mcpx reserves nothing of its own in _meta. opencode’s ai.opencode/sessionID follows the reverse rule.

C-09 Batching lived for one revision. 2025-03-26 servers “MUST support receiving JSON-RPC batches” (2025-03-26/basic/index.mdx:97); 2025-06-18 removes batching (2025-06-18/changelog.mdx:12). mcpx lists 2025-03-26 as supported and rejects batches with -32700 (W16).

C-10 Is a dropped connection a cancellation? 2025-03-26 through 2025-11-25: “Disconnection SHOULD NOT be interpreted as the client cancelling its request” (2025-11-25/basic/transports.mdx:128). 2026-07-28: closing the response stream “MUST be treated by the server as cancellation” (2026-07-28/basic/transports/streamable-http.mdx:235-236). mcpx propagates the HTTP request context to the upstream call for every era. It is right for 2026 and against the legacy SHOULD NOT. This is inferred from the context chain and was not driven.

C-11 notifications/cancelled.requestId. Optional in 2025-11-25 (so a task can be cancelled without one), required again in 2026-07-28 (schema/2025-11-25/schema.ts:223). mcpx reads it when present.

C-12 URL elicitation’s plumbing. 2025-11-25 added elicitationId, notifications/elicitation/complete and -32042; 2026-07-28 removed all three (2026-07-28/changelog.mdx:54-60, 2026-07-28/basic/index.mdx:144). mcpx passes an upstream’s elicitation params through to a 2026 host verbatim, so a 2026 host can receive an elicitationId it has no use for.

C-13 Sessions. Legacy: a client “MUST include” the Mcp-Session-Id it was given (2025-11-25/basic/transports.mdx:206-208). 2026-07-28: a server supporting only that revision should “ignore it, and do not mint or echo session IDs” (2026-07-28/basic/transports/streamable-http.mdx:680-686). mcpx mints one on server/discover, a modern request, and its modern input_required path needs it back (stateless.md).

C-14 MCP-Protocol-Version. Legacy (2025-06-18+): required after initialization; an invalid value is a 400 (2025-06-18/basic/transports.mdx:256-257). 2026-07-28: required on every POST and must equal the _meta version, else -32020 (2026-07-28/basic/transports/streamable-http.mdx:252). The 2026 page also says revisions before 2025-06-18 “did not define” the header (2026-07-28/basic/transports/streamable-http.mdx:278). 2025-03-26 did define it, for OAuth metadata discovery (2025-03-26/basic/authorization.mdx:135-139). mcpx ignores an invalid legacy header (W14) and answers a 2026 mismatch with a non-JSON-RPC 400 (W10).

C-15 structuredContent and outputSchema. An object, described by an object-rooted schema, in 2025-06-18 and 2025-11-25; any JSON value, any schema in 2026-07-28 (schema/2026-07-28/schema.ts:1821). A server that returns an array to a 2026 client must not return it to a 2025 one. mcpx emits no structuredContent today.

C-16 Client registration. Dynamic Client Registration is a SHOULD in 2025-03-26 (2025-03-26/basic/authorization.mdx:42), a MAY in 2025-11-25 (behind Client ID Metadata Documents), and deprecated in 2026-07-28 (2026-07-28/deprecated.mdx:29). mcpx performs no OAuth.

C-17 includeContext. thisServer and allServers are soft-deprecated in 2025-11-25 and deprecated in 2026-07-28 (2026-07-28/changelog.mdx:84-88), gated by sampling.context in between. mcpx forwards sampling requests to hosts without checking it.

B. One revision against itself

C-20 Bad tool arguments: protocol error or tool error? 2026 prose makes input-validation failures isError results (2026-07-28/server/tools.mdx:760-765). So does the 2025-11-25 changelog (2025-11-25/changelog.mdx:30). The 2026 schema’s InvalidParamsError still lists “invalid tool arguments” as -32602 (schema/2026-07-28/schema.ts:366) and ships a -32602 example for it. mcpx reports its own tools’ argument errors as isError results (internal/mcpserver/server.go:665-675), which follows the prose.

C-21 Ending a subscription (2026). The cancellation page says the server MUST send notifications/cancelled for the listen id (2026-07-28/basic/patterns/cancellation.mdx:11). The subscriptions page says it SHOULD send a successful subscriptions/listen result, then close (2026-07-28/basic/patterns/subscriptions.mdx:122-124). The schema limits the server-sent cancel to stdio (schema/2026-07-28/schema.ts:637).

C-22 Client cancellation (2026). “A client SHOULD send a cancellation notification” (2026-07-28/basic/patterns/cancellation.mdx:8), but on HTTP the transport “defines no client-to-server” notification. Closing the stream is the cancellation (2026-07-28/basic/transports/streamable-http.mdx:95-101). Read the SHOULD as stdio-only.

C-23 Legacy lifecycle against its own example. A counter-offer is a MUST (2024-11-05/basic/lifecycle.mdx:126), yet the same page’s error example answers an unsupported version with -32602 (2024-11-05/basic/lifecycle.mdx:210). The client’s disconnect is a SHOULD in prose (:130) and a MUST in the schema (schema/2024-11-05/schema.ts:162).

C-24 Which results are cacheable (2026). The changelog names five methods (2026-07-28/changelog.mdx:36); the caching page and the schema add server/discover (2026-07-28/server/utilities/caching.mdx:16, schema/2026-07-28/schema.ts:678).

C-25 Where inputResponses may go (2026). The schema says “any client-initiated request” (schema/2026-07-28/schema.ts:598); the prose allows input_required on three methods only (2026-07-28/basic/patterns/mrtr.mdx:192).

C-26 Is resultType open (2026)? Typed as "complete" | "input_required" | string (schema/2026-07-28/schema.ts:216), but “a resultType of any value unrecognized by the client MUST be considered invalid” (2026-07-28/basic/index.mdx:84). An extension value ("task") is valid only where the extension was negotiated. mcpx stamps "complete" on its task handle, where the extension’s value would be "task".

C-27 The examples break their own rule (2026). The list_changed examples carry no _meta (2026-07-28/server/tools.mdx:246), though every notification on a listen stream MUST carry io.modelcontextprotocol/subscriptionId (2026-07-28/basic/index.mdx:413). An implementer copying the example (as mcpx’s stdio listen path effectively does) is non-conformant.

C-28 The tasks SEP against itself. tasks/get responses MUST use resultType: "complete" (seps/2663-tasks-extension.md:340), but its own error examples show "task" (:844, :868). It names the protocol version 2026-06-30 (:17). It reserves notifications/tasks/ but names its notification notifications/tasks (:894, :422).

C-29 “Unsolicited” tasks (2026). The changelog says servers may return task handles “without per-request opt-in” (2026-07-28/changelog.mdx:22). The extension still requires the client to list it in each request’s capabilities (docs/extensions/tasks/overview.mdx:231-233). Both hold once “opt-in” is read as “the removed task parameter”.

C-30 Answers cannot be errors (2026). InputResponse has no error variant (schema/2026-07-28/schema.ts:541-542). Yet the schema still documents client-side -32602 for elicitation modes and sampling tool results (schema/2026-07-28/schema.ts:370-371), errors a client can no longer return inside MRTR.

C-31 Deprecation windows (2026). Twelve months minimum (2026-07-28/changelog.mdx:110), except HTTP+SSE: three months after SEP-2596 reaches Final (2026-07-28/deprecated.mdx:31).

C. Product against product

C-40 Neither opencode speaks 2026 by default. v1’s SDK negotiates 2025-11-25 and has no modern path (v1:patches/@modelcontextprotocol%2Fsdk@1.29.0.patch:36). v2 speaks 2026-07-28 only when a server is configured protocol: "auto" or "2026-07-28" (v2:packages/schema/src/mcp.ts:20-23). So mcpx’s modern serving path is not exercised by either host out of the box. docs/opencode-plugin.md says v2 will exercise it; that holds only with the option set.

C-41 Session identity arrives two ways, and mcpx reads neither on /mcp. The v1 plugin injects MCPX_SESSION_ID into shell commands through shell.env (plugin/opencode/mcpx-session.ts:664). That reaches the CLI, not /mcp. v2 has no session id in its shell hook, and instead sends _meta["ai.opencode/sessionID"] on every tools/call (v2:packages/core/src/mcp/client.ts:278). mcpx’s MCP server keys every call by process id (internal/cli/serve.go:292-297).

C-42 Code mode inside code mode. v2 wraps every MCP server in its own code mode unless the server is configured codemode: false (v2:packages/schema/src/mcp.ts:34-35), and the built-in exclusion matches only executor (v2:packages/core/src/plugin/mcp-codemode-exclusion.ts:16). mcpx’s mcpx_exec then runs as a tool called from a program the model wrote for opencode’s interpreter. v2 also appends ?codemode=false to remote MCP URLs so servers that bundle code mode can expose raw tools (v2:packages/core/src/mcp/client.ts:214-218). mcpx ignores the parameter.

C-43 Tool names. opencode names MCP tools <server>_<tool> (v1:packages/opencode/src/mcp/catalog.ts:119), so mcpx configured as mcpx becomes mcpx_mcpx_namespaces. v2 rejects any name part over 64 characters (v2:packages/core/src/tool.ts:297).

C-44 v1 drops what mcpx’s artifacts use. v1’s direct tool path keeps text, images and embedded resources and drops audio and resource_link (v1:packages/opencode/src/session/tools.ts:429-436). mcpx_exec artifacts are resource_link blocks, so under v1 without code mode the model never sees them.

C-45 Declaring resources costs every v1 request context. v1 adds three resource tools to every request when any server declares resources (v1:packages/opencode/src/session/tools.ts:136). mcpx always declares it.

C-46 Nobody answers mcpx’s questions on v1. v1 has no elicitation/create handler and declares no elicitation (v1:packages/opencode/src/mcp/index.ts:42-48, :77). mcpx correctly never sends it one, so a question raised under v1 goes to the broker. v2 declares form and url and answers them, but attributes them to the Location, not the session (v2:packages/core/src/mcp/index.ts:80-82).

C-47 Progress that keeps nothing alive. v2’s comment says requesting progress “keeps long calls alive under the SDK’s timeout”, but resetTimeoutOnProgress is never set (v2:packages/core/src/mcp/client.ts:279-281). mcpx never forwards progress, so in either host a long mcpx_call is bounded by the host’s timeout: 60 s on v1 unless configured, 12 h on v2.

C-48 lootbox declares nothing. lootbox’s MCP client (SDK 1.22.0, latest 2025-06-18) sends capabilities: {} (.lootbox/src/lib/external-mcps/mcp_client_manager.ts:150-153). An upstream that elicits gets method-not-found. mcpx declares elicitation and answers through its broker.

C-49 Sandbox or no sandbox. The MCP client best-practices guide’s programmatic tool calling “requires clients to implement a sandbox”. Cloudflare argues a shell-based CLI is “a much broader attack surface than a sandboxed isolate”. opencode runs only the language features it implements. mcpx runs scripts on a real runtime with full authority, by choice (register/code-mode.md). Nobody is wrong on the facts. The disagreement is about who the caller is and what it may do.

D. One mcpx surface against another

C-60 mcpx_call against the script client. The same upstream result is seen differently. mcpx_call drops isError, pretty-prints structuredContent as text and drops images (internal/cli/commands.go:384-415). A script gets ToolError, the structured value, and every block on .raw (internal/codegen/emit.go:493-518). See content-passthrough.md.

C-61 Two task stores. The comment on the task store says one store serves both the MCP server and /v1 so a task started on one is visible on the other (internal/tasks/tasks.go:9-12). There are two: the MCP server’s (internal/mcpserver/tasks.go:31-38) and the daemon’s (internal/daemon/ops.go:428-429).

C-62 stdio and HTTP declare different capabilities. The same server declares listChanged: true and subscribe: true over stdio and false over HTTP (W2, S2). Neither delivers: nothing starts a notifier for a legacy stdio client (internal/mcpserver/server.go:1389-1402).

C-63 mcpx’s server and client agree with each other and not with the schema. Both use protocolVersions for server/discover (internal/mcpserver/server.go:534, internal/mcpclient/client.go:284), and three tests pin it (internal/mcpserver/server_test.go:393, internal/mcpclient/era_test.go:87, internal/mcpclient/modern_test.go:88). Self-consistent tests are how an interoperability bug passes CI.

C-64 The plugin’s mcpx_exec and the daemon’s /v1/exec. The plugin reads an output field the daemon’s result does not have, and sends no session, working directory or abort signal (plugin/opencode/mcpx/; see register/plugin-apis.md).

C-65 The CLI and /v1/exec release sessions differently. The CLI sets MCPX_EPHEMERAL (internal/cli/commands.go:694); /v1/exec does not (internal/execsvc/execsvc.go:573-593). So session-scoped instances, a browser for instance, are released at the end of a CLI run and left for idle reaping after a /v1/exec run. Found by reading code; not driven.

C-66 /v1/protocol reports the default, not the setting. nativeElicit is the compiled default rather than the effective configuration (internal/daemon/routes_proto.go:530), on the one endpoint whose comment says it cannot disagree with the code (internal/daemon/routes_proto.go:495-497).

C-67 A script name locally, a path remotely. Already tracked as #106: the CLI resolves a script name against a search path, and /v1/exec treats file as a path.

E. mcpx’s documents against its code

docs/protocol.md at 05c78b2 against the code at 05c78b2. The PROTOCOL work under way is rewriting that document; these are recorded so a reviewer can check each is gone.

The existing comparison documents also say things the pinned sources do not:

F. mcpx sends what the peer did not negotiate

“Send conservatively” is mcpx’s own rule (../protocol.md). These are the places where it breaks it at 05c78b2: