Audit agent client capability advertisement

[huntharo]

Background

OpenCode v1.17.6 included a small MCP compatibility change: "Improved MCP server compatibility by declaring OpenCode's supported client capabilities."

Release and implementation references:

• Release: https://github.com/anomalyco/opencode/releases/tag/v1.17.6
• PR: chore(mcp): declare client capabilities anomalyco/opencode#32222
• Commit: anomalyco/opencode@11fd6f8
• MCP lifecycle/capability negotiation: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle

What OpenCode actually changed:

• It now passes an explicit MCP SDK ClientOptions object with capabilities: {}.
• It keeps unsupported client-side capabilities commented out: sampling, elicitation, roots, and tasks.
• The intent is compatibility and correctness: conforming MCP servers can inspect the initialize handshake and avoid calling client-side features the client does not actually support.

agent-kit comparison

agent-kit does not currently appear to instantiate the MCP TypeScript SDK client directly or act as a first-party MCP client. Its MCP handling is mostly ACP-adjacent:

• packages/agent-acp/src/acp-client.ts forwards mcpServers through ACP session/new / session/load.
• packages/agent-client/src/chat/chat-thread-controller.ts forwards per-surface threadMcpServers to ACP-style backends.
• The ACP adapter already follows the same conservative principle at the ACP boundary:
  • packages/agent-acp/src/acp-client.ts sends explicit clientCapabilities.
  • It advertises auth.terminal: false, fs.readTextFile: false, fs.writeTextFile: false, and terminal: false.
  • packages/agent-acp/src/acp-connection.ts intentionally does not install fs/terminal handlers because those capabilities are not advertised.
• Codex App Server clients also send explicit capabilities during initialize, currently experimentalApi: true and requestAttestation: false.

Proposed work

Add a focused capability-advertisement audit and regression coverage so we do not accidentally advertise host/client features we cannot service as agent-kit grows MCP/ACP support.

Suggested checklist:

• Add tests for ACP initialize payloads asserting the exact conservative clientCapabilities we advertise today.
• Add tests for Codex App Server initialize payloads asserting the exact capabilities objects for both CodexThreadClient and CodexOneShotClient.
• Add a short source comment or docs note near ACP mcpServers explaining that these are downstream MCP servers attached to the ACP agent, not an MCP client implementation inside agent-kit.
• If agent-kit later adds a direct MCP SDK client, use the OpenCode pattern immediately:
  • centralize ClientOptions;
  • pass an explicit capabilities object;
  • advertise only implemented client features;
  • leave unsupported sampling, elicitation, roots, tasks, etc. unadvertised until handlers and user-consent flows exist.

Why this matters

MCP capability negotiation happens during initialize. The client sends supported protocol version, client capabilities, and client info; the server responds with its capabilities. During operation, both sides are expected to use only successfully negotiated capabilities.

The practical failure mode is subtle: if a client omits, overstates, or drifts its capability declaration, MCP or MCP-adjacent agents may try to call server-initiated features such as roots, sampling, or elicitation. That can show up as compatibility bugs, hung requests, "method not found" errors, or unsafe UX if a capability is advertised before the host has consent and review UI.

For agent-kit today, I do not see an urgent code change equivalent to OpenCode's MCP SDK update. The useful follow-up is to lock in the existing conservative ACP/Codex behavior with tests and documentation, and to make the direct-MCP rule explicit before we add that surface.