io.github.Oortonaut/mcacp
MCP-to-ACP bridge — let any MCP client drive ACP coding agents
Open source Open in the app JSON README (API)
About
MCP-to-ACP bridge — let any MCP client drive ACP coding agents
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- oortonaut
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Stars
- 9
- Forks
- 4
- Open pull requests
- 2
- Last push
- 2026-02-01T05:08:18Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:09
- Updated
- 2026-08-29 03:02:09
- Origin id
io.github.Oortonaut/mcacp
README
# MCACP
**Bridge any MCP client to any ACP coding agent.**
MCACP is an [MCP](https://modelcontextprotocol.io/) server that speaks the [Agent Client Protocol](https://agentclientprotocol.com/) 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.
```
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:
```
"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
```
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):
1. `--config` flag or `MCACP_CONFIG` env var
2. `.mcacp/mcacp.json` in the current directory
3. `~/.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](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](LICENSE)