Integration Guide

Hermes Agent + Composio: Hundreds of Apps Behind One MCP Endpoint

Q: Can Hermes Agent use Composio?

Yes. Composio exposes toolkits as an MCP server and Hermes connects to it as a remote HTTP MCP server under mcp_servers in config.yaml.

Q: Why can I not pass the API key with a --header flag?

Because hermes mcp add has no --header flag. Its options are --url, --command, --args, --auth, --preset, --connect-timeout and --env. Set headers in config.yaml under the server headers mapping.

Q: What is the Composio MCP URL?

Use https://backend.composio.dev/v3/mcp/{SERVER_ID}?user_id={USER_ID} for your own server, or https://connect.composio.dev/mcp for Composio Connect. The older mcp.composio.dev host no longer serves MCP.

Q: Do I still need per-app API keys?

Generally no. With Composio-managed auth the agent connects accounts at runtime through the session, so per-toolkit auth configs are not pre-created. The trade-off is that Composio holds those connections.

Q: Which header do I send, and is it always required?

It depends on the endpoint: x-consumer-api-key with a ck_ key for Composio Connect, or x-api-key with an ak_ key for a Platform MCP server. Assume a key is required; require_mcp_api_key is on by default for new organisations.

Composio handles tool discovery, authentication and toolkit versioning so your agent does not have to. For Hermes Agent it arrives as an ordinary remote MCP server — which makes the setup short, and makes the two things that go wrong worth writing down.

What Composio is doing for you

Composio is a tools-and-auth layer for agents. Rather than writing an integration per SaaS product and storing a key for each, you connect once and Composio manages tool discovery, the OAuth dance, and toolkit versioning behind a single MCP endpoint.

The part worth understanding before you wire it in is the auth model. With Composio-managed auth, the agent connects accounts at runtime through the session, so you do not pre-create connected accounts for managed toolkits. That removes a lot of setup and it also means Composio is holding those app connections on your behalf. That is a reasonable trade for many teams and a disqualifying one for others; decide it deliberately rather than discovering it later.

Get your endpoint

There are two live shapes, and each takes a different header with a different key format. They are not interchangeable, and mixing them is the most common cause of a 401 on an otherwise correct setup:

Form	URL	Header
Platform MCP	`https://backend.composio.dev/v3/mcp/{SERVER_ID}?user_id={USER_ID}`	`x-api-key: ak_...`
Composio Connect	`https://connect.composio.dev/mcp`	`x-consumer-api-key: ck_...`

Do not use mcp.composio.dev. A large number of still-circulating tutorials show a https://mcp.composio.dev/composio/server/{ID} URL. That host no longer serves MCP — it redirects to a marketing page — so an agent pointed at it fails in a way that reads like an authentication problem rather than a dead endpoint.

Copy the exact URL from your Composio dashboard. Server IDs are opaque, and a hand-assembled URL fails as an authentication error rather than as a not-found, which sends people looking at their key.

Add it to Hermes

The CLI registers the server, which keeps validation on your side:

hermes mcp add composio \
  --url https://connect.composio.dev/mcp \
  --connect-timeout 60

Now the part that catches people. hermes mcp add takes --url, --command, --args, --auth, --preset, --connect-timeout and --env. There is no --header flag, so the Composio API key cannot be supplied on the command line. It goes into ~/.hermes/config.yaml:

mcp_servers:
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "ck_YOUR_CONSUMER_KEY"
    connect_timeout: 60
    timeout: 180

# Your own Platform MCP server uses a different host, header and key prefix:
#   url: "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?user_id=YOUR_USER_ID"
#   headers:
#     x-api-key: "ak_YOUR_COMPOSIO_API_KEY"

Composio Connect is the route Composio's own Hermes integration page documents, which is why it leads here. Note that it sets both timeouts — connect_timeout: 60 for the handshake and timeout: 180 for tool calls, which can legitimately take minutes when a tool is doing real work at the far end.

Restart Hermes after editing the file. The remote-server schema also supports auth for OAuth 2.1, client_cert for mTLS, identity_header for per-user identity, and timeout alongside connect_timeout.

Why the timeout is not optional: Composio's server advertises a large toolkit, and initial tool discovery is the slow part of the handshake. A default timeout can expire during discovery and present as “server not reachable” when the endpoint is perfectly healthy.

Keys, and where they must not go

Whichever header your endpoint takes, a key is effectively always required — on the Platform side require_mcp_api_key is on by default for new organisations. Store it in the config of your own instance. Never bake a Composio key into a shared image or a template that other people deploy from — an MCP key is a key to every app connected behind it, which is a much broader blast radius than a single provider token.

Confirm it before asking the agent to use it

List the registered servers and check the connection actually completed, rather than inferring it from a chat reply. An agent that cannot see a tool will usually answer without it instead of reporting the failure, so a plausible answer is not evidence the integration works. Ask for something only Composio could do — a specific action in a connected app — and confirm the side effect at the far end.

If you would rather not run the Hermes side yourself, OpenClaw Launch deploys a managed Hermes Agent in about thirty seconds and you attach your own Composio server to it.

Hermes Agent and Composio FAQ

Can Hermes Agent use Composio?

Yes. Composio exposes its toolkits as an MCP server, and Hermes speaks MCP, so it connects as a remote HTTP server under mcp_servers in config.yaml. No Composio SDK is involved on the Hermes side.

Why can I not pass the API key with a --header flag?

Because hermes mcp add does not have one. Its options are --url, --command, --args, --auth, --preset, --connect-timeout and --env. Arbitrary headers are set in config.yaml under the server's headers mapping.

What is the Composio MCP URL?

There are two, depending on which product you are on. Your own generated server is https://backend.composio.dev/v3/mcp/{SERVER_ID}?user_id={USER_ID}, and the shared Composio Connect endpoint is https://connect.composio.dev/mcp. The older mcp.composio.dev host no longer serves MCP, so ignore tutorials that still show it. Copy the URL your dashboard gives you rather than assembling one by hand.

Do I still need per-app API keys?

Generally no — that is the point of Composio-managed auth. The agent connects accounts at runtime through the session, so you are not pre-creating auth configs for every managed toolkit. The trade is that Composio then holds those connections.

Which header do I send, and is it always required?

It depends on the endpoint: x-consumer-api-key with a ck_ key for Composio Connect, x-api-key with an ak_ key for your own Platform MCP server. Assume a key is required either way — on the Platform side require_mcp_api_key is enabled by default for newly created organisations.