| 1 | # MCP Setup |
| 2 | |
| 3 | MCP lets Agent Zero use tools from other apps and services. |
| 4 | |
| 5 | Think of each MCP connection as a bridge. One bridge might connect Gmail, |
| 6 | another might connect a database, and another might connect an automation app. |
| 7 | |
| 8 | Use MCP when you have a clear external tool you want Agent Zero to call. For |
| 9 | normal browsing, start with Agent Zero's built-in Browser first. |
| 10 | |
| 11 | > [!NOTE] |
| 12 | > This page is about giving Agent Zero tools from other apps. For deeper MCP |
| 13 | > details, see the [advanced MCP reference](../developer/mcp-configuration.md). |
| 14 | |
| 15 | ## When To Use MCP |
| 16 | |
| 17 | | Need | Good first stop | |
| 18 | | --- | --- | |
| 19 | | Browse, screenshot, annotate, or use the Docker browser | [Browser Guide](browser.md) | |
| 20 | | Use your host Chrome-family browser through A0 CLI | [A0 CLI Connector](a0-cli-connector.md#host-browser) | |
| 21 | | Connect a third-party app or service with MCP support | This guide | |
| 22 | | Paste or review MCP JSON by hand | [Advanced MCP Configuration](../developer/mcp-configuration.md) | |
| 23 | |
| 24 | ## Before You Add One |
| 25 | |
| 26 | - [ ] You know what app or service you want to connect. |
| 27 | - [ ] You trust the package or URL. |
| 28 | - [ ] You know where it will run: inside Agent Zero, on your computer, or online. |
| 29 | - [ ] You have any needed credentials ready. |
| 30 | - [ ] You know whether the tool should be project-specific or global. |
| 31 | |
| 32 | ## Open MCP Settings |
| 33 | |
| 34 | 1. Click **Settings** in the sidebar. |
| 35 | 2. Open the **MCP/A2A** tab. |
| 36 | 3. Find **External MCP Servers**. |
| 37 | 4. Click **Open**. |
| 38 | |
| 39 |  |
| 40 | |
| 41 | ## Add A Connection |
| 42 | |
| 43 | The configuration editor accepts JSON. A command-based MCP connection looks like |
| 44 | this: |
| 45 | |
| 46 | ```json |
| 47 | { |
| 48 | "mcpServers": { |
| 49 | "chrome-devtools": { |
| 50 | "command": "npx", |
| 51 | "args": ["-y", "chrome-devtools-mcp@latest"] |
| 52 | } |
| 53 | } |
| 54 | } |
| 55 | ``` |
| 56 | |
| 57 |  |
| 58 | |
| 59 | Click **Apply now** after editing. |
| 60 | |
| 61 | > [!TIP] |
| 62 | > The first launch of an `npx` or `uvx` server can take a little longer because |
| 63 | > the package may need to download. |
| 64 | |
| 65 | ## Check That It Connected |
| 66 | |
| 67 | After applying the config, look for the status below the editor. |
| 68 | |
| 69 | | Signal | What it means | |
| 70 | | --- | --- | |
| 71 | | Name | The connection Agent Zero found. | |
| 72 | | Tool count | How many tools are available. | |
| 73 | | Green status | The connection is working. | |
| 74 | | Error text | The command, URL, network, or credentials need attention. | |
| 75 | |
| 76 | After the connection works, Agent Zero discovers the MCP tools. The active |
| 77 | Agent Profile's MCP policy still decides which discovered tools it may use. Use |
| 78 | **Edit agent -> MCPs** to keep the category default or set an individual tool |
| 79 | to **On** or **Off**. See [Agent Profiles](agent-profiles.md#choose-capability-access). |
| 80 | |
| 81 | You can still ask naturally: |
| 82 | |
| 83 | ```text |
| 84 | Use the connected Gmail tools to find the last message from Alice and summarize it. |
| 85 | ``` |
| 86 | |
| 87 | ## Common Examples |
| 88 | |
| 89 | ### Tool Started By A Command |
| 90 | |
| 91 | Use this pattern when Agent Zero should start the tool itself. |
| 92 | |
| 93 | ```json |
| 94 | { |
| 95 | "mcpServers": { |
| 96 | "sqlite": { |
| 97 | "command": "uvx", |
| 98 | "args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"] |
| 99 | } |
| 100 | } |
| 101 | } |
| 102 | ``` |
| 103 | |
| 104 | ### Tool At A URL |
| 105 | |
| 106 | Use this pattern when the tool is already running at a URL. |
| 107 | |
| 108 | ```json |
| 109 | { |
| 110 | "mcpServers": { |
| 111 | "external-api": { |
| 112 | "url": "https://api.example.com/mcp", |
| 113 | "headers": { |
| 114 | "Authorization": "Bearer YOUR_API_KEY" |
| 115 | } |
| 116 | } |
| 117 | } |
| 118 | } |
| 119 | ``` |
| 120 | |
| 121 | > [!IMPORTANT] |
| 122 | > Do not paste real API keys into public files, screenshots, or issue reports. |
| 123 | > Prefer project secrets or environment variables when possible. |
| 124 | |
| 125 | ## Docker Networking |
| 126 | |
| 127 | If Agent Zero runs in Docker and the MCP tool runs somewhere else, the address |
| 128 | matters. |
| 129 | |
| 130 | | Where the MCP tool runs | What to use from Agent Zero | |
| 131 | | --- | --- | |
| 132 | | Host machine on macOS or Windows | `host.docker.internal` | |
| 133 | | Another container | Same Docker network plus the container name | |
| 134 | | Remote server | The reachable HTTPS URL | |
| 135 | | Inside Agent Zero's container | Local command config | |
| 136 | |
| 137 | On Linux, `host.docker.internal` is not always available by default. Running the |
| 138 | MCP tool in the same Docker network is usually cleaner. |
| 139 | |
| 140 | ## Browser MCP Or Built-In Browser? |
| 141 | |
| 142 | For most browsing tasks, use Agent Zero's built-in `_browser` plugin and direct |
| 143 | `browser` tool. It covers the Docker browser surface, screenshots, annotations, |
| 144 | Chrome extensions, and optional A0 CLI host-browser mode. |
| 145 | |
| 146 | MCP-based browser tools are still useful when another browser tool is required |
| 147 | for a specific workflow. |
| 148 | |
| 149 | See the [Browser Guide](browser.md) for the built-in workflow. |
| 150 | |
| 151 | ## Recommended Server Types |
| 152 | |
| 153 | | Tool type | Useful for | |
| 154 | | --- | --- | |
| 155 | | Chrome DevTools MCP | Direct Chrome debugging/control workflows | |
| 156 | | Playwright MCP | Alternative browser automation stacks | |
| 157 | | n8n MCP | Workflow automation | |
| 158 | | Gmail MCP | Email workflows | |
| 159 | | VS Code MCP | IDE-centered workflows | |
| 160 | |
| 161 | ## Troubleshooting |
| 162 | |
| 163 | - **No tools appear:** confirm the JSON is valid and click **Apply now** again. |
| 164 | - **Command not found:** install the command where Agent Zero can run it, or use a URL-based tool instead. |
| 165 | - **Package launch is slow:** wait for the first package download to finish. |
| 166 | - **Host service unreachable:** check Docker networking and try `host.docker.internal` on macOS or Windows. |
| 167 | - **Credentials fail:** rotate or re-enter the credential, then restart or reapply the config. |
| 168 | |
| 169 | ## Related |
| 170 | |
| 171 | - [Browser Guide](browser.md): built-in browsing, screenshots, annotations, Docker browser, and host-browser mode. |
| 172 | - [A0 CLI Connector](a0-cli-connector.md): host-machine access and Bring Your Own Browser setup. |
| 173 | - [Advanced MCP Configuration](../developer/mcp-configuration.md): complete configuration reference. |