What is Acp Mcp Server

ACP-MCP-Server is a bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, facilitating seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.

Use cases

Use cases include connecting ACP agents to Claude Desktop for enhanced AI interactions, enabling multi-modal communication in applications, and facilitating the development of intelligent systems that require dynamic agent interactions.

How to use

To use ACP-MCP-Server, install it via PyPI using ‘pip install acp-mcp-server’. You can run it with various transports like STDIO, SSE, or Streamable HTTP. For integration with Claude Desktop, add the server configuration to the desktop’s settings.

Key features

Key features include protocol bridging between ACP and MCP, support for multiple transports (STDIO, SSE, Streamable HTTP), automatic agent discovery, smart routing of requests, full async support, interactive multi-turn sessions, and multi-modal content handling.

Where to use

ACP-MCP-Server is used in fields requiring integration between AI agents and various tools, particularly in environments utilizing ACP-based AI systems and MCP-compatible applications.

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 agents
• get_agent_info: Get detailed information about specific agents

Agent Execution

• run_acp_agent: Execute agents in sync/async modes
• get_async_run_result: Retrieve results from async executions
• list_active_runs: List all active agent runs

Smart Routing

• smart_route_request: Intelligently route requests to best agents
• test_routing: Test routing logic without execution
• add_routing_rule: Add custom routing rules
• list_routing_strategies: View all routing strategies

Interactive Sessions

• start_interactive_agent: Start interactive agent sessions
• provide_user_input: Provide input to waiting agents
• list_pending_interactions: View pending interactions

Message Processing

• convert_acp_message: Convert between ACP and MCP formats
• analyze_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

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation