A2AMCP MCP server for AI agents

A2AMCP is a Redis-backed Model Context Protocol (MCP) server that enables AI agents to communicate and collaborate in real-time while working on the same project. It solves the critical problem of isolated AI agents working on the same codebase without awareness of each other's changes, preventing conflicts and enabling seamless coordination.

Installation

Using Docker (Recommended)

# Clone the repository
git clone https://github.com/webdevtodayjason/A2AMCP
cd A2AMCP

# Start the server
docker-compose up -d

# Verify it's running
docker ps | grep splitmind

# Test the connection
python verify_mcp.py

Docker Compose Configuration

services:
  mcp-server:
    build: .
    container_name: splitmind-mcp-server
    ports:
      - "5050:5000"  # Changed from 5000 to avoid conflicts
    environment:
      - REDIS_URL=redis://redis:6379
      - LOG_LEVEL=INFO
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  
  redis:
    image: redis:7-alpine
    container_name: splitmind-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  redis-data:
    driver: local

Python SDK Installation

pip install a2amcp-sdk

Configuration

Claude Code (CLI)

# Add the MCP server using Claude Code CLI
claude mcp add splitmind-a2amcp \
  -e REDIS_URL=redis://localhost:6379 \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py

Claude Desktop

Add to your configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "splitmind-a2amcp": {
      "command": "docker",
      "args": ["exec", "-i", "splitmind-mcp-server", "python", "/app/mcp-server-redis.py"],
      "env": {
        "REDIS_URL": "redis://redis:6379"
      }
    }
  }
}

Usage

Python SDK Example

from a2amcp import A2AMCPClient, Project, Agent

async def run_agent():
    client = A2AMCPClient("localhost:5000")
    project = Project(client, "my-app")
    
    async with Agent(project, "001", "feature/auth", "Build authentication") as agent:
        # Agent automatically registers and maintains heartbeat
        
        # Coordinate file access
        async with agent.files.coordinate("src/models/user.ts") as file:
            # File is locked, safe to modify
            pass
        # File automatically released
        
        # Share interfaces
        await project.interfaces.register(
            agent.session_name,
            "User",
            "interface User { id: string; email: string; }"
        )

Direct MCP Tool Usage

# Register agent
register_agent("my-project", "task-001", "001", "feature/auth", "Building authentication")

# Query another agent
query_agent("my-project", "task-001", "task-002", "interface", "What's the User schema?")

# Share interface
register_interface("my-project", "task-001", "User", "interface User {...}")

Core Features

Real-time Agent Communication

Direct queries between agents
Broadcast messaging
Async message queues

File Conflict Prevention

Automatic file locking
Conflict detection
Negotiation strategies

Shared Context Management

Interface/type registry
API contract sharing
Dependency tracking

Task Transparency

Todo list management
Progress visibility
Completion tracking
Task completion signaling

Troubleshooting

Agents can't see `mcpsplitmind-a2amcp` tools

Restart Claude Desktop - MCP connections are established at startup
Verify server is running: docker ps | grep splitmind
Check health endpoint: curl http://localhost:5050/health
Run verification script: python verify_mcp.py
Check configuration: Ensure your config file contains the A2AMCP server configuration

Common Issues

"Tool 'X' not yet implemented" - Fixed in latest version, pull latest changes
Connection failed - Ensure Docker is running and ports 5050/6379 are free
Redis connection errors - Wait for Redis to be ready (takes ~5-10 seconds on startup)

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 "splitmind-a2amcp" '{"command":"docker","args":["exec","-i","splitmind-mcp-server","python","/app/mcp-server-redis.py"],"env":{"REDIS_URL":"redis://redis:6379"}}'

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": {
        "splitmind-a2amcp": {
            "command": "docker",
            "args": [
                "exec",
                "-i",
                "splitmind-mcp-server",
                "python",
                "/app/mcp-server-redis.py"
            ],
            "env": {
                "REDIS_URL": "redis://redis:6379"
            }
        }
    }
}

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": {
        "splitmind-a2amcp": {
            "command": "docker",
            "args": [
                "exec",
                "-i",
                "splitmind-mcp-server",
                "python",
                "/app/mcp-server-redis.py"
            ],
            "env": {
                "REDIS_URL": "redis://redis:6379"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

A2AMCP MCP server