feat(coding-agent): first-party MCP extension

[Apocrathia]

Summary

• Adds packages/coding-agent/extensions/prime-mcp/ — a first-party MCP client shipped as a pi package. A single mcp proxy tool (list/describe/call) keeps the prompt small (~200 tokens) instead of loading every server's tool defs.
• Optional directTools promotes hot tools to first-class registerTool entries with their real schemas. Promotions are trust-filtered so a lower-precedence repo config can't hijack a server a higher-trust config opted to auto-promote.
• Lazy connect on first use, refcounted idle disconnect, and a single transparent reconnect on a dead transport. Supports stdio and streamable-HTTP servers.
• Config resolution with precedence: <cwd>/.mcp.json > <cwd>/.prime/agent/mcp.json > ~/.prime/agent/mcp.json. Malformed files warn and are skipped rather than failing the whole load. ${VAR} expansion in env/headers.
• /mcp slash commands (status, tools, reconnect), example config, docs/mcp.md, README pointer, and a CHANGELOG entry.

Test plan

• npm run check clean
• 28 unit tests (config precedence/validation, proxy call path, reconnect, concurrency, content rendering, name caps) — mocked MCP server, no real keys
• Manual: prime-agent -e ./packages/coding-agent/extensions/prime-mcp with an example server

Scope notes (v1)

• Ships as a workspace package installed via local path (prime-agent install ./packages/coding-agent/extensions/prime-mcp); not auto-enabled in default settings and not bundled into the published coding-agent package.
• Client-only — Prime Agent is not exposed as an MCP server.
• Promoted tools are namespaced mcp__<server>__<tool> (capped at the 64-char provider limit with a stable hash). There is no extension API to detect collisions with other extensions' tools, so the prefix is the guard.

prime-swarm alignment

MCP is agent-to-tool (see prime-swarm docs/interconnect.md); the implementation stays in the agent image and only tool names cross the swarm wire.

Made with Cursor

Note

Add first-party MCP client extension to the coding agent

• Adds a new prime-mcp extension package that connects the coding agent to external MCP servers via a single mcp proxy tool, allowing the model to list servers/tools, inspect schemas, and invoke tools.
• Implements McpManager with lazy connect, idle disconnect via configurable timeout, single retry on transport error, and graceful shutdown across sessions.
• Reads merged config from .mcp.json, .prime/agent/mcp.json, or ~/.prime/agent/mcp.json with precedence-based merging; supports both stdio and HTTP transports with ${VAR} env expansion.
• Supports promoting selected MCP tools to first-class agent tools via directTools config, with sanitized names, collision detection, and schema passthrough.
• Exposes a /mcp slash command for status, tool listing, and per-server reconnect operations.

📊 Macroscope summarized 4ab8720. 13 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[Apocrathia]

@cursor macroscope found stuff. please address the findings and respond/resolve the threads.

[cursor]

Implemented and pushed review fixes on feat/prime-mcp-extension.

Fixed:

• Null/undefined MCP content blocks no longer crash rendering.
• callTool no longer auto-retries transport errors, avoiding duplicate side effects.
• listTools still retries once on dead transports.
• Reconnect failure no longer double-decrements old connection refcounts.
• /mcp reconnect now passes abort signals through.
• disconnect() now lets in-flight operations drain before closing.
• directTools now register a deferred fallback on connection errors and retry/upgrade schema after reconnect.

Verified:

• npx tsx ../../node_modules/vitest/dist/cli.js --run test/prime-mcp.test.ts passes: 34 tests.
• npm run check passes.
• Pre-commit hook reran npm run check cleanly.
• Working tree clean.
• Commit: 0e74b42e fix(coding-agent): address prime mcp review findings

I updated the PR registration. I could not post/resolve the GitHub review threads directly: no GitHub comment/review MCP tool is available, and gh is read-only in this environment.

Environment note: node_modules was absent, so I ran npm install from the existing lockfile. For future Cloud agents, consider an env setup agent with: “Install workspace dependencies for prime-agent from package-lock.json so vitest and npm run check work without a per-agent npm install.”

  

[macroscopeapp]

🟡 Medium prime-mcp/index.ts:144

/mcp reconnect <server> re-runs registerDirectTools() with the full directToolRefs list, so reconnecting one server triggers describeTool() calls against every other direct-tool server. This lazily connects to unrelated servers and, if any of them is down, reports a failure even though the targeted server reconnected successfully. Consider filtering directToolRefs to only refs whose server matches the reconnect target.

 					if (directToolRefs.length > 0) {
-						await registerDirectTools(
-							pi,
-							manager,
-							directToolRefs,
-							(message) => failed.push(message),
-							promoted,
-							ctx.signal,
-						);
+						const refsForTarget = directToolRefs.filter((ref) => ref.split("/")[0] === name);
+						if (refsForTarget.length > 0) {
+							await registerDirectTools(
+								pi,
+								manager,
+								refsForTarget,
+								(message) => failed.push(message),
+								promoted,
+								ctx.signal,
+							);
+						}

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/extensions/prime-mcp/index.ts around lines 144-153:

`/mcp reconnect <server>` re-runs `registerDirectTools()` with the full `directToolRefs` list, so reconnecting one server triggers `describeTool()` calls against every other direct-tool server. This lazily connects to unrelated servers and, if any of them is down, reports a failure even though the targeted server reconnected successfully. Consider filtering `directToolRefs` to only refs whose server matches the reconnect target.

[macroscopeapp]

🟡 Medium prime-mcp/manager.ts:220

In begin(), waitForConnect() resolves with a Connection, but between the await resuming and connection.active += 1 executing, a concurrent disconnect(name) can evict that connection (sees active === 0) and call closeClient(), closing the transport. begin() then increments active on the stale, closed object and returns it, so the caller's listTools/callTool runs against a closed client and fails spuriously during shutdown/reconnect races. Consider re-reading the current connection from this.connections.get(name) after await and reconnecting if it was evicted while waiting.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/extensions/prime-mcp/manager.ts around line 220:

In `begin()`, `waitForConnect()` resolves with a `Connection`, but between the `await` resuming and `connection.active += 1` executing, a concurrent `disconnect(name)` can evict that connection (sees `active === 0`) and call `closeClient()`, closing the transport. `begin()` then increments `active` on the stale, closed object and returns it, so the caller's `listTools`/`callTool` runs against a closed client and fails spuriously during shutdown/reconnect races. Consider re-reading the current connection from `this.connections.get(name)` after `await` and reconnecting if it was evicted while waiting.

[macroscopeapp]

🟡 Medium prime-mcp/manager.ts:100

setConfig() awaits disconnectAll() before assigning this.config, so a concurrent listTools/callTool started during that window still sees the old config. Its begin() → connect() call is not in the snapshot disconnectAll() took, so it is never aborted, and when it resolves it writes the old client into this.connections. Later calls under the new config then silently talk to the previous server for the same name. Replace this.config before disconnecting so concurrent operations started during the teardown window reject against the new config.

-		await this.disconnectAll();
-		this.config = config;
+		this.config = config;
+		await this.disconnectAll();

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/extensions/prime-mcp/manager.ts around lines 100-104:

`setConfig()` awaits `disconnectAll()` before assigning `this.config`, so a concurrent `listTools`/`callTool` started during that window still sees the old config. Its `begin()` → `connect()` call is not in the snapshot `disconnectAll()` took, so it is never aborted, and when it resolves it writes the old client into `this.connections`. Later calls under the new config then silently talk to the previous server for the same name. Replace `this.config` before disconnecting so concurrent operations started during the teardown window reject against the new config.

[kevinjosethomas]

To follow the RLM paradigm, MCP should be implemented as an IPython RLM skill rather than a Prime Agent extension. This was added in #280.