[sanchitrk]

Summary

Adds the low-level MCP client the MCP service will build on: one scoped connection to one server, over stdio or Streamable HTTP, through the official SDK (@modelcontextprotocol/client 2.3.1).

• src/mcp/client.ts: McpClient.connect(...) returns a Connection with tools(), resources(cursor?), resourceTemplates(cursor?), readResource(uri), callTool(...) and onToolsChanged / onResourcesChanged / onSessionExpired / onClose callbacks.

  • Timeouts: 30 s to start, 60 s per request, restarted by progress.
  • Retries: HTTP connect and list/read retry transient failures; tool calls never retry.
  • Errors: HTTP session expiry becomes SessionExpiredError, auth failures become NeedsAuthError.
  • Closing the scope ends the HTTP session and never fires onClose.

• src/mcp/stdio.ts: stdio transport. Servers run on the host in their own process group.

  • A crash is reported with the exit code and the stderr tail.
  • Closing ends stdin, waits 2 s, then SIGTERM and SIGKILL to the group.
  • An exit hook stops leftover servers if the host exits without closing them.

• src/mcp/content.ts: tool results as model text and image content. src/mcp/error.ts: tagged errors.

• SDK validation: list pages and tool results (against a tool's outputSchema) are validated by the SDK.

• Process.terminate: the process-group stop sequence moves out of the host shell into sandbox/utils/process.ts, shared by the host shell and the stdio transport.

• Server logging: onLog receives the server's notifications/message entries, and src/mcp/log.ts (McpLog) appends them one line per entry, rotating the file past 5 MB.

• Readable validation errors: the SDK's multi-line issue list becomes one line, Invalid result for <method>: <path>: <message>; the raw list is logged at debug level.

• Tracing: entry points use Effect.fn (McpClient.connect, McpStdio.make, McpLog.make), and each request gets a span named McpClient.<method>.

No user-facing surface yet: config, the MCP service, scoping and tool wiring come in follow-up PRs stacked on this one.

Review fixes (2026-10-24)

Rebased onto canary (effect 4.0.5, harness 0.5.0); the lockfile now only adds the MCP SDK.

• Retries: connects retry on HTTP 408/429/5xx and on fetch failures with a system code only. Any other TypeError, such as an invalid header value, fails once instead of being retried and logged. Lists and reads retry once, 250 ms later, after a transient HTTP error.
• Startup timeout: bounded by the request timeout (60 s by default) unless set on its own, instead of a fixed 30 s.
• Progress: only requests given a progress handler (tool calls) ask for progress.
• Shutdown: a stdio server's process group gets SIGTERM even after the server exits on its own, and SIGTERM before SIGKILL when the leader is gone but a pipe is still open. The host shell keeps its immediate kill.
• Server logs from the start: the log handler is a connect option, so messages sent during the handshake, or by a server that then fails, reach mcp.log.
• List changes before the handler: a tools/list_changed sent while the first listing is answered is reported once the handler is set, instead of being lost.

Test plan

• test/mcp.client.test.ts: 29 scenarios against real stdio and Streamable HTTP fixture servers.
  • Process behaviour: crash mid-call, process-group cleanup, a server that ignores SIGTERM.
  • Protocol: message framing and the 16 MiB limit, progress keeping a call alive, cancellation.
  • HTTP: transient retry, connection refused, session expiry, 401 with and without an auth provider.
  • Data: roots, resources and paging, output-schema validation, malformed list pages, server logging and log rotation.
  • Error messages: a missing command or working directory.
  • Ends with __artifacts__/mcp.client.json, stable across runs.
• Sandbox tests still pass after the Process.terminate extraction
• vp check and vp run typecheck
• Node SEA bundle with the SDK (checked once the follow-up PRs land)

🤖 Generated with Claude Code

[sanchitrk]

Review (2026-10-24)

Stack status

• Doesn't merge cleanly into current canary. packages/harness/package.json and pnpm-lock.yaml conflict, because canary moved to effect / platform-node 4.0.5 and harness 0.5.0. Rebase, regenerate the lockfile, then run vp check and vp run typecheck again.
• SchemaRepresentation.fromJsonSchemaDocument still returns Schema.Top in 4.0.5, so Tool.fromJsonSchema should be unaffected.
• The green CI ran against the old base. feat(harness): run MCP servers per session and declare their tools #80, feat(harness): add MCP resource tools and keep oversized output on the host #81 and feat(harness): share MCP servers by scope and close idle ones #83 have had no CI at all, because their bases aren't canary.

should-fix: a resolved header value can leak a secret

• Where: mcp/value.ts resolves ${VAR} / !command header values without checking them.
• What happens: if a value contains CR, LF or NUL, new Headers(...) throws a TypeError whose message is the whole value. I reproduced it on Node: Headers.append: "Bearer sk-secret\nx" is an invalid header value.
• Why it spreads: isTransient treats any TypeError as transient, so the message is:
  • logged on every retry;
  • logged again as the connect failure;
  • stored as the server error;
  • with feat(harness): run MCP servers per session and declare their tools #80, shown to the model as MCP server "x" is not connected: …, which puts it in the provider request and the session log.
• Realistic trigger: a !token-cmd that prints a notice line after the token.
• Fix:
  • In resolve, reject header values matching /[\r\n\0]/ with a message that names the header but not the value.
  • Narrow isTransient to fetch network failures (a TypeError with cause.code).

nit: read retries

• Reads and lists retry twice (250 ms, then 1 s), on any TypeError.
• The reference retries reads once, after 250 ms, and only on transient HTTP and network errors. Connect retries already match it.
• Match it, or note why we differ.