> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Add MCP servers to agents

> How to add MCP servers to your Murmur agents.

This guide shows you how to add MCP servers to your agents. To control Murmur from your own MCP client, see [MCP integration](https://docs.murmur.dev/integrations/mcp.md).

## Before you start

* Agents get MCP servers from a plugin: a git repository whose `.mcp.json` declares the server. The dashboard has no field for an MCP server URL. [Plugin marketplaces](https://docs.murmur.dev/guides/plugin-marketplace.md) describes the repository layout.
* Agents authenticate to an MCP server with a token stored as a Murmur secret. Agents can't complete an OAuth sign-in, so for an MCP server that offers both OAuth and API keys, use an API key.
* Every agent in the workspace receives the same token, unless the agent's owner has mounted a personal secret with the same name, which takes precedence. Use a team or service-account token, not a personal one.

The examples use the workspace `backend`, the plugin repository `https://github.com/acme/example-tools`, and the token variable `EXAMPLE_API_TOKEN`.

## Declare the MCP server

In the plugin's `.mcp.json`, reference the token by its variable name. Never commit the token itself.

```json .mcp.json theme={null}
{
  "mcpServers": {
    "example": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "bearer_token_env_var": "EXAMPLE_API_TOKEN",
      "headers": {
        "Authorization": "Bearer ${EXAMPLE_API_TOKEN}"
      }
    }
  }
}
```

Keep both token fields: Claude Code and OpenCode read `headers`, and Codex reads `bearer_token_env_var`.

## Add it to your workspace

### From the dashboard

1. Push the plugin to a repository your agents can clone.
2. In **Settings → Agent configuration → Secrets**, click **Add secret**. Enter the name `EXAMPLE_API_TOKEN`, set **Management scope** to your workspace, paste the **Value**, and leave **Mount automatically** checked.
3. In **Settings → Workspaces**, open the workspace. Under **Plugins**, click **Add plugin**, and enter the **Name** `example-tools` and the **Clone URL**. Optionally, set **Ref** to a tag or commit to pin the version. Click **Save changes**.

Plugins install when an agent starts. Spawn a new agent to pick up the MCP server.

### From the CLI

Store the token, then add the secret mount and the plugin to the workspace. `--if-generation` rejects the write if the workspace changed after you read it.

```bash theme={null}
printf '%s' "$EXAMPLE_API_TOKEN" | murmur secret set --workspace backend EXAMPLE_API_TOKEN

murmur get workspace backend > backend.yaml
yq '.runtimeSecretMounts += [{"name": "backend/EXAMPLE_API_TOKEN", "mountType": "MOUNT_TYPE_ENV"}]
  | .plugins += [{"name": "example-tools", "cloneUrl": "https://github.com/acme/example-tools"}]' backend.yaml \
  | murmur set workspace backend --if-generation "$(yq '.generation' backend.yaml)"
```

The dashboard and CLI require a workspace collaborator or administrator.

### From an agent

An agent can write the plugin and propose the secret and the workspace change for your approval. The agent never sees the token.

1. Spawn an agent with access to the plugin repository:

   ```bash theme={null}
   murmur spawn --workspace backend --repo https://github.com/acme/example-tools=main add-example-mcp \
     "Add a plugin for the MCP server at https://mcp.example.com/mcp, authenticated with the EXAMPLE_API_TOKEN environment variable, and open a pull request. Then propose the secret backend/EXAMPLE_API_TOKEN and the backend workspace with that secret mounted and the plugin added."
   ```

2. Review and merge the plugin pull request.

3. In the dashboard, open **Change requests**, select the request, enter the token under **Secret value for backend/EXAMPLE\_API\_TOKEN**, and click **Accept changes**.

Anyone who can spawn agents in the workspace can request the proposal. Approving it requires a workspace collaborator or administrator.

## Verify

Spawn a new agent and ask it to use the MCP server:

```bash theme={null}
murmur spawn --workspace backend check-example-mcp "List the tools the example MCP server provides and call one read-only tool."
```

If the agent lists the tools and the call succeeds, the MCP server is connected.

## Troubleshooting

### The agent doesn't have the MCP server's tools

| Symptom | Fix |
| - | - |
| The agent was spawned before you changed the workspace. | Spawn a new agent. |
| The **Clone URL** is wrong, or your agents can't read the repository. | Correct the URL, or grant your agents read access to the repository. |
| `.claude-plugin/plugin.json` or `.mcp.json` is missing or in the wrong place. | Follow the layout in [Plugin marketplaces](https://docs.murmur.dev/guides/plugin-marketplace.md#repo-structure). |

### The MCP server rejects the token (401 or 403)

| Symptom | Fix |
| - | - |
| The workspace doesn't mount the secret. | In **Settings → Workspaces**, open the workspace, add the secret under **Runtime secret mounts** with type `ENV`, and spawn a new agent. |
| `.mcp.json` references a different variable name than the secret delivers. | Change the variable in `.mcp.json`, or store the secret under that name, so the names are identical. A secret stored as `backend/EXAMPLE_API_TOKEN` is delivered as `EXAMPLE_API_TOKEN`. |
| The agent's owner has a personal secret mounted under the same name, which takes precedence. | Remove it with `murmur secret unmount EXAMPLE_API_TOKEN`, and spawn a new agent. |
| The token is invalid, expired, or missing scopes. | Update the secret's value in **Settings → Agent configuration → Secrets**, and spawn a new agent. |

To verify which environment variables an agent received, run `murmur credentials --workspace backend check-example-mcp`. See [`murmur credentials`](https://docs.murmur.dev/cli/credentials).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.