# Add an MCP server

> Add a remote MCP server in Plugins so every Zuse agent can use its tools through the Zuse gateway.

Canonical URL: https://docs.zuse.sh/how-to/local-configure-mcp



## Goal [#goal]

Make an MCP server's tools available to Zuse agents, then verify them in a fresh session.

## How agents get MCP tools [#how-agents-get-mcp-tools]

Agents launched by Zuse receive MCP tools **only** through Zuse's own session gateway. The gateway serves the plugins connected to your workspace, so the same tools work with every supported provider.

Zuse does not read or pass through MCP servers configured in a provider's own files, such as `~/.claude.json`, `.mcp.json`, or `[mcp_servers]` in `~/.codex/config.toml`. Where a provider CLI offers a switch for it, Zuse also stops the CLI from loading those servers itself. Servers you configured there keep working when you use that CLI outside Zuse.

## Prerequisites [#prerequisites]

* Sign in to Zuse. Plugins belong to your account or organization.
* Have the server's remote HTTPS URL. Local `stdio` commands and private-network servers cannot be added.
* Know how the server authenticates: OAuth, no authentication, or an API key sent in a request header.
* Read the server's tool list and trust boundary before connecting it.

## 1. Add the server [#1-add-the-server]

1. Open **Plugins** and choose **Add MCP server**.
2. Enter a name and the server's HTTPS URL.
3. Choose its authentication:
   * **OAuth** or **no authentication**: Zuse detects which one the server uses when you connect.
   * **API key**: enter the header name and key. Zuse checks the key once before saving it.
4. Choose where it belongs:
   * **Personal workspace**: only you can use it.
   * **Organization workspace**: organization admins add and remove it; every member can use it.
5. Connect the server. If the first connection fails, the server is not kept, so you can fix the URL or key and try again.

Popular services may already be in the plugin catalog. Prefer the catalog entry when one exists.

## Verify the server [#verify-the-server]

1. Start a new chat. A provider process that was already running may still have its old tool set.
2. Ask the agent to list available plugins, then to use one known, harmless read-only tool from the server.
3. Approve the call if the active permission mode requires it, and confirm that the result came from the intended server.

## Troubleshooting [#troubleshooting]

* **The URL is rejected:** the server must be reachable at a public HTTPS address.
* **The key is rejected:** check the header name and key with the server's documentation, then add the server again.
* **The agent cannot see the tools:** confirm that the server is connected in **Plugins**, then start a new chat.
* **A server you configured in a provider CLI is missing:** that is expected. Add it in **Plugins** instead.
* **A tool request is denied:** plugin availability does not bypass [runtime modes and permissions](/composer/modes-permissions.md).

If status and provider behavior disagree, inspect **Settings → Diagnostics**.