# Настройка MCP

Brain отдаёт Streamable HTTP MCP-эндпоинт на `/mcp/:companyId`. У каждого тенанта свой URL, ограниченный API-ключом.

## Что нужно

1. **API-ключ** brain (формат `brain_<base64>`). Сгенерируй на `https://brain.inite.ai/admin/keys`.
2. **companyId**, на который выдан ключ (виден на том же экране).
3. **MCP-URL**: `https://brain.inite.ai/mcp/<companyId>`.

Brain не принимает анонимный MCP-трафик. Режима общего секрета нет.

## Claude Desktop

Правь `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) или `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

Полностью выйди из Claude Desktop (не просто закрой окно) и открой заново. Сервер brain появится в панели MCP с шестью инструментами (или четырьмя, если у ключа только `brain:read`).

## Cursor

`.cursor/mcp.json` в воркспейсе (или `~/.cursor/mcp.json` глобально):

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

Перезагрузи воркспейс. Инструменты brain станут доступны как `@brain.<tool>` в панели чата.

## 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` подгрузит инструменты brain.

## n8n

В ноде **MCP Client**:

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

Закрепи credential, чтобы переиспользовать между воркфлоу.

## Hermes (Nous Research)

[Hermes Agent](https://hermes-agent.nousresearch.com) поддерживает remote MCP нативно. Добавь brain в `mcp_servers` файла `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  brain:
    url: "https://brain.inite.ai/mcp/<companyId>"
    headers:
      Authorization: "Bearer <api-key>"
    tools:
      exclude: [forget_entity]   # опционально — спрятать деструктивный admin-инструмент
```

Hermes на старте обнаружит инструменты brain и зарегистрирует их в своём общем реестре. Фильтры `tools.include` / `tools.exclude` позволяют отдать агенту только нужную поверхность.

## Харнесы только с stdio — коннектор `@inite/brain-mcp`

Некоторые харнесы умеют запускать MCP-серверы только как **stdio**-подпроцессы и не могут прикрепить заголовок `Authorization` — MCP-клиент [openclaw](https://github.com/openclaw/openclaw) только stdio, как и Goose 1.x. Для них есть first-party коннектор stdio↔HTTP [`@inite/brain-mcp`](https://www.npmjs.com/package/@inite/brain-mcp). Харнес спавнит его по stdio, а он прозрачно проксирует каждый доступный по scope инструмент на удалённый эндпоинт, пробрасывая Bearer-ключ из `env`:

```
харнес ──stdio──▶ @inite/brain-mcp ──HTTP + Bearer──▶ /mcp/<companyId>
```

Это чистый проксипасс — `tools/list` и `tools/call` форвардятся вербатим, так что агент видит ровно ту поверхность, что открывает ключ. Пропиши его в MCP-конфиг харнеса (пример для `mcp.servers` у openclaw):

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

| Переменная | Обязательна | По умолчанию | Примечание |
| --- | --- | --- | --- |
| `BRAIN_API_KEY` | да | — | твой ключ `brain_…` |
| `BRAIN_COMPANY_ID` | да\* | — | \*не нужна, если задан `BRAIN_MCP_URL` |
| `BRAIN_BASE_URL` | нет | `https://brain.inite.ai` | для self-hosted brain |
| `BRAIN_MCP_URL` | нет | — | полный override эндпоинта; важнее base + company |

Аутентификация, изоляция тенантов, scopes и PII-фенс по-прежнему энфорсятся на стороне brain из ключа — коннектор лишь несёт токен. Харнесам, которые уже умеют remote MCP (Hermes, Claude Desktop, Cursor, Goose v2), коннектор не нужен — им прямой URL-конфиг выше; коннектор только для случая stdio-only.

## Smoke-тест

Когда подключился, попроси ассистента:

> Покажи доступные инструменты brain и вызови `search_knowledge` с query `"hello"` limit 1.

Ты увидишь либо четыре, либо шесть инструментов (в зависимости от scope) и результат `search_knowledge` — либо пустой (свежий тенант), либо одно попадание (seed-данные).

Получил 401 — bearer-токен битый или ключ невалиден. Получил `400: MCP path companyId (...) does not match ApiKey companyId` — вставил не тот companyId для этого ключа.

## Матрица scope

| Scope | Видимые инструменты |
| --- | --- |
| `brain:read` (всегда) | `search_knowledge`, `get_entity_profile`, `get_entity_timeline`, `find_related_entities` |
| `brain:write` (дополнительно) | плюс `record_fact`, `retract_fact` |
| `brain:read_pii` (дополнительно) | открывает значения `email` / `phone` / `dob` / `address` в результатах |

Ключ только с `brain:read` видит четыре инструмента, а не шесть. Это инвариант безопасности, а не баг.

## Stateless-режим

Brain держит MCP без состояния: один McpServer на запрос, без session id. MCP-клиентам, которым нужны долгие сессии, стоит звать по разу на использование инструмента — на стороне brain нет стоимости установки. Сессии с состоянием можно добавить через `sessionIdGenerator`, если появится кейс.

## Связанное

- [Справочник MCP-инструментов](/ru/docs/mcp/tools) — полные схемы инструментов brain
- [Набор скиллов](/ru/docs/skills) — инструкции для агента (формат Anthropic Skills)
- [`@inite/brain-mcp`](https://www.npmjs.com/package/@inite/brain-mcp) — коннектор stdio↔HTTP для харнесов только с stdio (исходники в [`clients/brain-mcp`](https://github.com/inite-ai/inite-brain-service/tree/main/clients/brain-mcp))
