--- title: How do I add a custom tool server (MCP) to codus? question: add an MCP server area: mcp order: 2 surface: desktop audience: beginner keywords: [add MCP server, MCP, custom tools, extra tools, servers, stdio, http, command, server url, arguments, environment, auth token, bearer, scope, quadrant, all surfaces, enable, disable, remove, connected, not connected, playwright, chrome bridge, plugin, add on] related: [what-are-custom-tools-mcp, codus-manages-your-mcp-config, mcp-servers-and-agent-browser] updated: 2026-07-21 --- # How do I add a custom tool server (MCP) to codus? Open the gear (**⚙**), click **See all settings →**, then click **MCP servers**. Click **Add MCP server** (or one of the **Quick add** templates), give it a **Name**, pick a **Type**, fill in what that type needs, choose which agents get it, and click **Save**. Its tools reach the matching agents within seconds, including any agent that is mid-conversation, and no restart is needed. ## Before you start - Have the server's details ready. For a local program, that is the command to run. For a remote server, that is its web address, and a token if it needs one. - Know the safety trade-off. A **Command** server, described below, runs a program on your Mac with your agent's permissions. The section says so plainly: "Command servers run a local program on this Mac with the agent's permissions, so only add tools you trust." Only add servers from a source you trust. ## Steps 1. Click **Add MCP server**. If you want a head start, click a **Quick add** button instead (for example **Chrome bridge** or **Playwright**) to open the form already filled in. 2. Type a **Name**. Use letters, numbers, `-`, or `_` only. The name **codus** is reserved, and each server needs a different name. 3. Pick a **Type**: - **Command** runs a local program on your Mac. Fill in **Command** (for example `mcp-chrome-bridge`), optional **Arguments** (space-separated, for example `-y @playwright/mcp@latest`), and optional **Environment** values (one `KEY=VALUE` per line). - **HTTP URL** connects to a server already running at a web address. Fill in **Server URL** (for example `https://example.com/mcp`) and, if the server needs one, an **Auth token**. 4. Under **Which agents get this server?**, choose **All surfaces** to make it available across codus, or tap specific quadrants (**Q1**, **Q2**, and so on) to limit it to only those. You must pick **All surfaces** or at least one quadrant before you can save. 5. Click **Save**. ### About the auth token The **Auth token** box is only for **HTTP URL** servers, and only when the server requires one. The form explains where it goes: "Sent as an Authorization: Bearer header in the server's config. Stored encrypted on this device; never shown to agents." Leave it blank if the server needs no token. If you saved one before, leave it blank to keep it, or use **Clear saved token** to remove it. ## How do I know it worked? Back on the list, your server appears as its own row showing its **Name**, a badge that reads **Command** or **HTTP**, and its scope (**All quadrants**, or a list like **Q1, Q2**). Below that, a live status line tells you what actually happened: - **Working:** "connected", the tool count, and "live in all agents", for example "connected, 5 tools, live in all agents". - **Still trying:** "connecting". - **Failed:** "not connected", followed by a short reason. The status line is the real proof. A saved row with "not connected" means your agents did not get the tools yet. ## Turning a server on or off, editing, or removing it Each of your server rows has three controls on the right: - The **On** / **Off** toggle enables or disables it, and hovering it tells you whether a click will enable or disable the server. - **Edit** reopens the form to change any field. - **Remove** deletes it. codus asks you to confirm with "Remove this MCP server? Its tools disappear from all agents immediately." ## Common problems - **The row says "No quadrants".** Its scope is empty, so no agent gets it. Click **Edit**, then set the scope to **All surfaces** or pick at least one quadrant. - **The row says "not connected".** codus reached out to the server and could not connect. Check the address or command is right and that the server is actually running, then click **Edit** and **Save** again to retry. For a **Command** server, make sure the program is installed on this Mac. - **The Save button is greyed out.** Something is missing or invalid. A **Name** is required and cannot be **codus** or a duplicate, a **Command** or **Server URL** is required for its type, and you must choose **All surfaces** or at least one quadrant. - **I added the server in a terminal, and my agent still cannot see it.** codus only loads servers from this section. Adding one another way has no effect. See [Why doesn't editing mcp.json or "claude mcp add" work in codus?](codus-manages-your-mcp-config.md).