Skip to main content
Glama
Sign In
ACP-MCP-Server

ACP-MCP-Server

by GongRzhe
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

ACP-MCP-Server

PyPI version Python 3.11+ License: MIT

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

Related MCP server: A2A MCP Server

🚀 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

📞 Support

Available Tools

16 tools
add_routing_ruleC

Add a new routing rule to a strategy

Inputs: agent_name (required), keywords (required), strategy_name (required), description, +1 more. Returns: result

analyze_message_contentC

Analyze the content types and structure of an ACP message

Inputs: acp_message_json (required). Returns: result

cancel_interactionC

Cancel a pending interactive agent

Inputs: run_id (required). Returns: result

convert_acp_messageB

Convert ACP message format to MCP-compatible format

Inputs: acp_message_json (required). Returns: result

discover_acp_agentsB

Discover all available ACP agents and register them as resources

Inputs: no named parameters. Returns: result

get_agent_infoC

Get detailed information about a specific ACP agent

Inputs: agent_name (required). Returns: result

get_async_run_resultC

Get the result of an asynchronous run

Inputs: run_id (required). Returns: result

get_server_infoB

Get information about the ACP-MCP bridge server

Inputs: no named parameters. Returns: result

list_active_runsB

List all active runs

Inputs: no named parameters. Returns: result

list_pending_interactionsB

List all pending interactive agents waiting for input

Inputs: no named parameters. Returns: result

list_routing_strategiesB

List all available routing strategies and their rules

Inputs: no named parameters. Returns: result

provide_user_inputC

Provide user input to resume a waiting interactive agent

Inputs: run_id (required), user_input (required). Returns: result

run_acp_agentC

Execute an ACP agent with specified mode

Inputs: agent_name (required), input_text (required), mode, session_id. Returns: result

smart_route_requestC

Intelligently route a request to the best ACP agent

Inputs: input_text (required), mode, session_id, strategy. Returns: result

start_interactive_agentC

Start an interactive ACP agent that may require user input

Inputs: agent_name (required), initial_input (required), session_id, timeout_minutes. Returns: result

test_routingA

Test routing without executing - shows which agent would be selected

Inputs: input_text (required), strategy. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.3/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some potential overlap between 'smart_route_request' and 'test_routing' as both involve routing decisions, which could cause confusion. The other tools are clearly differentiated by their specific actions on agents, runs, interactions, or routing components.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures, such as 'add_routing_rule', 'analyze_message_content', and 'run_acp_agent'. This uniformity makes the tool set predictable and easy to navigate.

    Tool Count4/5

    With 16 tools, the count is slightly high but reasonable for an ACP-MCP bridge server covering discovery, routing, execution, and interaction management. It might feel a bit heavy, but each tool appears to serve a specific function in this domain.

    Completeness5/5

    The tool set provides comprehensive coverage for the ACP agent domain, including agent discovery, information retrieval, execution (synchronous and asynchronous), routing management, interaction handling, and message conversion. There are no obvious gaps, supporting full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers