@corbits/mcp turns each tool on a remote MCP server into its own @intx/agent tool for the Interchange sidecar. The client speaks MCP 2026-07-28 (stateless server/discover, per-request _meta and Mcp-* headers). A server that does not implement server/discover, times out, or only speaks 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 falls back to initialize plus Mcp-Session-Id. It owns the MCP client, tool naming and the ask floor, the sidecar-bundle factory, the hub catalog-discovery route and MCP OAuth discovery. It does not own the OAuth login itself (@corbits/oauth-core) or credential storage (the hub).
src/client.ts: streamable-HTTP JSON-RPC client.mcpConnectprobesserver/discover. Modern calls aretools/list,tools/call,prompts/list,prompts/get,resources/list,resources/read,resources/templates/list,completion/complete, andsubscriptions/listen.mcpInitializeis the explicit legacy handshake. Extensions (io.modelcontextprotocol/tasks,io.modelcontextprotocol/ui,io.modelcontextprotocol/skills) are advertised and sent only when the caller opts in by extension id.src/tool.ts:mcpTools, one@intx/agenttool per remote MCP tool, named<server>.<tool>.src/naming.ts: qualified names and the ask floor, shared bymcpToolsand the sidecar bundle.src/url.ts: which MCP endpoints a token may be sent to.src/oauth-discovery.ts: MCP OAuth metadata discovery, Client ID Metadata Documents, dynamic client registration, issuer-keyed stored credentials, and RFC 9207isschecks before a code is read.src/sidecar-bundle.ts: the./sidecar-bundleentry a deployed agent's bundle loads.src/hub/discover.ts,src/hub/index.ts: the./hubentry, server-side catalog discovery.src/test-server.ts: in-test MCP server used by the tests.src/index.ts: the root entry.
Discovery and calling are split, because a deployed agent's tool factories are evaluated synchronously when the agent is constructed and the agent must never hold a server's bearer.
- The deployer discovers the catalog once, server-side, through the hub
route this package mounts. The browser never holds an MCP token, so this
is the only way an OAuth-protected server's
tools/listcan be read. - The catalog is stored with the rest of the agent's deploy config.
mcpServersturns the stored catalog into tools. Construction is synchronous and does no network work: names andaskmarks come from the stored catalog. By contrast,mcpToolsis asynchronous and discovers the remote catalog live before building tools.- At run time the agent only ever sees a mediated handle. Each server's
credential resolves to an
httphandle (a fetch pinned to the credential's origin that injects the bearer per request), so the token never reaches agent code, and a relative path is all the bundle ever asks for.
The client in src/client.ts is hand-rolled on purpose. A 2026 server gets
one POST per call after server/discover: protocol version, client info, and
client capabilities travel in _meta, and Mcp-Method / Mcp-Name /
MCP-Protocol-Version travel as headers. There is no session id, no
initialize, and no notifications/initialized on that path. A call made with
no session speaks this stateless path directly. input_required
comes back as a typed result and mcpContinue retries the original method
with inputResponses. subscriptions/listen is the long-lived stream.
notifications/progress stays on the response stream of the call that asked
for it. Modern HTTP cancellation closes the response stream; it does not post notifications/cancelled.
A legacy server still gets initialize, notifications/initialized, and
Mcp-Session-Id. In the sidecar bundle every request goes through a fetch
the mediated credential handle pins to the server's origin.
The SDK's streamable-HTTP client transport is built for long-lived sessions
(resumable streams, server-initiated requests) and installs server-framework dependencies this client does not need. Shared wire/schema validation now uses a directly declared AJV dependency, not the SDK runtime. Resumable streams
(Last-Event-ID), the removed HTTP+SSE transport, modern ping, and the deprecated
roots, sampling, and logging methods are not implemented. e2e/ runs
discovery and tool calls against the SDK's stateless and stateful 2025
transports and against a small 2026 fixture; the SDK is a devDependency only.
Prompts, resources, and subscriptions are client methods. They are not
projected into agent tools, and tools stay the only grantable unit.
bun install && bun run check && bun run test:e2e- Read
README.mdbefore changing public behavior. - Keep changes focused; update docs and tests alongside code changes.
- Run
bun run checkbefore declaring work complete.
./clientand./serverare standalone entries. Never import agent, harness, hub, DB or Hono runtime code into their dependency graph../interchange/clientconsumes remote MCP;./interchange/serverexposes only explicitly selected host bindings. Preserve the root, sidecar-bundle and hub facades.- Shared wire validation belongs in
src/protocol; extension runtimes accept transport/provider interfaces instead of importing client facades. - Runtime JSON Schema validation uses declared AJV; skill YAML parsing uses declared YAML. The MCP SDK remains development-only and only tests legacy transport interoperability.
docs/conformance.mdtracks role/revision/capability-qualified evidence; never infer complete conformance from aggregate test counts.- Package gates:
bun run check,bun run test:e2e,bun run build,bun run test:package. The packed smoke suite requires npm, registry access and Node 24+.
createMcpServeris modern/stateless by default. Explicitlegacyoptions enable the three 2025 Streamable HTTP revisions; see docs/legacy-server.md for session bounds, affinity/restart behavior, initialization authorization and March-only batches. Do not describe this implemented shim as missing.- Apps metadata is not host support. Advertisement requires explicit host bridge, sandbox/CSP/authenticated-bridge support and presentation; actual rendering is host-owned. Keep metadata-only hosts unadvertised.
- OAuth-core is an optional peer required by root/guarded login, not by neutral client/server. Keep stock dependency defects CL11479/CL11480 distinct from local guarded behavior and from application deployment obligations.
- Shared-worktree build/pack gates must run serially; record exact runtime versions and do not infer final Node26 evidence from earlier Node24 results.