Content
DISCLAIMER: AI SLOP, HAVENT READ ANY OF THE CODE
# ACP-to-MCP Bridge
Wrap any [ACP](https://agentclientprotocol.com)-compatible agent as an [MCP](https://modelcontextprotocol.io) server. An orchestrator with an expensive model delegates tasks to a cheaper subagent via MCP tool calls.
```
Orchestrator (Claude Code / Copilot) ──MCP──▶ Bridge ──ACP──▶ Subagent (OpenCode)
```
## Quick Start
No install needed — run via `npx`:
```bash
npx acp-mcp-bridge \
--model coder:openrouter/openai/gpt-4o-mini \
--model reviewer:openrouter/deepseek/deepseek-v3.2
```
Or from source:
```bash
git clone ... && cd acp-mcp-bridge
npm install && npm run build
node dist/index.js --model coder:openrouter/openai/gpt-4o-mini
```
## MCP Config Examples
### Copilot
Place in `~/.copilot/_user/mcps/acp.json`:
```json
{
"mcpServers": {
"acp-bridge": {
"tools": ["*"],
"type": "stdio",
"command": "npx",
"args": [
"-y", "acp-mcp-bridge",
"--model", "coder:openrouter/openai/gpt-4o-mini",
"--model", "reviewer:openrouter/deepseek/deepseek-v3.2"
]
}
}
}
```
### Claude Code
Place in `.mcp.json` in your project root:
```json
{
"mcpServers": {
"acp-bridge": {
"command": "npx",
"args": [
"-y", "acp-mcp-bridge",
"--model", "coder:openrouter/openai/gpt-4o-mini",
"--model", "reviewer:openrouter/deepseek/deepseek-v3.2"
]
}
}
}
```
### Running against opencode locally
If opencode is already configured with providers, use bare model IDs without prefix:
```bash
npx acp-mcp-bridge --model fast:gpt-5-nano --model smart:claude-sonnet-4-20250514
```
Check available models with the `agent_list_models` tool after startup.
## MCP Tools
| Tool | Description |
|---|---|
| `agent_prompt` | One-off prompt — full lifecycle per call, no state persisted |
| `agent_session_new` | Create a persistent session + send initial prompt |
| `agent_session_prompt` | Continue conversation in an existing session |
| `agent_session_cancel` | Cancel an ongoing prompt |
| `agent_session_close` | Close a session (preserves output files) |
| `agent_session_list` | List sessions in the current workspace |
| `agent_session_load` | Resume a previous session |
| `agent_session_fork` | Fork an existing session (if agent supports it) |
| `agent_session_delete` | Permanently delete a session + output files |
| `agent_list_models` | List available models with aliases |
## Model Aliases
The `--model` flag defines both an **alias** and an **allowlist entry**:
```bash
--model coder:openrouter/openai/gpt-4o-mini # alias:model_id
--model reviewer:openrouter/deepseek/deepseek-v3.2
--model bare-model-id # no alias, just whitelist
```
- `agent_list_models` reports aliases, not raw model IDs
- All prompt tools accept the alias as the `model` parameter
- If no `--model` flags are given, all agent models are available unfiltered
- Each `--model` flag acts as an allowlist — unlisted models are inaccessible
## Output Files
Subagent responses are written to `.acp-as-mcp/outputs/` (not returned inline, to avoid context bloat). MCP tool responses include a path and summary — the orchestrator reads the file when it needs the full output.
| Call | Output file |
|---|---|
| `agent_prompt` | `outputs/oneshot-{timestamp}.md` |
| `agent_session_new` / `agent_session_prompt` | `outputs/{sessionId}-turn-{N}.md` |
One-off files: kept 10 most recent. Session outputs: deleted with the session.
Sessions: auto-pruned to 20 most recent. Logs: `.acp-as-mcp/logs/`, also 20 most recent.
## Smoke Test
```bash
npm run build && node scripts/smoke-test.mjs
```
Tests MCP connection, all 9+ tools, sequential one-off prompts, session create/continue/list/close.
## Spec
Full design document: [docs/spec.md](docs/spec.md).
Upstream ACP protocol docs: [docs/upstream/acp/](docs/upstream/acp/).
