# Connect Brain

Connect Brain. Your coding agent integrates it, tests it, and shows you the proof.

## Five-minute setup

Ask the Brain operator for three values:

- the hosted MCP URL;
- a Brain-bound key with `records:read` and `context:read`;
- the company or personal Brain name you expect `brain_status` to return.

Install the unpublished, checksum-verified CLI directly from your service:

```bash
curl -fsSL https://docs.brain.new/downloads/install.sh | sh
export BRAIN_API_KEY="..."
brain connect --url "$BRAIN_MCP_URL" --company "Acme" --client auto
brain doctor --json
```

`brain connect` detects Codex, Claude Code, and Cursor. Use `--client codex,claude,cursor` to name
them explicitly. The installer verifies the CLI, canonical Skill, reference, and generated client
wrappers; `brain connect` installs the matching wrapper without overwriting a customer-owned file.
It never accepts a key as an argument and never writes one into the repository.

## Connect your agent

Give the agent the generated `brain-integrate` Skill, then ask it to resume from
`.brain/integration.json`. The receipt is the state machine; chat history is not.

The agent must begin read-only, run `brain_status`, integrate Context at one product seam, resolve
one citation with `get_record`, preserve the full response state, run the repository tests, and
run the doctor. It may add `remember` only when writes are explicitly requested.

## Codex setup

```bash
codex mcp add brain --url https://your-brain.example/mcp \
  --bearer-token-env-var BRAIN_API_KEY
```

Copy the generated Skill to your Codex skills directory, or keep it in the project instructions.
The CLI emits the exact path it configured.

## Claude Code setup

```bash
claude mcp add --transport http brain https://your-brain.example/mcp \
  --header 'Authorization: Bearer ${BRAIN_API_KEY}'
```

The generated Claude wrapper and canonical Skill have the same workflow; neither contains a
credential.

## Cursor setup

`brain connect --client cursor` merges only the `brain` entry into `~/.cursor/mcp.json` and
preserves unrelated servers. The header keeps `${env:BRAIN_API_KEY}` as an environment reference.
If Cursor was opened from the Dock, ensure its process receives that environment variable.

## Generic MCP

Use Streamable HTTP at `/mcp` with `Authorization: Bearer $BRAIN_API_KEY`. Tool discovery returns
exactly `brain_status`, `context`, `get_record`, and `remember`.

## Read-only integration

Call `context` where the application must decide using prior facts—not at every screen or model
call. Preserve:

- `status`, including `processing`;
- `citations` and their `record_id` values;
- `unknowns`, `conflicts`, and `abstained.reason`;
- `budget`, `cost`, `watermark`, and request identity.

Resolve at least one citation with `get_record` before the application treats Context as evidence.
The application—not Brain and not the coding agent—keeps authority over accepted business state.

## Idempotent writes

Add `records:write` only when the product genuinely needs new Records. One logical event gets one
stable source identity and one stable idempotency key. A retry reuses both. Pass `remember`'s
watermark to the next `context` call as `min_watermark`; `processing` is an honest result, not a
failure to hide.

On a dedicated test Brain with an explicitly writable key, `brain doctor --json --write-probe`
adds two labelled synthetic Records with `visibility: shareable`: a stable Record whose replay must
return the same Record and watermark, plus a per-run freshness Record whose watermark must produce
a cited read-your-write result that resolves. Do not run it on customer production data by accident.

## Citations and authority

Records are immutable inputs. Memories are derived claims. Objects are application-accepted state.
Context is a bounded view for one task. A model can propose an Object; it cannot silently accept
one. A citation proves what evidence Brain used, not that the application must agree with it.

## Processing and watermarks

A successful write can still return a processing Record. The watermark names the evidence
boundary. Retry Context with that boundary until it is ready, using bounded backoff. Never serve
older Context as if it included the new write.

## Errors and repair

`brain doctor --json` checks authentication, identity, tool discovery, annotations, scopes,
failure shapes, Context, and citation resolution. Each failure records a stable code, surface,
whether an agent can repair it, the next action, retry command, request ID when available, and a
documentation URL.

Run `brain receipt` to inspect progress and `brain support-bundle --json` for a redacted handoff.
Neither output includes a key, memory content, or Record identifier.

## Status and doctor

```bash
brain status --json
brain doctor --json --query "a known customer fact"
brain receipt
```

Use a query whose answer the customer is authorized to inspect. The doctor stores only counts and
check states; it never puts returned content into the receipt.

## Revocation and deletion

`brain disconnect` removes only Brain-owned client configuration. It does not pretend to revoke
the server credential. Ask the Brain operator to revoke the key by its safe last four characters;
revocation takes effect on the next request. Rotate with a new key rather than restoring a revoked
one.

Record or Brain deletion is a separate custody operation in the HTTP API. It is intentionally not
an MCP tool and should never be part of an unattended agent installation.

## Support bundles

```bash
brain support-bundle --output brain-support.json --json
```

Review the JSON before sharing it. It contains CLI version, safe endpoint metadata, receipt state,
checks, and failure codes—not credentials, customer content, citation IDs, or query text.

## Limitations

- The design-partner path is scoped bearer authentication, not OAuth discovery.
- Key issuance and server revocation are operator actions today.
- The CLI is downloaded from the service; it is not published to npm.
- The public sandbox is ephemeral `InMemoryStore`; customer durability is proven only on the
  authenticated `SpineStore` service.
- Context conflicts and Object arbitration remain named product gaps; see
  [Known limitations](limits.html).