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

# MCP servers

> Connect remote Model Context Protocol servers and control their tools.

Attach remote MCP servers to an agent with `mcpServers`, then enable and set
permissions for their tools with an `mcp_toolset` entry in `tools`.

## Configure a server

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": [
    {
      "type": "url",
      "name": "support",
      "url": "https://mcp.example.com/support"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcpServerName": "support",
      "defaultConfig": {
        "permissionPolicy": { "type": "always_ask" }
      },
      "configs": [
        {
          "name": "lookup_customer",
          "permissionPolicy": { "type": "always_allow" }
        }
      ]
    }
  ]
}
```

Server names must be unique within an agent version. `mcpServerName` must match
an entry in `mcpServers`. See [Tools](/api-reference/tools#mcp-toolset-config)
for enablement, resources, prompts, and permission policies.

## Authentication

Do not place raw credentials in the server URL or agent configuration. Store
them in a [vault](/api-reference/vaults), attach that vault to the agent, and
install the connection through:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/agents/{agentId}/mcp/installations
```

The installation body includes `expectedAgentVersion`, an `idempotencyKey`, a
catalog or custom `connector`, and `authentication`. Use
`authentication.type: "existing_vault"` with `vaultId` to reuse an attached
vault, `static_bearer` to store a new token, or `none` for a public server.

When an MCP server is configured directly on an agent version, Herm resolves a
matching credential from attached vaults by normalized server URL.

Herm resolves credentials when the MCP request runs; secret values are not
written into the agent's sandbox configuration.

## Updates

Use `PATCH /v1/agents/{agentId}` to upsert one MCP server by `name` while
preserving omitted servers. Use the full-replacement
`POST /v1/agents/{agentId}` when removing a server from the version.

MCP tool calls appear as `agent.mcp_tool_use` and `agent.mcp_tool_result` on the
[session event stream](/api-reference/events-reference).