> ## 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`, `authentication`, and an optional
`defaultPermission` of `always_ask`, `always_allow`, or `always_deny`. It
defaults to `always_ask`. 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.

Direct MCP connectors, including GitHub, Linear, Notion, and Slack, authenticate
against their provider endpoint with the vault-backed bearer or OAuth token.
Composio-managed connectors use their generated Composio MCP endpoint and are
authenticated by Herm's control-plane Composio credential. These paths are
separate; direct connector credentials are not routed through Composio.

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