ACP-MCP-Server
A bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.
✨ Features
- 🔄 Protocol Bridge: Seamlessly connects ACP agents with MCP clients
- 🚀 Multiple Transports: Supports STDIO, SSE, and Streamable HTTP
- 🤖 Agent Discovery: Automatic discovery and registration of ACP agents
- 🧠 Smart Routing: Intelligent routing of requests to appropriate agents
- 🔄 Async Support: Full support for synchronous and asynchronous operations
- 💬 Interactive Sessions: Support for multi-turn agent interactions
- 🌐 Multi-Modal: Handle text, images, and other content types
🚀 Quick Start
Installation
# Install from PyPI
pip install acp-mcp-server
# Or use uvx for isolated execution
uvx acp-mcp-server
Basic Usage
# Run with STDIO (default, for Claude Desktop)
acp-mcp-server
# Run with SSE transport
acp-mcp-server --transport sse --port 8000
# Run with HTTP transport
acp-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000
# Connect to different ACP server
acp-mcp-server --acp-url http://localhost:8001
Using with Claude Desktop
Add to your Claude Desktop configuration:
{
"mcpServers": {
"acp-bridge": {
"command": "uvx",
"args": ["acp-mcp-server"]
}
}
}
📋 Requirements
- Python 3.11+
- Running ACP server with agents
- FastMCP for protocol implementation
🔧 Configuration
Environment Variables
ACP_BASE_URL: ACP server URL (default:http://localhost:8000)
Command Line Options
usage: acp-mcp-server [-h] [--transport {stdio,sse,streamable-http}] [--host HOST] [--port PORT] [--path PATH] [--acp-url ACP_URL] [--version]
options:
-h, --help show this help message and exit
--transport {stdio,sse,streamable-http}
Transport protocol (default: stdio)
--host HOST Host address for HTTP transports (default: 127.0.0.1)
--port PORT Port number for HTTP transports (default: 8000)
--path PATH URL path for HTTP transports (default: /mcp)
--acp-url ACP_URL ACP server URL (default: http://localhost:8000)
--version show program's version number and exit
🛠️ Available Tools
The bridge server provides several MCP tools:
Agent Management
discover_acp_agents: Discover available ACP agentsget_agent_info: Get detailed information about specific agents
Agent Execution
run_acp_agent: Execute agents in sync/async modesget_async_run_result: Retrieve results from async executionslist_active_runs: List all active agent runs
Smart Routing
smart_route_request: Intelligently route requests to best agentstest_routing: Test routing logic without executionadd_routing_rule: Add custom routing ruleslist_routing_strategies: View all routing strategies
Interactive Sessions
start_interactive_agent: Start interactive agent sessionsprovide_user_input: Provide input to waiting agentslist_pending_interactions: View pending interactions
Message Processing
convert_acp_message: Convert between ACP and MCP formatsanalyze_message_content: Analyze message structure and content
🏗️ Architecture
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Client │ │ ACP-MCP Bridge │ │ ACP Agents │
│ (Claude Desktop)│◄──►│ Server │◄──►│ (echo, chat, │
│ │ │ │ │ translate...) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
MCP Protocol Protocol Bridge ACP Protocol
(STDIO/SSE/HTTP) (FastMCP + aiohttp) (HTTP/WebSocket)
🔌 Transport Modes
STDIO (Default)
Perfect for Claude Desktop integration:
acp-mcp-server
SSE (Server-Sent Events)
For web applications and streaming:
acp-mcp-server --transport sse --port 8000
Streamable HTTP
For REST API integration:
acp-mcp-server --transport streamable-http --port 9000
🐳 Docker
Quick Start with Docker
# Build the image
docker build -t acp-mcp-server .
# Run with Streamable HTTP transport
docker run -p 9000:9000 acp-mcp-server
# Run with SSE transport
docker run -p 8000:8000 acp-mcp-server \
--transport sse --host 0.0.0.0 --port 8000
# Connect to custom ACP server
docker run -p 9000:9000 -e ACP_BASE_URL=http://my-acp-server:8001 acp-mcp-server
Using Docker Compose
# Run HTTP transport service
docker-compose up acp-mcp-http
# Run SSE transport service
docker-compose up acp-mcp-sse
# Run both services
docker-compose up
# Run development mode with live code reload
docker-compose --profile dev up acp-mcp-dev
Production Docker Image
For production deployments, use the multi-stage Dockerfile:
# Build production image
docker build -f Dockerfile.prod -t acp-mcp-server:prod .
# Run production container
docker run -d \
--name acp-mcp-server \
--restart unless-stopped \
-p 9000:9000 \
-e ACP_BASE_URL=http://your-acp-server:8000 \
acp-mcp-server:prod
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🔗 Related Projects
- FastMCP - Fast, Pythonic MCP server framework
- ACP SDK - Agent Communication Protocol SDK
- Claude Desktop - AI assistant with MCP support