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

> Configure MCP setup for Agent Zero in server and client modes. Learn how Agent Zero integrates with MCP for tool exposure and external server consumption.

- Repository: [Agent Zero/agent-zero](https://github.com/agent0ai/agent-zero)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/settings.json).
3. Save the configuration to trigger `MCPConfig.update()` in [`python/helpers/mcp_handler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/mcp_handler.py) (lines 321-329), which initializes a FastMCP instance from [`python/helpers/mcp_server.py`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/run_ui.py) script (line 543) triggers `MCPConfig.initialize()` during startup, creating the FastMCP instance defined in [`mcp_server.py`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/usr/settings.json) under the `"mcp_servers"` object, where each key represents a canonical server name mapped to connection parameters:

```json
{
  "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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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

```python
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`](https://github.com/agent0ai/agent-zero/blob/main/mcp_handler.py) lines 285-295).

### Invoking MCP Tools from Agent Scripts

```python
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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/mcp_handler.py) to manage bidirectional protocol support.
- Configuration persists in [`usr/settings.json`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/usr/settings.json) manually:

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

```

When [`run_ui.py`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/run_ui.py) lines 128-130).