# MCP setup

Brain ships a Streamable HTTP MCP endpoint at `/mcp/:companyId`. Each tenant has its own URL, scoped by API key.

## What you need

1. A brain **API key** (format `brain_<base64>`). Generate at `https://brain.inite.ai/admin/keys`.
2. The **companyId** the key was issued for (visible in the same screen).
3. The **MCP URL**: `https://brain.inite.ai/mcp/<companyId>`.

Brain refuses anonymous MCP traffic. There is no shared-secret mode.

## Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "brain": {
      "url": "https://brain.inite.ai/mcp/<companyId>",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}
```

Quit Claude Desktop fully (not just close the window) and reopen. The brain server appears in the MCP panel with six tools (or four if the key only has `brain:read`).

## Cursor

`.cursor/mcp.json` in the workspace (or `~/.cursor/mcp.json` for global):

```json
{
  "mcpServers": {
    "brain": {
      "url": "https://brain.inite.ai/mcp/<companyId>",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}
```

Reload the workspace. Brain tools become available as `@brain.<tool>` in the chat panel.

## Goose

`~/.config/goose/config.yaml`:

```yaml
extensions:
  brain:
    type: streamable_http
    uri: https://brain.inite.ai/mcp/<companyId>
    headers:
      Authorization: Bearer <api-key>
    enabled: true
```

`goose session start` loads brain tools.

## n8n

In the **MCP Client** node:

- URL: `https://brain.inite.ai/mcp/<companyId>`
- Transport: HTTP (Streamable)
- Header: `Authorization: Bearer <api-key>`

Pin a credential so it's reusable across workflows.

## Hermes (Nous Research)

The [Hermes Agent](https://hermes-agent.nousresearch.com) supports remote MCP natively. Add brain under `mcp_servers` in `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  brain:
    url: "https://brain.inite.ai/mcp/<companyId>"
    headers:
      Authorization: "Bearer <api-key>"
    tools:
      exclude: [forget_entity]   # optional — hide the destructive admin tool
```

Hermes discovers brain's tools at startup and registers them into its normal tool registry. The `tools.include` / `tools.exclude` filters let you expose only the surface you want the agent to see.

## stdio-only harnesses — the `@inite/brain-mcp` connector

Some harnesses can only launch **stdio** MCP servers as subprocesses and have no way to attach an `Authorization` header — [openclaw](https://github.com/openclaw/openclaw)'s MCP client is stdio-only, and so is Goose 1.x. For these, use the first-party stdio↔HTTP connector [`@inite/brain-mcp`](https://www.npmjs.com/package/@inite/brain-mcp). The harness spawns it over stdio; it transparently proxies every scoped tool to the remote endpoint, carrying the Bearer key from `env`:

```
harness ──stdio──▶ @inite/brain-mcp ──HTTP + Bearer──▶ /mcp/<companyId>
```

It is a pure passthrough — `tools/list` and `tools/call` are forwarded verbatim, so the agent sees exactly the surface the key unlocks. Wire it into the harness's MCP config (shown here for openclaw's `mcp.servers`):

```json
{
  "mcp": {
    "servers": {
      "brain": {
        "command": "npx",
        "args": ["-y", "@inite/brain-mcp"],
        "env": {
          "BRAIN_API_KEY": "brain_xxxxxxxx",
          "BRAIN_COMPANY_ID": "<companyId>"
        }
      }
    }
  }
}
```

| Env var | Required | Default | Notes |
| --- | --- | --- | --- |
| `BRAIN_API_KEY` | yes | — | your `brain_…` key |
| `BRAIN_COMPANY_ID` | yes\* | — | \*not needed if `BRAIN_MCP_URL` is set |
| `BRAIN_BASE_URL` | no | `https://brain.inite.ai` | point at a self-hosted brain |
| `BRAIN_MCP_URL` | no | — | full endpoint override; wins over base + company |

Auth, tenancy isolation, scopes and PII fencing stay enforced server-side from the key — the connector only carries the token. Harnesses that already speak remote MCP (Hermes, Claude Desktop, Cursor, Goose v2) should use the direct URL config above instead; the connector is only for the stdio-only case.

## Smoke test

Once connected, ask the assistant:

> List available brain tools and call `search_knowledge` with query `"hello"` limit 1.

You should see either four or six tools (depending on scope) and a `search_knowledge` result that is either empty (fresh tenant) or one hit (seed data).

If you get a 401, the bearer token is malformed or the key is invalid. If you get `400: MCP path companyId (...) does not match ApiKey companyId`, you've pasted the wrong companyId for this key.

## Scope matrix

| Scope | Tools visible |
| --- | --- |
| `brain:read` (always) | `search_knowledge`, `get_entity_profile`, `get_entity_timeline`, `find_related_entities` |
| `brain:write` (extra) | also `record_fact`, `retract_fact` |
| `brain:read_pii` (extra) | unlocks `email` / `phone` / `dob` / `address` object values in results |

A key with only `brain:read` sees four tools, not six. That's the security invariant, not a bug.

## Stateless mode

Brain runs MCP stateless: one McpServer per request, no session id. MCP clients that need long-running sessions should call once per tool use — there's no setup cost on brain's side. Stateful sessions can be added via `sessionIdGenerator` if a use case appears.

## Related

- [MCP tools reference](/en/docs/mcp/tools) — full schemas for the brain tools
- [Skills bundle](/en/docs/skills) — agent how-to-use briefs (Anthropic Skills format)
- [`@inite/brain-mcp`](https://www.npmjs.com/package/@inite/brain-mcp) — stdio↔HTTP connector for stdio-only harnesses (source in [`clients/brain-mcp`](https://github.com/inite-ai/inite-brain-service/tree/main/clients/brain-mcp))
