# Connect Hermes and Other Clients

Interactive clients such as claude.ai and ChatGPT sign in through a
browser. Headless clients — command-line agents, servers, scheduled
jobs — cannot open a browser, so they authenticate with a static API
token instead.

Any MCP client that supports the streamable HTTP transport and an
`Authorization` header can connect this way.

## 1. Generate an API token

1. Sign in and open [API tokens](https://kafkai.com/en/accounts/api-tokens/) (also
   linked from the dashboard).
2. Name the token after the client that will use it, for example
   `Hermes` — the name makes it easy to revoke the right token later.
3. Choose **Generate Token**.
4. Copy the token immediately. It is shown only once; Kafkai stores
   only a hash of it.

## 2. Connect Hermes

Hermes reads its MCP servers from `~/.hermes/config.yaml`. Keep the
token out of that file. Put it in `~/.hermes/.env`, which Hermes loads
into the environment:

```
KAFKAI_API_TOKEN=YOUR_API_TOKEN
```

Then add the server under `mcp_servers` in `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  kafkai:
    url: "https://kafkai.com/mcp"
    headers:
      Authorization: "Bearer ${KAFKAI_API_TOKEN}"
```

Run `/reload-mcp` in a running Hermes session, or start a new one.
Hermes prefixes tool names with the server name, so the Kafkai tools
appear as `mcp_kafkai_list_projects` and so on.

## 2b. Connect any other client

Point the client at the endpoint and send the token as a Bearer
header:

- Endpoint: `https://kafkai.com/mcp`
- Header: `Authorization: Bearer YOUR_API_TOKEN`

For clients configured with JSON, the shape is usually:

```json
{
  "mcpServers": {
    "kafkai": {
      "url": "https://kafkai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

## 3. Verify

Ask the agent to list your Kafkai projects. A successful call to
`kafkai_list_projects` means the token works. From there, the prompts
on the [Example Prompts](https://kafkai.com/en/prompts/) page apply as-is.

## Managing tokens

The [API tokens page](https://kafkai.com/en/accounts/api-tokens/) lists your active
tokens with their creation and last-used dates. Revoke a token there
and it stops working immediately.

Treat API tokens like passwords:

- one token per client, so revoking one does not break the others,
- never commit a token to a repository or paste it into shared chats,
- revoke tokens you no longer use.

A token gives its holder access to your Kafkai data and spends your
credits. If a token may have leaked, revoke it first and ask questions
after.
