How to Configure MCP Setup for Agent Zero: Server and Client Modes

Agent Zero supports bidirectional MCP (Model Context Protocol) integration, allowing it to expose built-in tools as an MCP server via FastMCP while simultaneously consuming external MCP servers through the MCPConfig singleton that manages configurations in usr/settings.json.

Agent Zero (agent0ai/agent-zero) implements full bidirectional MCP support, enabling both exposure of its native capabilities as an MCP server and consumption of external tool providers. The MCP setup for Agent Zero centers on the MCPConfig singleton class in python/helpers/mcp_handler.py, which orchestrates configuration persistence, server lifecycle management, and tool call routing through a centralized JSON configuration.

Understanding the MCP Configuration Architecture

Core Configuration Files and Classes

The MCP configuration lives in the user-level usr/settings.json file, specifically under the "mcp_servers" key for external connections and the "mcp_server" key for the built-in server. The MCPConfig class in python/helpers/mcp_handler.py (lines 63-102) implements a singleton pattern responsible for parsing this JSON, instantiating either MCPServerLocal or MCPServerRemote objects, and routing tool invocations to the appropriate endpoints.

Enabling Agent Zero as an MCP Server

To expose Agent Zero's native tools to external MCP clients, you enable the integrated MCP server through the UI or configuration file.

1. Navigate to Settings → MCP/A2A → A0 MCP Server in the web interface.
2. Toggle "Enable A0 MCP Server" to set "enabled": true in the "mcp_server" section of settings.json.
3. Save the configuration to trigger MCPConfig.update() in python/helpers/mcp_handler.py (lines 321-329), which initializes a FastMCP instance from python/helpers/mcp_server.py.

When active, the server listens on the same host/port as the web UI, exposing endpoints at /mcp/sse for streaming and /mcp/http for standard HTTP requests. The run_ui.py script (line 543) triggers MCPConfig.initialize() during startup, creating the FastMCP instance defined in mcp_server.py (lines 8-31) and registering built-in tools automatically.

Configuring External MCP Servers (Client Mode)

Agent Zero consumes external MCP servers by maintaining client connections to remote tool providers, enabling access to specialized capabilities like browser automation or workflow orchestration.

JSON Configuration Format

External servers are defined in usr/settings.json under the "mcp_servers" object, where each key represents a canonical server name mapped to connection parameters:

{
  "mcp_servers": {
    "chrome_devtools": {
      "type": "remote_http",
      "url": "http://localhost:8123/mcp/http",
      "description": "Control Chrome via DevTools protocol"
    },
    "playwright": {
      "type": "remote_http",
      "url": "http://localhost:8124/mcp/http",
      "description": "Cross-browser automation"
    },
    "n8n_workflow": {
      "type": "remote_http",
      "url": "https://n8n.example.com/mcp/http",
      "description": "Orchestrate workflows"
    }
  }
}

Server Types and Tool Routing

The MCPConfig.update() method (lines 85-101 and 221-244 in mcp_handler.py) processes each entry and creates appropriate client objects:

• MCPServerLocal: For type: "local" or "stdio" connections
• MCPServerRemote: For type: "remote_http" or "remote_sse" connections

When the LLM requests a tool using the server_name.tool_name naming convention, the process_tools pipeline invokes MCPConfig.get_instance().call_tool() (lines 107-115). This method delegates to the underlying MCPClientRemote or MCPClientLocal instance, which transmits the request via HTTP/SSE and returns the parsed JSON response (lines 115-124).

Authentication and Security

Agent Zero reuses the same API token generated for external API access to secure MCP connections. The UI displays this token under Settings → MCP/A2A → Token. External clients must include the header Authorization: Bearer <token> when connecting to Agent Zero's MCP server endpoints, ensuring unified security across MCP server access, external API calls, and A2A links (see run_ui.py lines 128-130).

Programmatic MCP Configuration

For dynamic configuration without UI interaction, interact directly with the MCPConfig singleton.

Updating MCP Servers at Runtime

from python.helpers.mcp_handler import MCPConfig

# Define new server configuration

new_mcp_cfg = {
    "chrome_devtools": {
        "type": "remote_http",
        "url": "http://localhost:8123/mcp/http",
        "description": "Chrome DevTools control"
    },
    "playwright": {
        "type": "remote_http",
        "url": "http://localhost:8124/mcp/http",
        "description": "Cross-browser automation"
    }
}

# Apply configuration immediately

MCPConfig.get_instance().update({"mcp_servers": new_mcp_cfg})
print("MCP configuration refreshed")

The update() method validates the dictionary, instantiates appropriate server objects, and initializes client connections without requiring a restart (see mcp_handler.py lines 285-295).

Invoking MCP Tools from Agent Scripts

from python.helpers.mcp_handler import MCPConfig

async def capture_screenshot():
    # Target tool using server_name.tool_name convention

    tool_name = "chrome_devtools.screenshot"
    arguments = {"url": "https://example.com"}
    
    result = await MCPConfig.get_instance().call_tool(tool_name, arguments)
    print("Screenshot received:", result["image_base64"])

# Execute in async context: await capture_screenshot()

This pattern enables agents to leverage external capabilities while maintaining consistent error handling and response parsing through the centralized handler.

Advanced Configuration Options

For production deployments requiring TLS, custom project scoping, or dynamic hot-reloading, refer to docs/developer/mcp-configuration.md. This documentation covers server type specifications (remote_http, remote_sse, local_stdio), project path isolation for namespace management, and certificate configuration for HTTPS endpoints.

Summary

• MCP setup for Agent Zero relies on the MCPConfig singleton in python/helpers/mcp_handler.py to manage bidirectional protocol support.
• Configuration persists in usr/settings.json with separate keys for the built-in server (mcp_server) and external clients (mcp_servers).
• Enable the integrated server via Settings → MCP/A2A to expose Agent Zero tools at /mcp/sse and /mcp/http endpoints using FastMCP.
• Add external servers by defining JSON objects with type, url, and description fields; the system automatically creates MCPServerRemote or MCPServerLocal instances.
• Tool calls use the server_name.tool_name pattern and route through MCPConfig.call_tool() to the appropriate HTTP/SSE client.
• Authentication uses a shared Bearer token displayed in the MCP/A2A settings panel, securing both incoming and outgoing connections.

Frequently Asked Questions

Where is the MCP configuration stored in Agent Zero?

The configuration lives in usr/settings.json at the user level. The mcp_servers key contains external server definitions, while the mcp_server key controls the built-in FastMCP instance. The MCPConfig class in python/helpers/mcp_handler.py handles parsing and validation of these settings at runtime.

How does Agent Zero route tool calls to external MCP servers?

When a tool request matches the server_name.tool_name pattern, MCPConfig.get_instance().call_tool() (lines 107-124 in mcp_handler.py) extracts the server prefix and delegates to the corresponding client object. Remote servers receive HTTP POST requests at their configured URLs, while local servers communicate via stdio streams.

Can I enable the Agent Zero MCP server without using the web UI?

Yes. Add the following block to usr/settings.json manually:

{
  "mcp_server": {
    "enabled": true,
    "type": "local_stdio",
    "command": "npx fastmcp@latest"
  }
}

When run_ui.py starts (line 543), it calls MCPConfig.initialize(), which detects the enabled flag and instantiates the FastMCP server from python/helpers/mcp_server.py.

What authentication is required for MCP connections?

Agent Zero uses a single API token for all MCP/A2A security. External clients must provide Authorization: Bearer <token> headers when connecting to your Agent Zero instance. This same token secures the web UI and external API endpoints, ensuring consistent access control across all interfaces (see run_ui.py lines 128-130).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}