Overview

The MCP-to-ACP Proxy enables Model Context Protocol (MCP) clients, such as IDEs and development tools, to communicate with Agent Client Protocol (ACP) agents through stdio Bus kernel. It acts as a protocol bridge, translating MCP messages to ACP format and routing them to the appropriate agents.

Location: workers-registry/mcp-to-acp-proxy/

Architecture

The proxy sits between MCP clients and stdio Bus, enabling seamless integration without requiring clients to implement the ACP protocol directly.

Features

• Protocol Translation: Converts MCP messages to ACP format and vice versa
• IDE Integration: Works with any MCP-compatible IDE or development tool
• Agent Routing: Routes messages to specific ACP agents via AGENT_ID configuration
• Session Management: Maintains session state across the protocol bridge
• Transparent Operation: Clients interact using standard MCP protocol
• TypeScript Support: Full type definitions for type-safe development

Configuration

IDE Configuration

Configure the proxy in your IDE's MCP settings. The exact configuration format depends on your IDE, but typically follows this pattern:

Kiro IDE Configuration

Add to your Kiro MCP settings:

{
  "mcpServers": {
    "stdio-bus-acp": {
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "mcp-to-acp-proxy"
      ],
      "env": {
        "ACP_HOST": "localhost",
        "ACP_PORT": "9000",
        "AGENT_ID": "claude-acp"
      }
    }
  }
}

Generic MCP Client Configuration

{
  "mcpServers": {
    "stdio-bus-acp": {
      "command": "stdiobus-mcp-to-acp-proxy",
      "env": {
        "ACP_HOST": "0.0.0.0",
        "ACP_PORT": "9000",
        "AGENT_ID": "claude-acp"
      }
    }
  }
}

Environment Variables

stdio Bus Configuration

Ensure stdio Bus kernel is running with Registry Launcher or ACP Worker:

{
  "pools": [
    {
      "id": "registry-launcher",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "registry-launcher",
        "./api-keys.json"
      ],
      "instances": 1
    }
  ]
}

Use Cases

IDE Integration

Connect your IDE to ACP agents through stdio Bus:

1. Configure stdio Bus: Start stdio Bus kernel with Registry Launcher
2. Configure IDE: Add MCP-to-ACP Proxy to your IDE's MCP settings
3. Select Agent: Set AGENT_ID to your desired agent (e.g., claude-acp, goose)
4. Start Coding: Your IDE can now communicate with the ACP agent

Benefits:

• Use any ACP agent from your IDE
• No need to implement ACP protocol in your IDE
• Leverage stdio Bus routing and session management
• Switch between agents by changing AGENT_ID

Multi-Agent Workflows

Route different IDE instances to different agents:

{
  "mcpServers": {
    "claude-agent": {
      "command": "stdiobus-mcp-to-acp-proxy",
      "env": {
        "ACP_HOST": "localhost",
        "ACP_PORT": "9000",
        "AGENT_ID": "claude-acp"
      }
    },
    "goose-agent": {
      "command": "stdiobus-mcp-to-acp-proxy",
      "env": {
        "ACP_HOST": "localhost",
        "ACP_PORT": "9000",
        "AGENT_ID": "goose"
      }
    }
  }
}

Development and Testing

Use the proxy for testing ACP agents with MCP clients:

# Terminal 1: Start stdio Bus with Registry Launcher
docker run -p 9000:9000 \
  -v $(pwd)/workers-registry:/workers-registry:ro \
  -v $(pwd)/config.json:/config.json:ro \
  stdiobus/stdiobus:latest \
  --config /config.json --tcp 0.0.0.0:9000
 
# Terminal 2: Start MCP-to-ACP Proxy
export ACP_HOST=localhost
export ACP_PORT=9000
export AGENT_ID=claude-acp
npx @stdiobus/workers-registry mcp-to-acp-proxy
 
# Terminal 3: Connect with MCP client
# Your MCP client will communicate through the proxy

Remote Agent Access

Connect to remote stdio Bus instances:

{
  "mcpServers": {
    "remote-agent": {
      "command": "stdiobus-mcp-to-acp-proxy",
      "env": {
        "ACP_HOST": "agent-server.example.com",
        "ACP_PORT": "9000",
        "AGENT_ID": "claude-acp"
      }
    }
  }
}

Protocol Bridging

Message Flow

1. MCP Client → Proxy: IDE sends MCP protocol message
2. Proxy → stdio Bus: Proxy translates to ACP format and sends via TCP/Unix socket
3. stdio Bus → Worker: Kernel routes to appropriate worker (Registry Launcher or ACP Worker)
4. Worker → Agent: Worker spawns or routes to target ACP agent
5. Agent → Worker: Agent processes request and returns response
6. Worker → stdio Bus: Response sent back through kernel
7. stdio Bus → Proxy: Kernel routes response to proxy connection
8. Proxy → MCP Client: Proxy translates to MCP format and returns to IDE

Protocol Translation

The proxy handles translation between MCP and ACP message formats:

MCP Initialize Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-ide",
      "version": "1.0.0"
    }
  }
}

Translated to ACP:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "agentId": "claude-acp",
    "clientInfo": {
      "name": "my-ide",
      "version": "1.0.0"
    }
  }
}

Session Preservation

The proxy maintains session state across the protocol bridge:

• Session IDs are preserved during translation
• Stateful interactions are routed to the same agent instance
• Connection state is synchronized between MCP and ACP layers

Testing

Verify stdio Bus Connection

Ensure stdio Bus kernel is accessible:

# Test TCP connection
nc -zv localhost 9000
 
# Test with echo message
echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test"}}}' | nc localhost 9000

Test Proxy Standalone

Run the proxy and verify it starts without errors:

export ACP_HOST=localhost
export ACP_PORT=9000
export AGENT_ID=claude-acp
 
npx @stdiobus/workers-registry mcp-to-acp-proxy

Expected output (to stderr):

MCP-to-ACP Proxy starting...
Connecting to stdio Bus at localhost:9000
Target agent: claude-acp
Proxy ready

Test with MCP Client

Configure your MCP client with the proxy and send a test message. The proxy should:

1. Accept the MCP connection
2. Translate the message to ACP format
3. Forward to stdio Bus
4. Receive the response
5. Translate back to MCP format
6. Return to the client

Troubleshooting

Connection Refused

Symptom: Proxy cannot connect to stdio Bus

Solutions:

• Verify ACP_HOST and ACP_PORT environment variables
• Check firewall rules if connecting to remote host

Agent Not Found

Symptom: Error message about unknown agent ID

Solutions:

• Verify AGENT_ID matches an available agent in the ACP Registry
• Check Registry Launcher is running in stdio Bus
• Ensure API keys are configured if required by the agent

Protocol Errors

Symptom: Message format errors or unexpected responses

Solutions:

• Verify MCP client is using compatible protocol version
• Check proxy logs for translation errors
• Ensure stdio Bus kernel is up to date

IDE Not Detecting Proxy

Symptom: IDE doesn't show the MCP server

Solutions:

• Verify command path is correct in IDE configuration
• Check environment variables are set properly
• Restart IDE after configuration changes

Programmatic Usage

Module Import

// Import MCP-to-ACP Proxy
import mcpToAcpProxy from '@stdiobus/workers-registry/workers/mcp-to-acp-proxy';

TypeScript Types

import type { MCPToACPProxy } from '@stdiobus/workers-registry/workers/mcp-to-acp-proxy';
 
// Use types for type-safe development
const proxy: MCPToACPProxy = /* ... */;

Next Steps

• Registry Launcher - Agent routing
• ACP Worker - Direct ACP integration

Resources

• Model Context Protocol
• MCP-to-ACP Proxy Source