ACP to MCP Adapter

1<div align="left">
2 
3<h1>ACP to MCP Adapter</h1>
4 
5**Connect ACP Agents to MCP Applications Seamlessly**
6 
7[![Apache 2.0](https://img.shields.io/badge/Apache%202.0-License-EA7826?style=plastic&logo=apache&logoColor=white)](https://github.com/i-am-bee/beeai-framework?tab=Apache-2.0-1-ov-file#readme)
8[![Follow on Bluesky](https://img.shields.io/badge/Follow%20on%20Bluesky-0285FF?style=plastic&logo=bluesky&logoColor=white)](https://bsky.app/profile/beeaiagents.bsky.social)
9[![Join our Discord](https://img.shields.io/badge/Join%20our%20Discord-7289DA?style=plastic&logo=discord&logoColor=white)](https://discord.com/invite/NradeA6ZNF)
10[![LF AI & Data](https://img.shields.io/badge/LF%20AI%20%26%20Data-0072C6?style=plastic&logo=linuxfoundation&logoColor=white)](https://lfaidata.foundation/projects/)
11 
12</div>
13 
14The **ACP to MCP Adapter** is a lightweight standalone server that acts as a bridge between two AI ecosystems: **Agent Communication Protocol (ACP)** for agent-to-agent communication and **Model Context Protocol (MCP)** for connecting AI models to external tools. It allows MCP applications (like **Claude Desktop**) to discover and interact with ACP agents as resources.
15 
16## Capabilities & Tradeoffs
17 
18This adapter enables interoperability between ACP and MCP with specific benefits and tradeoffs:
19 
20### Benefits
21 
22- Makes ACP agents discoverable as MCP resources
23- Exposes ACP agent runs as MCP tools
24- Bridges two ecosystems with minimal configuration
25 
26### Current Limitations
27 
28- ACP agents become MCP tools instead of conversational peers
29- No streaming of incremental updates
30- No shared memory across servers
31- Basic content translation between formats without support for complex data structures
32 
33This adapter is best for situations where you need ACP agents in MCP environments and accept these compromises.
34 
35## Requirements
36 
37- Python 3.11 or higher
38- Installed Python packages: `acp-sdk`, `mcp`
39- An ACP server running (Tip: Follow the [ACP quickstart](https://github.com/i-am-bee/acp/blob/main/README.md#quickstart) to start one easily)
40- An MCP client application (We use [Claude Desktop](https://claude.ai/download) in the quickstart)
41 
42## Quickstart
43 
44**1. Run the Adapter**
45 
46Start the adapter and connect it to your ACP server:
47 
48```sh
49uvx acp-mcp http://localhost:8000
50```
51 
52> [!NOTE]
53> Replace `http://localhost:8000` with your ACP server URL if different.
54 
55<details> <summary><strong>Prefer Docker?</strong></summary>
56 
57```sh
58docker run -i --rm ghcr.io/i-am-bee/acp-mcp http://host.docker.internal:8000
59```
60 
61**Tip:** `host.docker.internal` allows Docker containers to reach services running on the host (adjust if needed for your setup).
62 
63</details> 
64 
65**2. Connect via Claude Desktop**
66 
67To connect via Claude Desktop, follow these steps:
681. Open the Claude menu on your computer and navigate to Settings (note: this is separate from the in-app Claude account settings).
692. Navigate to Developer > Edit Config
703. The config file will be created here:
71  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
72  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
734. Edit the file with the following:
74 
75```json
76{
77  "mcpServers": {
78    "acp-local": {
79      "command": "uvx",
80      "args": ["acp-mcp", "http://localhost:8000"]
81    }
82  }
83}
84```
85  
86<details> <summary><strong>Prefer Docker?</strong></summary>
87  
88```json
89{
90  "mcpServers": {
91    "acp-docker": {
92      "command": "docker",
93      "args": [
94        "run",
95        "-i",
96        "--rm",
97        "ghcr.io/i-am-bee/acp-mcp",
98        "http://host.docker.internal:8000"
99      ]
100    }
101  }
102}
103```
104 
105</details>
106 
107**3. Restart Claude Desktop and Invoke Your ACP Agent**
108 
109After restarting, invoke your ACP agent with:
110 
111```
112use "echo" agent with the "Good morning!" input
113```
114 
115Accept the integration and observe the agent running.
116 
117![Screenshot of Claude Desktop invoking the echo agent](docs/assets/running_echo.png)
118 
119![MCP Resources](docs/assets/attach-from-mcp.png)
120 
121> [!TIP]
122> ACP agents are also registered as **MCP resources** in Claude Desktop.<br />
123> To attach them manually, click the Resources icon (two plugs connecting) in the sidebar, labeled "Attach from MCP", then select an agent like `acp://agents/echo`.
124 
125## How It Works
126 
1271. The adapter connects to your ACP server.
1282. It automatically discovers all registered ACP agents.
1293. Each ACP agent is registered in MCP as a resource using the URI: `acp://agents/{agent_name}`
1304. The adapter provides a new MCP tool called `run_agent`, letting MCP apps easily invoke ACP agents.
131 
132## Supported Transports
133 
134- Currently supports Stdio transport
135 
136---
137 
138Developed by contributors to the BeeAI project, this initiative is part of the [Linux Foundation AI & Data program](https://lfaidata.foundation/projects/). Its development follows open, collaborative, and community-driven practices.
139