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

{
  "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 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, attach that vault to the agent, and install the connection through:

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.