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?.