Add MCP servers to agents

This guide shows you how to add MCP servers to your agents. To control Murmur from your own MCP client, see MCP integration.

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

.mcp.json

{
  "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

Push the plugin to a repository your agents can clone.
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.
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.

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.

Spawn an agent with access to the plugin repository:

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

Review and merge the plugin pull request.
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:

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.

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.

Getting started

Core concepts

Integrations

Guides

Add MCP servers to agents

Before you start

Declare the MCP server

Add it to your workspace

From the dashboard

From the CLI

From an agent

Verify

Troubleshooting

The agent doesn’t have the MCP server’s tools

The MCP server rejects the token (401 or 403)

​Before you start

​Declare the MCP server

​Add it to your workspace

​From the dashboard

​From the CLI

​From an agent

​Verify

​Troubleshooting

​The agent doesn’t have the MCP server’s tools

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

Before you start

Declare the MCP server

Add it to your workspace

From the dashboard

From the CLI

From an agent

Verify

Troubleshooting

The agent doesn’t have the MCP server’s tools

The MCP server rejects the token (401 or 403)