brain-mcp
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
brain-mcp
A managed MCP server for the Brain memory database. It exposes Brain's tenant surface as MCP tools over remote Streamable HTTP, so any MCP client (Claude, ChatGPT, Cursor, Copilot, …) can give its agent durable, current-truth memory in one connection.
It is a thin, stateless front for Brain's REST surface (/v1/*): point
BRAIN_MCP_BACKEND_URL at the hosted gateway or a self-hosted
brain-edge — the JSON contract is the same. It defaults to
https://api.stg.arc-labs.ai, the Brain that is publicly reachable today, so
a first run needs a key and nothing else.
It holds no credential of its own. Each request carries the caller's own Brain API key, which the backend resolves to that caller's namespace and space. So one hosted deployment serves every user at their own identity, and the isolation between them is the backend's existing per-key scoping rather than anything this server decides. See Identity.
Quick start
Do not install this package directly. It is the server; the thing that sets
a machine up is @brain-db/cli:
npx @brain-db/cliThat opens your browser, asks you to confirm a code shown in your terminal, and configures every MCP client it finds — including this server, the Claude Code plugin, and the skills that tell an agent when memory is worth writing. No key is copied by hand.
brain connect
Give the agents on this machine a memory they keep between sessions.
backend https://api.stg.arc-labs.ai
machine your-laptop
clients Claude Code, Codex CLI, Claude Desktop
┌──────────────────────────────────────────┐
│ Confirm this code in your browser │
│ │
│ WXYZ-2345 │
│ │
└──────────────────────────────────────────┘
configured
✓ Claude Code plugin brain installed, key in your keychain
✓ Codex CLI via `codex mcp add`
✓ Claude Desktop …/claude_desktop_config.json
✓ skill: brain-memory ~/.agents/skills/brain-memoryWhy this package has no installer any more
It had one — brain-mcp init — and it is gone rather than deprecated, because
setting a machine up and serving an agent are different jobs:
the installer is one-shot and interactive: it opens a browser, waits on a human, shells out to other CLIs, and can change freely because every run is somebody's first;
this is long-lived and on the hot path: an agent starts it on every cold start, and it should do nothing but speak the protocol.
Fusing them also made this package the wrong thing to recommend. Nobody wants an MCP server — they want their agent to remember things — and a tool surface with no skill beside it is a tool surface an agent picks wrongly from. The CLI ships both. This ships the server.
Related MCP server: everos-mcp
Configuring it by hand
If you would rather not run an installer, this is what it writes:
{
"mcpServers": {
"brain": {
"command": "npx",
"args": ["-y", "@brain-db/mcp", "--stdio"],
"env": {
"BRAIN_MCP_BACKEND_URL": "https://api.stg.arc-labs.ai",
"BRAIN_MCP_API_KEY": "brain_…"
}
}
}
}Get the key from the dashboard under API Keys.
Run from source
npm install
cp .env.example .env # set BRAIN_MCP_BACKEND_URL (and _API_KEY for stdio)
npm run build
npm start # HTTP on :3333, MCP endpoint at POST /mcp
npm start -- --stdio # or stdio, for a client that owns the processLiveness: curl -fsS localhost:3333/healthz.
Configuration
Env var | Required | Default | Meaning |
| no |
| Brain REST base URL (gateway or brain-edge). |
| stdio only | — | The caller's Brain key. Required with |
| no |
| Serve MCP over stdin/stdout instead of HTTP (same as |
| no |
| Listen port (HTTP only). |
| no |
| Bind interface. |
| no |
| Per-request backend timeout. |
Container
Published to GHCR on every version tag, multi-arch (linux/amd64,
linux/arm64):
docker run -p 3333:3333 \
-e BRAIN_MCP_BACKEND_URL=https://brain-edge.internal \
ghcr.io/arc-labs-ai/brain-mcp:latestThat is the whole configuration. The image holds no credential and has no
default for one — each caller's Authorization: Bearer brain_… is what the
request runs as, so the same container serves every user at their own
identity. Pin a digest rather than a tag in a deploy manifest; each release
prints one.
Two things the image commits to, because a deploy depends on them:
curlis installed. Our ECS task definition hardcodes its container health check ascurl -f, so an image without it fails every probe and is killed and replaced in a loop that reads as the app being broken. The image's ownHEALTHCHECKuses curl for the same reason — if it went missing, the image would fail at build time rather than in a deploy.The health path is
/healthz, and it is unauthenticated: a load balancer has no bearer to send. A target group pointed at anything else will never see a healthy target.
The published image is smoke-tested before its manifest is tagged — it must
come up healthy, refuse an unauthenticated POST /mcp with a 401 and a
WWW-Authenticate challenge, accept a credentialed one, carry no baked-in
key, and run as a non-root user.
Tools
58 tools over the tenant surface. ? marks an optional argument. No tool takes
a customer or tenant id: the identity is the caller's credential, resolved
server-side, so there is nothing for an agent to set — or to get wrong.
Predicates and relation types are always namespace:name — acme:prefers,
never prefers. A bare name is rejected. whoami gives you the namespace.
Memory — The core loop. Most agents only ever call the first three.
Tool | Args | What it does |
|
| Store a fact, event, or conversation turn. Brain extracts typed facts and supersedes stale ones automatically. Returns the memory id. |
|
| Retrieve the current, consistent truth against a query. Returns an answer shape (single / many / none) with evidence and confidence — stale and contradicted facts are already resolved server-side. |
|
| Delete a specific memory. Soft by default (tombstone with a grace window); set hard=true to zero it immediately. Cascades to dependent facts. |
|
| Page through what is stored, newest first. Use when you need to see what exists rather than answer a question — recall is for questions, this is for inventory. |
|
| Everything behind one memory: the typed facts extracted from it, its provenance, and how it scored. Use when an answer looks wrong and you need to see why that memory was or was not used. |
|
| Render this workspace's learned standing instructions into a system-prompt block, with the statement ids behind each line. Call it once at the start of a session rather than recalling directives one at a time. |
|
| Store a memory whose embedding you already computed. Almost certainly not what you want — |
Reasoning — Ask Brain to plan or answer over what it knows.
Tool | Args | What it does |
|
| Find a route from a start state to a goal across what is known. Use for 'how do we get from here to there' questions; it reasons over stored facts rather than inventing steps. |
|
| Infer what follows from an observation, given what is already known. Use to check an implication before acting on it. |
Entities — The typed entity layer. entity_type_id comes from get_schema.
Tool | Args | What it does |
|
| Declare an entity of a known type. Creating one that already exists under the same name is a conflict, not a silent no-op — resolve_entity first if you are unsure. |
|
| Entities of one type. The type is required — listing across every type is refused rather than silently paged. |
|
| Map a surface form ('the Acme account', 'Priya') to the entity it refers to, or report no match. Use before creating, and before assuming two mentions are the same thing. |
|
| One entity by id, with its canonical name, type and attributes. |
|
| Walk outward from an entity along its relations. Use to answer 'what is connected to this, and how' without pulling the whole graph. |
|
| The relations attached to one entity, without walking further out. |
|
| Replace an entity's fields wholesale — omitting |
|
| Give an entity a new canonical name, keeping the old one as an alias by default — that alias is how a mention in older text still resolves. |
|
| Fold a duplicate into the entity that remains. The direction is not symmetric; |
|
| Pull an entity back out of the survivor it was merged into. Pass the absorbed id, not the survivor's. |
|
| Tombstone an entity. If it is a duplicate rather than a mistake, |
Graph — Typed relations between entities.
Tool | Args | What it does |
|
| Connect two memories with a typed edge (caused, followed_by, derived_from, similar_to, contradicts, supports, references, part_of). Use when the relationship is real but neither memory states it. |
|
| Remove a typed edge between two memories. Idempotent. |
|
| A page of the workspace's knowledge graph — entities and the relations between them. Use to see structure; use recall to answer a question. |
Knowledge — Read the statements and relations Brain extracted.
Tool | Args | What it does |
|
| Page through the subject–predicate–object facts extracted from this workspace's memories. Use to audit what Brain believes, not to answer a question. |
|
| One statement by id, with the memory it came from. |
|
| One relation by id, with its endpoints and type. |
|
| The full supersession chain, oldest to newest. Reach for it when a recall and a statement disagree: recall ranks by similarity, so a superseded claim can outrank the one that replaced it. |
|
| Assert a claim directly instead of waiting for extraction. |
|
| Replace a claim with a corrected one, keeping both and the link between them. The right tool when something changed — not |
|
| Soft-tombstone a claim; the row survives for audit. |
|
| Retract a claim so its content does not survive. Prefer |
|
| Assert a typed edge between two entities. For an untyped edge between two memories, use |
|
| Replace an edge with a corrected one, keeping the chain. |
|
| Tombstone a typed edge. Traversals stop crossing it. |
Schema — Declare the entity and relation types this namespace uses.
Tool | Args | What it does |
| — | The entity and relation types declared for this workspace. Read this before creating entities — |
|
| Check a schema document without storing it. Use before upload_schema so a malformed document is caught before it changes anything. |
|
| Merge new declarations into the workspace schema. Additive: it cannot drop a declaration, and changing an existing one is a conflict. Replacing a schema destructively is not available here. |
|
| The schema's version history, as opposed to |
| — | The entity types this workspace can use, each with the numeric |
| — | What will read a new memory and what it is allowed to produce. Read-only: extraction is always on. |
|
| Remove one declared |
|
| Replace the whole document instead of merging. Anything the new document omits is a removal, and the rows bound to a dropped declaration go with it. |
Query — What Brain would do, and what it did.
Tool | Args | What it does |
|
| The plan for a query and its estimated cost, without running it. Use when a recall was slow or empty and you want to know why before retrying. |
|
| Runs the query and reports what each stage actually cost. Note that it RUNS — it is not the free counterpart to |
Workspace — Sessions and spaces.
Tool | Args | What it does |
|
| Provision a session so one conversation's memories can be told from another's. The id is yours to choose and the call is idempotent on it. |
|
| The sessions in this workspace. |
|
| Retire a session. Soft by default, which leaves its memories in place. |
|
| The spaces this credential can see. |
|
| Provision this caller's space and report its stats. Takes no name and creates no other space — which space you are in is decided by the key you connect with. Idempotent: |
|
| Erase this caller's whole workspace — every memory, and the typed graph derived from it. No soft mode and nothing restores it. |
|
| Read what changed since a point in the feed. Returns a bounded slice and closes — it does not stream. Pass the returned |
Identity — What this request runs as, and what the deployment can do.
Tool | Args | What it does |
| — | Report the identity this connection runs as — the namespace and space your API key resolves to on the server. Call it first when anything looks like it is reading the wrong workspace. |
| — | What this deployment supports — limits, enabled extractor tiers, protocol version. Use to check a limit before hitting it. |
| — | Whether this workspace has an LLM provider key, and which provider and model it is for. Returns a display fingerprint, never the key. Use to confirm the cause when a write is refused for a missing key. |
| — | Re-check the stored key by asking the provider. Takes nothing and sends no secret. A key that worked at registration can be revoked later, and without this the first sign is an opaque upstream failure on a write. |
|
| Install this workspace's provider key, so writes can be extracted. Takes the name of an environment variable, never a key — the handler reads it, so the secret never enters a tool argument. Verified with the provider before it is stored. stdio only. |
|
| Probe a key against the provider without storing it or touching the registered one. Same env-var rule as above. stdio only. |
| — | Revoke the provider key. Every subsequent write is refused until one is registered again. Incident response, not cleanup. stdio only. |
How the hazardous routes are shaped
The line is not "is it a write" — entity merges, statement supersessions and schema drops are all writes and all tools, because each is recoverable, scoped to one record, or both. What matters is whether a confused or steered agent could leak a secret or lose something unrecoverably. Five routes that once had no tool now have one, because each found a shape that keeps its hazard out of reach:
PUT/POST /v1/llm-credential[/test]take a raw provider key. The tools take the name of an environment variable instead and read it in the handler, so the key never occupies a tool argument — where it would be written into the model's context and into every transcript and log of the session, and stay valid there. They are registered on stdio only: over HTTP the process environment belongs to whoever runs the deployment, not to the caller, so the same argument would read someone else's secret.DELETEcarries no secret and is a plain tool, marked destructive because revoking stops every write.PUT /v1/schemareplaces rather than merges, andforce_drop_existingtakes the rows bound to a dropped declaration with it. The flag is required with no default, so the destructive choice cannot be made by omission, and running itfalsefirst reports what would go.POST /v1/memories/vectortakes a caller-computed embedding, which an agent cannot produce. The tool exists for a program driving this server; its description sends an agent toremember.GET /v1/subscribeis Server-Sent Events, which request/response cannot represent.subscribe_eventsdrains a bounded slice — to a deadline and an event count — and returns the resume LSN, so following the feed is a loop the caller drives rather than a tool that hangs.DELETE /v1/spacestakes no path parameter, because every space verb acts on the caller's own space — so it is "erase this workspace" from a single call, with no id in the request that could fail to match and nothing that undoes it.delete_spacesupplies the missing id:confirm_space_idis required with no default and is checked against the space the credential actually resolves to, so a caller that is in a different workspace than it believes gets a refusal and loses nothing. Read the id fromwhoamiimmediately before the call. It is the only tool that reads before it writes, and the extrawhoamiis the price of that check.
Every route on the tenant surface now has a tool.
Identity
Every request runs as the caller, and nothing about that is this server's decision.
The caller's brain_… API key goes to the backend verbatim as
Authorization: Bearer. The backend resolves it to the (namespace, space)
the key is bound to and runs the operation as that tenant — the same path the
SDK and plain curl take. Rate limiting, metering and billing key off the same
resolved scope, so a hosted deployment accounts per user without being told who
anyone is.
This is why there is no customer_id argument, and why adding one back would
be worse than useless. Both backends scope by the key alone:
Hosted gateway — reads the
x-brain-namespace/x-brain-spaceheaders only for console JWTs, and ignores them for API keys (services/gateway/src/api/middleware/auth.rs). A key's own bound scope wins.Self-hosted brain-edge — scopes by the key's bound identity and ignores the scope headers too.
So a tool argument that claimed to select a customer would be accepted, sent,
ignored, and reported as success. Earlier versions of this server did exactly
that, and the server also held one shared service key — which meant every
caller of a hosted deployment landed in that key's workspace while the surface
read as if it isolated them. Per-caller credentials are what makes the one-URL
deployment correct; dropping customer_id is what stops it claiming to be
correct in a second, contradictory way.
To check which identity a connection has, call whoami. It reports what the
backend resolved, not what this server was configured with, so it cannot agree
with a mistake.
Running one
Public, no shared secret, no network boundary required:
BRAIN_MCP_BACKEND_URL=https://brain-edge.internal brain-mcpA request with no bearer gets a 401 and reaches the backend not at all. There
is deliberately no env-var fallback on the HTTP path: a server-held key would
make a client that forgot its header succeed as somebody — the one failure mode
that is invisible in production, because it looks exactly like working.
No OAuth today
BRAIN_MCP_OAUTH_ENABLED is gone, and setting it is a startup failure rather
than a no-op.
OAuth and pass-through are not two settings; they are two answers to "what is
in the Authorization header", and there is one header. The OAuth mode put a
JWT there, called the backend with a server-held service key, and selected a
namespace from a token claim — a claim both backends ignore for key callers. It
authenticated the caller and then served them the service key's workspace. A
deployment that set the flag believed it was isolating tenants, so the flag
fails loudly instead of quietly.
Real OAuth needs an authorization server that signs asymmetrically and publishes JWKS, and a way to map a verified token to a Brain identity. Neither exists yet. When they do, this is where it goes.
Errors
Every tool funnels failures through one renderer, so a condition reads the same
whichever tool hit it. A failed call comes back as an isError result (never a
thrown exception, which an MCP client reports as a transport fault) with four
labelled lines, plus a fifth when the backend supplied a trace id:
error: namespace acme has no LLM credential registered
code: llm_credential.missing http 409
retry: no — this call will fail identically until the cause below is fixed
fix: this workspace has no LLM provider key configured. Brain extracts typed
facts … a workspace admin needs to add an OpenAI or Anthropic key in the
Arc Labs dashboard under Settings → Providers.
trace_id: 01a1a1f6-0134-7ae1-8525-aaa6952f8d9dThe trace_id line appears only when the backend sent one — the gateway does
on every problem response, and it is the difference between "something broke"
and a line an operator can search, because the gateway withholds 5xx detail
from the response on purpose and logs it under that id.
The retry: line is the part that changes agent behaviour. Left to infer it, an
agent either retries a terminal failure until it gives up and tells the user
their data was lost, or abandons a transient one that would have succeeded a
second later. The two conditions that are easiest to confuse are kept
distinct on purpose: llm_credential.missing (409, terminal, needs an admin)
and llm_credential.unavailable (503, transient, needs nothing).
All twenty-six codes either backend can emit have their own guidance, and
that span matters: the gateway and brain-edge barely overlap — unauthorized
and bad_request against auth.invalid_key and request.malformed — so a
table built from one leaves the other almost entirely unrecognised. A code
either backend grows later renders as (unrecognised) with a status-derived
verdict rather than being passed through silently. The mapping and its drift
guard live in src/server/result.ts and test/server/errors.test.ts.
License
Apache-2.0.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
OAuth-protected, read-only-by-default MCP server for provenance-labeled QuillCaddie project memory.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceEnables remote MCP clients to securely access AgentMemory tools like memory_recall, memory_smart_search, and memory_save through OAuth 2.1 and Streamable HTTP, while keeping the AgentMemory backend secret private.-
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to interact with an EverOS v2 memory store over local Streamable HTTP, providing read-only memory tools and an opt-in, approval-gated write capability.-
- AlicenseBqualityBmaintenanceExposes a local-first personal brain to any MCP client, letting agents perform identity-grounded memory recall, simulate stances and value conflicts, propose or approve audited guardrail changes, take snapshots with drift comparison, and run a neural validation harness. Everything runs against a local SQLite neuron/synapse memory graph with consent-gated, append-only auditing.6CC BY-4.0
- AlicenseNot gradedqualityBmaintenanceExposes a remote Streamable HTTP MCP endpoint that lets an AI client save, search, and retrieve structured memories, archived conversations, social-account notes, and knowledge documents. Access is scoped by per-client API keys with configurable read/write permission levels, collections, and operations.ISC