Integration

What are MCP Servers?

MCP servers are external tools that Agent Zero can use to perform specialized tasks. Popular examples include:

• Browser automation - Chrome DevTools, Playwright
• Workflow automation - n8n integration
• Email operations - Gmail management
• Database access - SQLite, PostgreSQL
• File operations - Advanced file system tools
• API integrations - Third-party service connectors

1. Click Settings in the sidebar
2. Navigate to the MCP/A2A tab
3. Click on External MCP Servers
4. Click the Open button to access the configuration editor

In the JSON editor, add your MCP server configuration. Here's a simple example:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

1. Click Apply now to save your configuration
2. The server status will appear below, showing:
   • Server name (e.g., chrome_devtools)
   • Number of available tools
   • Connection status (green indicator = connected)

Local Command-Based Server

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"]
    }
  }
}

Remote HTTP Server

{
  "mcpServers": {
    "external-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Multiple Servers Configuration

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "database": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/data/app.db"]
    },
    "external-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  }
}

If Agent Zero runs in Docker and your MCP server runs on the host:

• macOS/Windows: Use host.docker.internal in URLs

  {
    "url": "http://host.docker.internal:PORT/endpoint"
  }

• Linux: Run the MCP server in the same Docker network and use the container name

  {
    "url": "http://container_name:PORT/endpoint"
  }

Once connected, MCP tools become available to Agent Zero automatically. Tools are named with the server prefix:

Simply ask Agent Zero to perform tasks, and it will use the appropriate MCP tools when needed.

What is A2A?

A2A enables direct communication between multiple Agent Zero instances. This allows:

• Distributed workflows - Delegate tasks to specialized agent instances
• Context isolation - Maintain separate workspaces for different agents
• Long-running collaboration - Persistent agent-to-agent conversations
• Project-specific delegation - Route work to agents with specific project contexts

1. Click Settings in the sidebar
2. Navigate to the MCP/A2A tab
3. Scroll to the A0 A2A Server section
4. Toggle Enable A2A server to ON

1. Click on connection example to view your A2A connection details
2. The dialog displays:
   • API Token - Automatically generated from your username and password
   • A2A Connection URL - The full URL other agents will use to connect
   • Optional Project selector - To create project-specific connection URLs

1. Click Save to apply your settings
2. The A2A server is now active and ready to accept connections

Basic A2A Connection

http://YOUR_HOST:PORT/a2a/t-YOUR_API_TOKEN

With Project Context

To connect with a specific project active:

http://YOUR_HOST:PORT/a2a/t-YOUR_API_TOKEN/p-PROJECT_NAME

When a project is specified, all A2A conversations run in that project's context with access to project-specific resources and knowledge.

1. Local Development Setup

Two Agent Zero instances on the same machine:

Instance 1: http://localhost:8080/a2a/t-abc123xyz
Instance 2: http://localhost:8081/a2a/t-def456uvw

2. Remote Agent Collaboration

Connect to a remote Agent Zero instance:

http://agent.example.com:8080/a2a/t-remote-token

3. Project-Specific Delegation

Main agent delegates frontend work to specialized agent:

http://localhost:8081/a2a/t-frontend-token/p-webapp-ui

You can test A2A connectivity using curl:

curl -X POST http://localhost:8080/a2a/t-YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from another agent"}'

MCP Issues

Server Not Connecting

• Verify the A2A server is enabled in Settings
• Check that the Agent Zero instance is running
• Confirm the port is accessible (check firewall rules)
• Wrong URL or port configuration
• Missing authentication headers for remote servers

Tools Not Appearing

• Confirm server shows as connected (green status)
• Check server exposes tools (count shown in UI)
• Verify tool names match server documentation
• For npx/uvx servers, first run downloads packages (may take time)

A2A Issues

Connection Refused

• Verify the A2A server is enabled in Settings
• Check that the Agent Zero instance is running
• Confirm the port is accessible

Invalid Token

• Token may have changed due to credential updates
• Generate a new connection URL from Settings → MCP/A2A
• Update the connecting agent's configuration

Project Not Found

• Verify the project name in the URL matches exactly
• Check that the project exists in the target instance
• Project names are case-sensitive