Share it with your team

Once your knowledge is in a Brain, the point is that everyone — and everyone’s agents — reads the same copy.

Invite people

From Settings → Members in app.nicia.ai, invite someone by email and pick their role. Accepting the invite creates their organization membership first, and the Brain access they need is granted against that membership — so the review inbox and connecting an agent both work the moment they accept, with nothing to re-authorize.

Connect Claude Code, Codex, Cursor, or any MCP client

Every Brain has one MCP endpoint, addressed by its handle:

https://api.nicia.ai/mcp/brains/{handle}

There are two ways to sign in to it.

In a browser. Paste the URL into a client that speaks MCP OAuth and it opens a browser to sign in as you. Nothing you paste is a secret. The access token the client receives is scoped to this Brain, carries read and write, expires on its own, and appears in the Brain’s key list under the name the client registered with (for example Claude Code), where you can revoke it like any other key.

With a key. Open the Brain in app.nicia.ai and press Connect. The dialog mints a key scoped to exactly this Brain and shows the credential once. Copy it before you close the dialog — it is not shown again, and the fix for a lost one is to rotate the key, not to look it up. A headless or CI client cannot open a browser, so this is its path.

The key is a secret; the URL is not. Keep the key in your environment rather than in the config file, so the file stays safe to commit and to share with a teammate who has their own key.

Claude Code — add to .mcp.json:

{
  "mcpServers": {
    "nicia-brain": {
      "type": "http",
      "url": "https://api.nicia.ai/mcp/brains/{handle}",
      "headers": { "Authorization": "Bearer ${NICIA_BRAIN_TOKEN}" }
    }
  }
}

Codex — add to ~/.codex/config.toml or .codex/config.toml:

[mcp_servers.nicia_brain]
url = "https://api.nicia.ai/mcp/brains/{handle}"
bearer_token_env_var = "NICIA_BRAIN_TOKEN"

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nicia-brain": {
      "url": "https://api.nicia.ai/mcp/brains/{handle}",
      "headers": { "Authorization": "Bearer ${env:NICIA_BRAIN_TOKEN}" }
    }
  }
}

Any other MCP client — Streamable HTTP against that same URL, sending Authorization: Bearer $NICIA_BRAIN_TOKEN. Prefer your client’s environment-backed secret setting over a literal in a config file.

Then export the key and restart the client:

export NICIA_BRAIN_TOKEN="nbk_…"

The URL names the Brain the way everything else on this site does, by its handle. The key in the header decides which Brain it may reach, so a handle that belongs to some other Brain answers the same 404 as one that does not exist.

To check the key before wiring a client to it, ask for the Brain it opens:

curl --fail-with-body "https://api.nicia.ai/v1/brains/{handle}" \
  -H "Authorization: Bearer $NICIA_BRAIN_TOKEN"

A one-command version of this page exists in the repository but is not installable today: packages/cli is unpublished, so npx nicia connect team:acme resolves nothing from the npm registry. Use the Connect dialog above. When the CLI does ship it will create the Brain in reviewed mode if it does not exist, mint a key named nicia-connect/<client>/<hostname> — so re-running it on the same laptop reuses that key instead of minting a second one — and merge one entry into the target client’s config, leaving every other MCP server in that file alone. The key gets read and write; --read-only narrows it to read. It will print:

Using existing Brain team:acme (mode reviewed; name, purpose, and mode left as they are)
Minted a Brain key.
Claude Code — /Users/priya/.claude.json: added MCP server "nicia-team-acme"

Restart Claude Code and ask it something from team:acme.

It authenticates with an organization key sent as Authorization: Bearer, and there is deliberately no --key flag — a secret on the command line lands in shell history and in ps output for every user on the machine, so it will only ever take one from NICIA_API_KEY or an echo-suppressed prompt.

What an agent can do with it

A key is a credential scoped to exactly this Brain, and the tools it sees follow its capabilities: read shows the seven that read, write adds the two that write, read and write together add the one that proposes a schema change, and review adds the one that says who was served what. There are eleven, and together they cover what an agent needs: read what the Brain knows, browse and cite its documents, notice what changed, put something new into it, give it a shape it lacks, see what is waiting for review, and account for what it was shown.

Tool	Does
`brain_context`	Semantic or open-ended retrieval over accepted records and source documents, with citations, a `staged` count and `warnings` as `POST /context` reports them, and a receipt. Use this when you do not know an exact identity or slug.
`brain_query`	Deterministic filtering by record kind, slug, exact link, and typed predicates on declared fields (`eq`, `ne`, `in`, `has`, ranges on number, date, datetime). It takes the body of `POST /query` less `branch`, and answers with the same records, `staged`, `warnings` and receipt id. Not semantic search; use `brain_context` for open-ended questions.
`brain_schema`	Read the Brain’s exact kinds, fields, links, and `declaredVersion`. When the credential can read, call it before writing typed records and again after `INVALID_RECORD_INPUT`.
`brain_events`	What changed since the agent last looked, as ids, field names, and versions — never values. Pass the returned `cursor` back as `after`. Preview; see Events and webhooks.
`brain_write_document`	Save markdown as source material, not typed facts. Its `action` says whether indexing is complete or the caller should wait.
`brain_write_records`	Create or update typed facts atomically. Preserve returned tokens for `ifMatch` updates and send an `idempotencyKey` for safe retries. Its `action` says whether knowledge changed or review is required.
`brain_evolve_schema`	Propose a kind, field, or link the Brain does not declare yet: the complete schema `brain_schema` returned, plus the additions. Changing an existing declaration (an enum value list, a safeguard) needs an `admin` key. The Brain’s mode decides, as it does for records: it lands on an `open` Brain and waits in review on a `reviewed` one.
`brain_documents`	List the documents the Brain serves, each with its outline (every heading as the exact `anchor` to cite), or read one document or one section of it. Reading text is receipted. Cite what you read in a record’s `evidence` with the same `anchor`; see Cite your sources. A branch key cannot use it. Preview.
`brain_receipts`	List the receipts this key committed (every key’s with `admin`), filtered by consumer, kind, key and time window, or get one by `receiptId` with the version of every source it pinned. Preview.
`brain_reads`	Who was served one record, document or source document, with the version each read was shown and how it stands now; `stale: true` for only the reads a correction made stale. Needs `review`. Preview.
`brain_proposals`	List review Proposals by source kind and status, or get one with its revisions, member ChangeSets and diff. Read-only; a branch key sees only its branch’s. Preview.

There is no tool that approves a change. An agent proposes; a person decides. There is also no tool that writes an answer for you: brain_context hands your agent the Brain’s knowledge and your agent’s own model does the answering.

So “check the handbook before you answer” stops being a thing you paste into a prompt and starts being something the agent can do.

For a simple request such as “Create a page named Onboarding notes”, the agent can call brain_write_document with title and text. The server handles the content digest and retry key, and the document is searchable through brain_context as soon as it is indexed. Indexed text and typed records are separate states: to put a typed fact into the Brain, call brain_write_records. Correcting something the Brain already knows is the same call again with the new value, or a new document that says so — there is no separate correction tool.

Every tool publishes a valid input example alongside its JSON Schema. The structured content of a staged record write includes the schema version used for validation:

{
  "action": {
    "outcome": "staged",
    "knowledgeChanged": false,
    "nextAction": "wait_for_review"
  },
  "validatedAgainst": { "declaredVersion": "schema-v7" }
}

Safe failures are equally explicit. Their text content is JSON with a stable code, whether the identical request is retryable, a concrete nextAction, and nextTool when another available tool is the recovery path. On a read/write connection, for example, INVALID_RECORD_INPUT points to brain_schema and RECORD_WRITE_CONFLICT points to brain_query. A model should never blindly repeat either one.

A record whose kind the Brain does not declare is refused, and the refusal says so: its action lists the undeclaredKinds and points to brain_evolve_schema, or, for a key that cannot read the schema, tells the agent to ask its operator. Dropping the kind to file the record as an untyped note is the wrong recovery — its fields would be stored but not queryable.

What an agent writes waits for you

Whether a connected agent’s write lands or waits is decided by the Brain, not by the credential. On a reviewed Brain a brain_write_records call is still typed and validated, but it stages instead of landing — the change waits in the queue, and nothing changes until somebody accepts it. The tool’s answer says staged and names the change, which is the id you find in the queue.

Check the mode before you hand a key to an agent that writes. A Brain created over the API with PUT /v1/brains/{handle} is open unless the request states "mode": "reviewed", and minting a key never changes the mode of a Brain that already exists — so a key against an open Brain writes into it unreviewed. The switch is one call:

curl -X PATCH "$API/v1/brains/team:acme" \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "content-type: application/json" \
  -d '{ "mode": "reviewed" }'

curl "$API/v1/brains/team:acme/changes?status=staged" \
  -H "authorization: Bearer $NICIA_KEY"

Settle it — from the same call, or from the review inbox in app.nicia.ai, which shows the diff and the source side by side:

curl -X POST "$API/v1/brains/team:acme/changes/chg_44a1e0/lifecycle/approve" \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "content-type: application/json" \
  -d '{}'

mode is the Brain’s own setting, so it governs every connected agent at once, and no credential carries an override of its own. If a pipeline needs to write straight in while agents are reviewed, give it its own Brain. See Keep it good and Review for the full model.

Everyone reads the same thing

The point of the shared copy is that a correction lands once. When Priya fixes the handbook, the next question anyone’s agent asks gets the corrected answer — no re-syncing, no stale local vault, no “which copy is right.”

Keep it good — review, contributions, and letting agents help maintain it.
Handing out keys — scoped keys for services and pipelines that don’t connect over MCP.