> ## Documentation Index > Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP & OAuth > Connect ChatGPT, Claude, and other AI clients to your Brein workspace via the Model Context Protocol. Brein ships an MCP (Model Context Protocol) server that exposes your workspace context to AI clients. ChatGPT, Claude, Copilot, and any MCP-compatible client can read and write topics through it. The `driftless_*` tool names remain stable compatibility contracts. ## How it works The MCP adapter runs at `apps/mcp` and translates MCP tool calls to the existing Driftless REST API. It is a **protocol adapter only**: it never accesses Postgres, internal libraries, or workspace admin operations directly. ## Start here: retrieve When you have a **task** but no topic slug yet, the first call is `driftless_context_retrieve`: it returns the team's most relevant recorded context for a task description, a set of files, or both, ranked drifted-first and bounded. It composes search + match-files + list filters so you don't hand-chain them. Bodies come back **brief** by default (the durable *why*, not the full `content`); call `driftless_context_get` for the one topic whose full body you need, or pass `view: "full"`. The same **active-only, bounded, brief-by-default** contract applies to the operational surface: `driftless_collection` `list` is active-only (opt into archived with `include_archived:true`), and `get` is brief unless you pass `view:'full'`. See [Payload views](#payload-views-keep-reads-fast) below. ## Tool families The MCP surface is documented by family in the **MCP reference**. Use this page for setup and auth; open a family page for tool names, actions, parameters, permissions, and examples. | Family | What it covers | Reference | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Knowledge and governance | Retrieve, read, write, graph, health, tags, areas, and the Note to Knowledge lifecycle | [MCP: Knowledge and governance](/mcp/knowledge) | | Collections and operations | Collections, records, and entities | [MCP: Collections and operations](/mcp/work) | | Integrations and Broker | Operating a connected provider (gated) | [MCP: Integrations and Broker](/mcp/integrations) | | Workspace and collaboration | Comments, members, workspaces, and proposal stats | [MCP: Workspace and collaboration](/mcp/collaboration) | | Commercial usage | `driftless_usage` reads the plan, monthly requests and credits, renewal date, promotional research availability, and contact-sales action. The read itself is free. | [API overview](/api/overview#commercial-usage) | | Commercial intelligence | Thirteen typed analysis tools for suppliers, segment comparisons, opportunities, awards, risk marks, and permits. Analysis never returns contact coordinates. `driftless_contact_quote` prices selected CRM accounts for free; `driftless_contact_unlock` runs only after explicit confirmation with a credit cap. There is no generic action router or bulk supplier-detail tool. Reconnect after schema changes because clients may cache tool definitions. | [Market Data](/api/market-data) | The surface covers **context** (topics, governance, the graph), **workspace organization** (tags and areas), the **operational substrate** (collections, records, entities), and **broker execution** (operating connected providers). It never covers workspace admin, repo registration, key management, **integration setup** (connecting a provider), authoring/deploying integration scripts, or manual agent-run triggering. Topics live in the workspace and are visible to its members; another's private drafts stay hidden. Operational writes require the `work:write` scope; merging into Knowledge needs owner/admin authority, and the MCP client runs it only when the authorizing owner/admin explicitly asks. Every result (search, list, get) carries a flat **`trust`** field (`reviewed` | `proposed` | `draft`), so an agent can key on `trust === "reviewed"` directly instead of inferring it from `classification.status` + `governance.authoritative`. `reviewed` is Knowledge, the team's source of truth; `proposed`/`draft` are Notes (hints). ### Payload views keep reads fast Reads default to a **light payload** so a result never floods your context. The vocabulary is the same everywhere (`summary` / `brief` / `full`): * **`summary`**: an index row (id/slug, title, trust, badges, anchors). Lists and search return this, bounded (top 5 search, top 40 list). * **`brief`** (the default for `driftless_context_retrieve` and `driftless_context_get_for_files`) is the durable **why**: what / decisions / gotchas / invariants, **without** the full `content`. Roughly 76% lighter than a full body. * **`full`**: everything, including the heavy `content` body. **Never a default elsewhere**; you opt in with `view: "full"`. `driftless_context_get` is the exception: it defaults to `full` because you named the one topic you want. The same `view: "full"` opt-in applies to `driftless_collection` `action:'get'` (brief by default, full on request). The pattern: `retrieve` / `get_for_files` in `brief` to see *which* topic governs the work, then `driftless_context_get` (full) for the single body you actually need, instead of pulling every full body up front. Collections mirror this: `driftless_collection action:'get'` is brief, with `view:'full'` for the one Collection whose full config you need. ### Broker (execution) vs integration setup `driftless_broker` only **operates** a connection that already exists (`operations` / `invoke` / `records` / `events` / `criterion`). **Connecting** a provider is integration *setup*: a privileged human-led flow done in the dashboard (Settings → Connections) or via the CLI `integration connect/confirm` commands; it is not on the MCP surface. Authoring or deploying a Nango action is a third, human-only lane. If an agent needs a broker operation that `operations` does **not** list, it must **report the missing capability**. Never write or deploy a script to fill the gap. ### Connector tools are synthesized per workspace Beyond the static tools above, the MCP server can **synthesize** extra read-only tools per workspace from a provider's ready capabilities: `driftless__records` and `driftless__document_content` (for example, `driftless_notion_document_content`). They appear only when broker tool synthesis is enabled and the provider exposes a `ready`, read-effect capability of a synthesizable kind, capped per workspace. Two rules follow: **a listed tool is not a usable one** (a synthesized or static broker tool still resolves through the broker API, where an external caller is gated by rollout and grants), and **write capabilities are never synthesized**. See [Broker](/integrations/broker). ### Typed relations from the MCP `create` and `update` accept `rels`, typed graph edges, the same seven types as the CLI's `--rel`: ```json theme={"theme":"github-light"} { "topic": "refund-flow", "rels": [ { "to": "billing-flow", "type": "depends_on" }, { "to": "stripe-webhook-ingest", "type": "relates_to" } ] } ``` Types: `relates_to`, `depends_on`, `supersedes`, `blocks`, `implements`, `documents`, `risk_for`. Each edge is created with per-relation tolerance: a bad edge reports `{ok: false, error}` in the tool result without losing the topic or the remaining edges. Both endpoints must exist and be visible to you. ### Server-side anchor validation Remote agents have no local checkout, so write responses carry `anchor_validation`, per-pattern match counts against the repo's **default branch**: `ok`, `overbroad` (>100 files), or `zero`. Warnings never block the write (a glob anchoring unmerged branch code legitimately shows 0); read them in the tool result and tighten flagged globs. Where the deployment holds no file index for the linked repo, the field arrives as `{ skipped }` with the reason instead of counts — an honest "not measured", never a silent pass. MCP clients (claude.ai, ChatGPT) **cache tool schemas per connector session**. After Driftless ships a schema change, reconnect the connector (or start a fresh session) to pick it up. Otherwise new parameters or tools won't be available. Tools such as `tags`, `areas`, and `driftless_collection` are **action-based**: pass `action` to pick the operation; if your client still shows removed Project tools or old per-operation tool names, reconnect to refresh. ### Governance from the MCP A topic becomes Knowledge only once an owner/admin merges it in. An MCP client always **puts a Note up for review** (`driftless_context_propose`); it can also **merge** (`driftless_context_approve`), but only with owner/admin authority. The MCP token acts as the human who authorized it, so `approve` succeeds only when that human is an owner/admin, and the client should run it **only when they explicitly ask** (a member's or faceless token is refused). The merge is stamped `approved_via: agent`. See [Governance](/concepts/governance). ## Authentication All MCP requests require authentication. Unauthenticated requests receive HTTP 401 with a `WWW-Authenticate` header pointing to the OAuth discovery endpoints. There are two ways to authenticate: * **API key**: pass your Driftless API key in the `X-API-Key` header. Best for CLI, agents, and CI. * **OAuth 2.0**: for published AI clients (ChatGPT, Claude) that need per-user consent. The server supports dynamic client registration and PKCE. ### Connecting with an API key Add this to your `claude_desktop_config.json` or equivalent: ```json theme={"theme":"github-light"} { "mcpServers": { "driftless": { "url": "https://api.trybrein.com/mcp", "headers": { "X-API-Key": "drift_your_api_key_here" } } } } ``` For local development, use `http://localhost:3020/mcp` and your local API key. ### Connecting with OAuth (Claude.ai, ChatGPT) The published ChatGPT app is named **Brein**. It connects to the same authenticated Driftless workspace and uses the same workspace permissions and MCP tool contracts; the name does not create a second account or data boundary. Published clients use OAuth 2.0 with PKCE. The flow is fully automatic: 1. Install Brein in ChatGPT, or enter `https://api.trybrein.com/mcp` as the MCP endpoint in Claude.ai 2. The client discovers the OAuth endpoints automatically via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` 3. You authorize in the Brein consent screen 4. The client receives a bearer token and uses it for MCP tool calls within the authorized workspace No manual OAuth configuration is needed. The client handles registration, PKCE, and token refresh. ## OAuth 2.0 reference ### Dynamic client registration Any client can register without authentication: ```bash theme={"theme":"github-light"} curl -X POST https://api.trybrein.com/api/v1/oauth/register \ -H "Content-Type: application/json" \ -d '{ "client_name": "My AI Client", "redirect_uris": ["https://myapp.com/oauth/callback"] }' ``` ### OAuth scopes | Scope | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `context:read` | Read topics and context | | `topics:create` | Create new topics | | `topics:write` | Update existing topics | | `work:write` | Write collections, records, entities, comments, tags, areas, plus merge and share actions | | `context:diff` | Read topic diff for local changes | | `broker:read` | Read broker connections, capabilities, and records | | `broker:invoke` | Invoke a broker operation | | `broker:admin` | Manage broker grants and criterion | | `market_data:read` | Read commercial intelligence (suppliers, opportunities, awards, risk marks, permits) — see [Market Data](/api/market-data) | | `commercial:read` | Read an exact Contact Path quote for selected CRM records; no contact coordinates are returned. | | `offline_access` | Refresh access without reconnecting | The `broker:*` scopes are enforced only when the Broker is enabled, and they gate its lane on top of rollout and grants. Discovery metadata advertises a subset of scopes; the enforced set is the authority. `market_data:read` is the documented, canonical scope for market-data reads, but today's default OAuth issuance does not yet grant it — `context:read` still satisfies those routes transitionally so no existing caller breaks. ### Endpoints | Method | Path | Purpose | | ------ | ----------------------------------------- | ----------------------------------------------------- | | `GET` | `/.well-known/oauth-protected-resource` | MCP resource metadata (RFC 9728) | | `GET` | `/.well-known/oauth-authorization-server` | Authorization server metadata (RFC 8414) | | `GET` | `/.well-known/openid-configuration` | OIDC-compatible discovery alias | | `GET` | `/api/v1/oauth/authorize` | Authorization consent screen (redirects to dashboard) | | `POST` | `/api/v1/oauth/token` | Exchange code for access token | | `POST` | `/api/v1/oauth/register` | Register an OAuth client (RFC 7591) | | `POST` | `/api/v1/oauth/revoke` | Revoke an access token | ## Token security * Authorization codes, access tokens, and refresh tokens are stored as **hashes only**, never plaintext * Tokens are never logged or returned after initial issuance * The MCP server does not import `@driftless/db`, `typeorm`, or any internal library; it calls the REST API exclusively