Operate and author MCP servers

xcsh keeps Model Context Protocol (MCP) transport concerns below capability discovery. MCP is off by default; configuration alone never starts discovery. After an explicit opt-in, a connected server contributes normalized tools and the agent loop invokes those tools through the same result boundary used for built-in and extension tools.

manager                      transport                server
  resolve configuration
  open one connection   ->   initialize          ->   accept
  list capabilities     ->   tools/list          ->   tool descriptors
  register bridged tools
  agent loop calls tool ->   tools/call (id N)   ->   result (id N)
                             notifications       ->   (uncorrelated)
  refresh set           ->   close removed
  shutdown              ->   close transports    ->   child process exits

How does a request move through the runtime?

The manager resolves configuration, establishes one connection per active server, caches that connection, lists capabilities, and registers bridged tools. JSON-remote procedure call (RPC) request identifiers correlate replies while notifications flow independently. Transport closure rejects outstanding work and moves the server to a reconnectable failure state.

How do reload and teardown work?

One session-owned runtime controller serializes enable, disable, and reload operations. Enabling discovers and connects once, then publishes tools, prompts, resources, notifications, and server instructions together. Disabling first removes those capabilities and child access, rebuilds the system prompt, and then closes every transport and child process. A reload is available only while the runtime is enabled. Session shutdown performs the same teardown. Server implementations must also handle client cancellation and EOF so local processes do not outlive xcsh.

Child tasks inherit the parent’s explicit policy. An enabled parent shares its live connections with children through proxies; children do not rediscover or start duplicate servers. Disabled or omitted child policy exposes no MCP proxies and performs no discovery.

What makes a tool server compatible?

Publish stable tool names, JSON Schema input definitions, bounded results, and actionable protocol errors. Keep credentials in the server environment, not tool descriptions. Test each of these against the same transport declared in mcp.json:

1. Initialization.
2. Tool listing.
3. One successful call.
4. Invalid input.
5. Cancellation.
6. Reconnect after a dropped transport.
7. Shutdown.

Read packages/coding-agent/src/mcp for the manager, transport selection, and tool bridging.

A server is ready only after initialization and capability listing complete on the same transport. A successful tools/call response must retain its request identifier; notifications never satisfy a request. During failure testing, terminate the server with one request outstanding and confirm the client rejects that request, closes the transport, and can establish a fresh connection. Do not leave a spawned server process running after the test.