feat(mcp): stdio MCP client — connect external tool servers

Adds Model Context Protocol support so users extend the agent with
external tools (filesystem, Postgres, git, fetch, …) without us
writing each integration. v1 is stdio transport; remote HTTP/SSE is a
planned follow-up.

No SDK dependency. The official @modelcontextprotocol/sdk is 4.3MB +
17 transitive deps (express, hono, cors, jose, ajv…) — almost all for
running a server + OAuth, none of which a stdio CLIENT needs. The
client is a hand-rolled newline-delimited JSON-RPC 2.0 stdio client
(src/mcp/), consistent with our minimal-deps tenet and the
app-server's existing JSON-RPC-over-stdio pattern.

Pieces:
- protocol.ts: JSON-RPC + MCP message types, line parser
- stdio-client.ts: spawn + handshake (initialize → initialized) +
  tools/list + tools/call, request/response correlation by id, timeout
  + crash → reject-all
- config.ts: load ~/.codebase/mcp.json + project, de-facto mcpServers
  schema (ports existing Claude Desktop/Cursor configs), skips remote
  url servers with a note
- to-agent-tool.ts: bridge MCP tool → AgentTool. Server JSON Schema
  becomes parameters verbatim (pi-agent-core forwards args without
  TypeBox validation); namespaced mcp__<server>__<tool> so no collision
  with built-ins
- manager.ts: spawn all servers best-effort, collect tools, expose
  status; one broken server never blocks others
- bundle.connectMcp() spliced into the live agent.state.tools after
  mount (createAgent is sync, connect is async); wired into ink + pi-tui
  + headless + app-server, disposed on exit and re-connected on /model
- /mcp command shows status + tools

Remote tools route through the same effect-based permission prompts.
22 tests including a real mock-server subprocess exercising the full
handshake, round-trip, error + crash paths.

Author: halfaipg

CLAUDE.md

@@ -439,9 +439,45 @@ Monitors auto-clean when the watched shell exits or when `max_matches`
 is reached. The background shell itself keeps running until
 `shell_kill` — `monitor_stop` only unsubscribes from notifications.
 
+## MCP (Model Context Protocol)
+
+Connect external tool servers (filesystem, Postgres, git, fetch, …)
+without us writing each integration. v1 supports **stdio** servers;
+remote HTTP/SSE is a planned follow-up. No SDK dependency — the client
+is a hand-rolled newline-delimited JSON-RPC 2.0 stdio client
+(`src/mcp/`), consistent with our minimal-deps tenet and the
+app-server's existing JSON-RPC pattern.
+
+Configure in `~/.codebase/mcp.json` (user) or `<cwd>/.codebase/mcp.json`
+(project, wins on name clash) — the de-facto `mcpServers` schema so
+existing Claude Desktop / Cursor configs port over:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+    },
+    "postgres": {
+      "command": "uvx",
+      "args": ["mcp-server-postgres"],
+      "env": { "DATABASE_URL": "postgres://…" }
+    }
+  }
+}
+```
+
+Servers connect after launch (async subprocess spawn + handshake);
+their tools splice into the live agent namespaced as
+`mcp__<server>__<tool>` so they can't collide with built-ins. A broken
+server is recorded and skipped — never blocks the others. `/mcp` shows
+status + tools. Remote MCP tools route through the same effect-based
+permission prompts. Lifecycle: connected on mount, re-connected on a
+`/model` swap, torn down on exit.
+
 ## In-flight features
 
-- **MCP**: real MCP client support hasn't shipped (the `/mcp`
-  placeholder was removed). The pi-mono roadmap will likely add this.
 - **Skills**: bundled + platform-fetched skills work; local
   user skills (`~/.codebase/skills/*.md`) coming.
+- **MCP remote transport**: HTTP/SSE servers + OAuth — stdio ships now.

src/agent/agent.ts

@@ -12,6 +12,7 @@ import { ConfigStore } from "../config/store.js";
 import { DiagnosticsEngine, formatDiagnostics } from "../diagnostics/engine.js";
 import { GlueClient, resolveGlueModels } from "../glue/client.js";
 import { HookManager } from "../hooks/manager.js";
+import { McpManager, type McpServerStatus } from "../mcp/manager.js";
 import { buildMemoryAddendum } from "../memory/inject.js";
 import { MemoryStore } from "../memory/store.js";
 import { PermissionStore } from "../permissions/store.js";
@@ -133,6 +134,16 @@ export interface AgentBundle {
 	/** Push-style line monitors over background shells. App subscribes
 	 * here and steers matched lines into the agent as system-reminders. */
 	monitors: MonitorStore;
+	/** MCP server manager — configured stdio servers + their bridged tools. */
+	mcp: McpManager;
+	/**
+	 * Connect configured MCP servers and splice their tools into the live
+	 * agent. Async (spawns subprocesses + handshake), so callers run it
+	 * after the bundle is built rather than blocking createAgent. Returns
+	 * the per-server connection status for display. Safe no-op when no
+	 * mcp.json exists.
+	 */
+	connectMcp: () => Promise<readonly McpServerStatus[]>;
 }
 
 export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
@@ -460,6 +471,20 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 		return { submitted: true };
 	};
 
+	// MCP: configured stdio servers are connected lazily after the bundle
+	// is built (connect is async; createAgent is sync). On connect we
+	// splice the bridged tools into the live agent's tool set so the
+	// model can call them from the next turn.
+	const mcp = new McpManager();
+	const connectMcp = async (): Promise<readonly McpServerStatus[]> => {
+		await mcp.connectAll({ cwd });
+		const mcpTools = mcp.tools();
+		if (mcpTools.length > 0) {
+			agent.state.tools = [...agent.state.tools, ...mcpTools];
+		}
+		return mcp.status();
+	};
+
 	void agentRef;
 	return {
 		agent,
@@ -483,6 +508,8 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 		resumedMessages: opts.initialMessages ?? resumed?.messages ?? [],
 		backgroundShells: toolContext.backgroundShells,
 		monitors: toolContext.monitors,
+		mcp,
+		connectMcp,
 	};
 }
 

src/app-server/server.ts

@@ -76,6 +76,12 @@ export async function runAppServer(opts: AppServerOptions = {}): Promise<number>
 		return fatal(msg);
 	}
 
+	// Connect configured MCP servers so IDE-bridge sessions get the same
+	// tool surface. Best-effort; failures are logged, never fatal.
+	await bundle.connectMcp().catch((e) => {
+		stderr.write(`app-server: MCP connect failed: ${e instanceof Error ? e.message : String(e)}\n`);
+	});
+
 	let totalUsage: Usage = { ...EMPTY_USAGE, cost: { ...EMPTY_USAGE.cost } };
 	let status: SessionState["status"] = "idle";
 	let pendingPermission: PendingPermission | undefined;
@@ -180,6 +186,7 @@ export async function runAppServer(opts: AppServerOptions = {}): Promise<number>
 
 	unsubscribeAgent();
 	unsubscribePerms();
+	bundle.mcp.dispose();
 	return 0;
 
 	// ─── command dispatch ──────────────────────────────────────────────

src/commands/builtins/index.ts

@@ -4,6 +4,7 @@ import { copy } from "./copy.js";
 import { cost } from "./cost.js";
 import { context, debug, help, pwd, whoami } from "./info.js";
 import { init } from "./init.js";
+import { mcp } from "./mcp.js";
 import { memory } from "./memory.js";
 import { modelCmd, modelsCmd } from "./model.js";
 import { outputStyleCmd } from "./output-style.js";
@@ -27,6 +28,7 @@ export const BUILTIN_COMMANDS: readonly Command[] = [
 	commit,
 	review,
 	memory,
+	mcp,
 	context,
 	login,
 	logout,

src/commands/builtins/mcp.ts

@@ -0,0 +1,48 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Command } from "../types.js";
+
+/**
+ * /mcp — show connected MCP servers and their tool counts, or guidance
+ * on configuring them when none are set up. MCP servers extend the
+ * agent with external tools (filesystem, Postgres, git, fetch, …)
+ * without us writing each integration.
+ */
+export const mcp: Command = {
+	name: "mcp",
+	description: "Show connected MCP servers and their tools.",
+	handler: (_args, ctx) => {
+		const statuses = ctx.bundle.mcp.status();
+		if (statuses.length === 0) {
+			ctx.emit("No MCP servers configured.");
+			ctx.emit(
+				`Add stdio servers in ${join(homedir(), ".codebase", "mcp.json")} (or <project>/.codebase/mcp.json):`,
+			);
+			ctx.emit("  {");
+			ctx.emit('    "mcpServers": {');
+			ctx.emit('      "filesystem": {');
+			ctx.emit('        "command": "npx",');
+			ctx.emit('        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]');
+			ctx.emit("      }");
+			ctx.emit("    }");
+			ctx.emit("  }");
+			ctx.emit("Restart codebase to connect. (Remote HTTP/SSE servers: coming soon — stdio only for now.)");
+			return { handled: true };
+		}
+
+		ctx.emit("MCP servers:");
+		for (const s of statuses) {
+			if (s.connected) {
+				ctx.emit(`  ✓ ${s.name} — ${s.toolCount} tool${s.toolCount === 1 ? "" : "s"}`);
+			} else {
+				ctx.emit(`  ✗ ${s.name} — failed: ${s.error ?? "unknown"}`);
+			}
+		}
+		const tools = ctx.bundle.mcp.tools();
+		if (tools.length > 0) {
+			ctx.emit("Tools:");
+			for (const t of tools) ctx.emit(`  ${t.name}`);
+		}
+		return { handled: true };
+	},
+};

src/headless/run.ts

@@ -102,6 +102,11 @@ export async function runHeadless(opts: HeadlessOptions): Promise<number> {
 	let errorMessage: string | undefined;
 	let totalUsage: Usage = { ...EMPTY_USAGE, cost: { ...EMPTY_USAGE.cost } };
 
+	// Connect configured MCP servers so headless runs (CI, scripts) can
+	// use MCP tools too. Best-effort: a failed server is skipped, never
+	// blocks the run. Subprocesses are torn down in the finally below.
+	await bundle.connectMcp().catch(() => undefined);
+
 	// Always tap the event stream for usage accumulation, regardless of
 	// output format — pi-agent-core surfaces per-turn usage on
 	// message_end events; the JSON output reports the running total.
@@ -167,6 +172,9 @@ export async function runHeadless(opts: HeadlessOptions): Promise<number> {
 		unsubscribe();
 		usageUnsub();
 		process.off("SIGINT", onSigInt);
+		// Terminate MCP server subprocesses so a headless run doesn't leak
+		// children to the parent shell / CI runner.
+		bundle.mcp.dispose();
 	}
 
 	const exitCode = aborted ? 130 : errored ? 1 : 0;

src/mcp/__test__/mock-server.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Minimal MCP stdio server for tests. Speaks newline-delimited JSON-RPC 2.0:
+// handles initialize, tools/list, tools/call. One tool, "echo", that returns
+// its `text` argument. Exits when stdin closes.
+import { createInterface } from "node:readline";
+
+const rl = createInterface({ input: process.stdin });
+
+function send(obj) {
+	process.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+
+rl.on("line", (line) => {
+	let msg;
+	try {
+		msg = JSON.parse(line);
+	} catch {
+		return;
+	}
+	if (msg.method === "initialize") {
+		send({
+			jsonrpc: "2.0",
+			id: msg.id,
+			result: {
+				protocolVersion: "2025-06-18",
+				capabilities: { tools: {} },
+				serverInfo: { name: "mock", version: "0" },
+			},
+		});
+		return;
+	}
+	if (msg.method === "notifications/initialized") return; // no response
+	if (msg.method === "tools/list") {
+		send({
+			jsonrpc: "2.0",
+			id: msg.id,
+			result: {
+				tools: [
+					{
+						name: "echo",
+						description: "Echo back the text argument.",
+						inputSchema: {
+							type: "object",
+							properties: { text: { type: "string" } },
+							required: ["text"],
+						},
+					},
+				],
+			},
+		});
+		return;
+	}
+	if (msg.method === "tools/call") {
+		const { name, arguments: args } = msg.params ?? {};
+		if (name === "echo") {
+			send({
+				jsonrpc: "2.0",
+				id: msg.id,
+				result: { content: [{ type: "text", text: String(args?.text ?? "") }] },
+			});
+		} else {
+			send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `unknown tool: ${name}` } });
+		}
+		return;
+	}
+	// Unknown method → error response.
+	if (typeof msg.id === "number") {
+		send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `unknown method: ${msg.method}` } });
+	}
+});
+
+rl.on("close", () => process.exit(0));

src/mcp/config.test.ts

@@ -0,0 +1,74 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { loadMcpServers } from "./config.js";
+
+describe("loadMcpServers", () => {
+	let home: string;
+	let cwd: string;
+
+	beforeEach(() => {
+		home = mkdtempSync(join(tmpdir(), "mcp-home-"));
+		cwd = mkdtempSync(join(tmpdir(), "mcp-cwd-"));
+	});
+	afterEach(() => {
+		rmSync(home, { recursive: true, force: true });
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	function write(root: string, obj: unknown): void {
+		mkdirSync(join(root, ".codebase"), { recursive: true });
+		writeFileSync(join(root, ".codebase", "mcp.json"), JSON.stringify(obj), "utf8");
+	}
+
+	it("returns [] when no config exists", () => {
+		expect(loadMcpServers({ home, cwd })).toEqual([]);
+	});
+
+	it("parses a stdio server with args + env", () => {
+		write(home, {
+			mcpServers: {
+				postgres: { command: "uvx", args: ["mcp-server-postgres"], env: { DATABASE_URL: "postgres://x" } },
+			},
+		});
+		const servers = loadMcpServers({ home, cwd });
+		expect(servers).toHaveLength(1);
+		expect(servers[0].name).toBe("postgres");
+		expect(servers[0].spec).toMatchObject({
+			command: "uvx",
+			args: ["mcp-server-postgres"],
+			env: { DATABASE_URL: "postgres://x" },
+		});
+	});
+
+	it("project config overrides user config on name collision", () => {
+		write(home, { mcpServers: { fs: { command: "user-cmd" } } });
+		write(cwd, { mcpServers: { fs: { command: "project-cmd" } } });
+		const servers = loadMcpServers({ home, cwd });
+		expect(servers).toHaveLength(1);
+		expect(servers[0].spec.command).toBe("project-cmd");
+	});
+
+	it("skips remote (url) servers — stdio only in v1", () => {
+		write(home, {
+			mcpServers: {
+				remote: { url: "https://mcp.example.com" },
+				local: { command: "local-cmd" },
+			},
+		});
+		const servers = loadMcpServers({ home, cwd });
+		expect(servers.map((s) => s.name)).toEqual(["local"]);
+	});
+
+	it("skips entries missing a command", () => {
+		write(home, { mcpServers: { broken: { args: ["x"] } } });
+		expect(loadMcpServers({ home, cwd })).toEqual([]);
+	});
+
+	it("tolerates invalid JSON without throwing", () => {
+		mkdirSync(join(home, ".codebase"), { recursive: true });
+		writeFileSync(join(home, ".codebase", "mcp.json"), "{ not json", "utf8");
+		expect(loadMcpServers({ home, cwd })).toEqual([]);
+	});
+});