ACP Bridge MCP server for AI agents

ACP-MCP Server is a bridge that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients. This enables seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop, allowing them to communicate effectively.

Installation

You can install the ACP-MCP server using pip:

# Install from PyPI
pip install acp-mcp-server

Alternatively, for isolated execution, use uvx:

uvx acp-mcp-server

Basic Usage

The server can be run with different transport modes:

# 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

Integration with Claude Desktop

To use the ACP-MCP server with Claude Desktop, add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "acp-bridge": {
      "command": "uvx",
      "args": ["acp-mcp-server"]
    }
  }
}

Configuration Options

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

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 Deployment

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

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "acp-bridge" '{"command":"uvx","args":["acp-mcp-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "acp-bridge": {
            "command": "uvx",
            "args": [
                "acp-mcp-server"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "acp-bridge": {
            "command": "uvx",
            "args": [
                "acp-mcp-server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect