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

Open the Brain in app.nicia.ai and press Connect. Pick your client, and the dialog mints a Connection scoped to exactly this Brain and shows you the configuration to paste, with the credential displayed once. Copy it before you close the dialog — it is not shown again, and the fix for a lost one is to rotate the Connection, not to look it up.

The credential is a secret; the URL is not. Keep the credential 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 credential.

Claude Code — add to .mcp.json:

{
  "mcpServers": {
    "nicia-brain": {
      "type": "http",
      "url": "https://api.nicia.ai/mcp/brains/{brainId}/connections/{connectionId}",
      "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/{brainId}/connections/{connectionId}"
bearer_token_env_var = "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 credential and restart the client:

export NICIA_BRAIN_TOKEN="nbk_…"

The MCP URL is the one place on this site that takes Nicia’s opaque brainId rather than your handle, because a Connection is addressed by the pair it was minted for. Both ids come from the dialog; you never assemble that URL by hand.

To check the credential before wiring a client to it, the Connection’s handshake answers directly:

curl --fail-with-body -X POST \
  "https://api.nicia.ai/v1/brains/{brainId}/connections/{connectionId}/handshake" \
  -H "Authorization: Bearer $NICIA_BRAIN_TOKEN" \
  -H "content-type: application/json" \
  --data '{"requiredCapability":"read"}'

Planned — not published yet

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 if it does not exist, mint a scoped credential named nicia-connect/<client>/<hostname> — so re-running it on the same laptop reuses that credential 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. It will print:

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

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

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 Connection is a credential scoped to exactly this Brain. The tools available track that credential’s capabilities; a Connection granting read and write enables ten tools. The five you will use most:

Tool	Does
knowledge_context	Assemble bounded context from accepted knowledge; the response carries a committed read receipt
knowledge_query	Run a structured, snapshot-addressed query against the Brain’s accepted state
knowledge_think	Ask a natural-language question and get a synthesized, cited answer grounded in the Brain’s corpus — restricted to the pages behind accepted claims once the Brain has any; the response carries a committed read receipt naming every source the answer cites
knowledge_submit_evidence	Submit versioned source material — not accepted state on its own, until a mutation cites it
knowledge_submit_mutations	Submit typed knowledge mutations; whether one lands or stages for review follows the Brain’s mode

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

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 knowledge_submit_mutations call is still typed and canonical, but it stages instead of landing — the mutation waits in the queue carrying the evidence it cites, and nothing changes until somebody accepts it.

Check the mode before you hand a Connection 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 Connection never changes the mode of a Brain that already exists — so a Connection 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/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.”

Next

• 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.