io.github.Oortonaut/mcacp

Official

by Oortonaut · TypeScript

MCP-to-ACP bridge — let any MCP client drive ACP coding agents

Bridge protocol enabling MCP clients to drive ACP coding agents.

Topics

acpagentic-aiagentic-frameworkllmmcp

README.md6 KBView on GitHub

MCACP

Bridge any MCP client to any ACP coding agent.

MCACP is an MCP server that speaks the Agent Client Protocol on behalf of your MCP host. It lets Claude Code, Zed, VS Code, or any MCP-compatible client spawn, manage, and interact with ACP coding agents — turning a single chat window into a multi-agent control plane.

code

MCP Client (Claude Code, Zed, VS Code, ...)
    |
    |  MCP (stdio)
    v
  MCACP
    |
    |  ACP (stdio, per agent)
    v
 Claude Code  ·  Gemini CLI  ·  Codex  ·  Auggie  ·  Copilot  ·  ...

What can you do with this?

Run any ACP agent from any MCP client. You don't need a dedicated IDE plugin for each agent. Install Gemini from Claude Code. Run Codex from Zed. Mix and match.

Compare agents side by side. Give the same task to Claude Code ACP and Gemini CLI in parallel sessions and compare the results.

Build agent-driven pipelines. One agent writes code, another reviews it, a third runs the tests. MCACP handles the lifecycle and permission flow for all of them.

Control permissions interactively. On hosts that support MCP elicitation (Zed), permission requests pop up as interactive forms. On hosts that don't (Claude Code), they fall back to operator mode where the host agent decides.

Resume where you left off. Sessions persist to disk. Shut down, restart, load_session — the agent picks up where it stopped.

Discover and install agents from chat. Browse the ACP registry, install agents, check for upgrades — without leaving your conversation.

Quick start

Install

bash

npm install -g mcacp

Or run directly:

bash

npx mcacp

Add to your MCP client

Claude Code (~/.claude/settings.json):

json

{
  "mcpServers": {
    "mcacp": {
      "command": "npx",
      "args": ["-y", "mcacp"]
    }
  }
}

Zed (settings.json):

json

{
  "context_servers": {
    "mcacp": {
      "command": { "path": "npx", "args": ["-y", "mcacp"] }
    }
  }
}

Then from chat:

code

"Search for available agents"        →  registry_search
"Install the Gemini agent"           →  agent_install
"Initialize it and start a session"  →  initialize + new_session
"Ask it to refactor auth"            →  prompt_start + prompt

MCP tools

MCACP exposes 22 tools organized into five groups.

Registry

Tool	Description
`list_installed_agents`	List locally installed agents
`registry_search`	Search the ACP agent registry
`agent_install`	Install an agent from the registry
`agent_uninstall`	Remove an installed agent
`agent_check_upgrades`	Check for available upgrades
`discover_agents`	Scan editor configs (Zed, JetBrains) for agents
`reload_config`	Reload `mcacp.json` from disk

Lifecycle

Tool	Description
`initialize`	Spawn an agent process and perform the ACP handshake
`shutdown`	Gracefully shut down an agent

Sessions

Tool	Description
`new_session`	Create a session with working directory and permission policy
`load_session`	Resume a persisted session
`list_sessions`	List stored sessions for an agent
`close_session`	Close a session (preserved for later resume)

Interaction

Tool	Description
`prompt_start`	Send a prompt (returns immediately)
`prompt`	Block until events are available
`prompt_events`	Non-blocking poll for events
`grant_permission`	Resolve a pending permission request (operator mode)
`request_permission`	Send an MCP elicitation to the host for a permission decision
`cancel`	Cancel an in-progress prompt
`set_mode`	Switch agent operating mode

Status

Tool	Description
`list_running_agents`	List all agents with status and sessions
`get_agent_status`	Detailed status of a running agent
`set_agent_status`	Set status text for an agent

Permission policies

Each session can use a different policy:

Policy	Behavior
`allow_all`	Auto-approve all agent actions
`deny_all`	Block all tool use
`elicit`	Forward as MCP elicitations to the host; falls back to `operator` if unsupported
`operator`	Queue as events — the host agent decides via `grant_permission`

Operator flow

code

Orchestrator                   MCACP                      ACP Agent
    |                            |                            |
    |-- prompt(sessionId, ...) ->|                            |
    |                            |-- session/prompt --------->|
    |                            |<- request_permission ------|
    |<- {pendingPermission: ...} |                            |
    |                            |                            |
    |-- grant_permission ------->|                            |
    |   {toolCallId, optionId}   |-- permission outcome ----->|
    |                            |<- prompt result -----------|
    |<- {stopReason, updates}    |                            |

Configuration

MCACP looks for mcacp.json in these locations (first found wins):

--config flag or MCACP_CONFIG env var
.mcacp/mcacp.json in the current directory
~/.config/mcacp/mcacp.json

jsonc

{
  "registries": ["https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json"],
  "defaultPermissionPolicy": "elicit",
  "agent_servers": {
    "my-custom-agent": {
      "command": "node",
      "args": ["my-agent.js"]
    }
  }
}

See docs/configuration.md for the full schema.

Building from source

bash

git clone https://github.com/Oortonaut/mcacp.git
cd mcacp
npm install
npm run build
node dist/index.js

License

Apache-2.0

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcacp": {
      "command": "npx",
      "args": [
        "-y",
        "mcacp@0.1.3"
      ]
    }
  }
}