Remote Access

brain mcp over stdio only works for tools that can start a program on your own computer, like Claude Code. Claude on the web and in the phone app can only reach a server over HTTPS. Remote access gives each person a private address that Claude can reach, so they can search, read and save notes in their own brain from anywhere.

One connector, one address per company. Everyone clicks Connect and signs in with their work email.

How it fits together

123456789101112Claude (web, phone, Code)
   │  HTTPS, signed in through your identity edge
   ▼
Cloudflare Access     runs the sign-in (OAuth) and signs each request
   │
   ▼
brain mcp-router      checks the signature, finds that person's port
   │                  (holds no vault)
   ├─▶ brain mcp --http  (alice)   reads compiled/alice only
   │                               saves to spool/alice only
   └─▶ brain mcp --http  (bob)     reads compiled/bob only
                                   saves to spool/bob only

brainkit does not run the sign-in. An identity edge in front of it does, and brainkit only checks the signed note the edge attaches to each request. Cloudflare Access is what this guide describes; the check is generic, so another edge that signs requests the same way works with a settings change.

The tenant wall still holds. Each brain mcp --http process is given exactly one compiled vault and answers only to that person's email. The router never opens a vault. Three separate checks stand between a request and a vault: the edge's list of allowed emails, the router's route table, and the vault process's own pinned email. A wrong route is refused, never served. See the deployment rule.

Connect in Claude

Add the connector once
On a Claude Team or Enterprise plan, an owner goes to Settings → Connectors → Add custom connector and pastes the company address your admin gave you (for example https://mcp-acme.example.com/mcp). Everyone in the organization then sees it. On other plans, each person adds the same address themselves.
Each person clicks Connect
Claude opens a sign-in page. Sign in with your work email. The first time, you'll be asked to allow Claude to use your brain.
Ask about your brain
Try "what changed in my brain this week?" or "save a note: Ana prefers aisle seats." Notes you save appear in your Inbox after the next sync, usually within a few minutes.

If the sign-in page says Invalid nonce, the Allow page waited too long. Click Connect again and click Allow straight away.

On the Claude phone app the connector appears by itself once it has been added on the web. Open it, tap Connect, and sign in the same way.

Claude remembers a connector's tool list from when it was first connected. If you connected before saving notes was available, Disconnect and Connect the connector once and brain_capture will appear.

Connect other apps

Any app that supports remote MCP servers with sign-in can use the same address. Claude on the web and phone is the one we have tested end to end. The others follow each app's own documentation, and their menus change, so treat these as the shape of the steps.

App	How to add it
Claude Code	`claude mcp add --transport http brain <address>`, then `/mcp` → brain → Authenticate.
Cursor	Add `{"mcpServers": {"brain": {"url": "<address>"}}}` to `~/.cursor/mcp.json`, then click Needs login.
VS Code	In `.vscode/mcp.json`: `{"servers": {"brain": {"type": "http", "url": "<address>"}}}`, then Start.
ChatGPT	Turn on developer mode under Settings → Connectors → Advanced (plan-dependent), add a connector with the address and choose OAuth.

Every app opens the same sign-in page. Apps that need a fixed client ID instead of registering themselves are not supported by the setup above.

If the brain files are on the same computer as the app, brain mcp over stdio needs no address and no sign-in (see brain mcp). It has the six read tools only; saving notes needs the remote address.

What Claude can do

The same six read tools as brain mcp (brain_search, brain_read, brain_links, brain_graph, brain_recent, brain_facts), plus brain_capture, which saves a note into your Inbox. Claude cannot edit or delete existing notes this way.

With Fleet

Fleet does every step in "Set it up by hand" for you. On a company's page, Remote MCP → Set up creates the tunnel, the Cloudflare Access application and its policies, the per-person services, the route table and the cron change, then checks each service's health. Running it again changes nothing that is already right. When someone joins or leaves, Fleet updates the allowed emails, the route table and that person's service in the same pass. Disable removes it all again.

The address is https://mcp-<company>.<your domain>/mcp.

Set it up by hand

If you run brainkit without Fleet, here is every piece. You need a Cloudflare account with Zero Trust, and brainkit[remote] installed on the brain box:

1uv tool install 'brainkit[remote] @ git+https://github.com/joedanz/brainkit@<release tag>'

The shipped units run /usr/local/bin/brain. uv tool install puts the program in the installing user's own folder, so link it once (ln -s ~/.local/bin/brain /usr/local/bin/brain), or change ExecStart= in both unit files to the real path (which brain).

Create the Cloudflare pieces
1. A tunnel that sends one hostname (say mcp-acme.example.com) to http://127.0.0.1:8900.
2. A self-hosted Access application on that hostname with Managed OAuth turned on: dynamic client registration enabled, allowed redirect addresses https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback, and localhost and loopback allowed (for Claude Code).
3. An allow policy listing your staff's work emails.
4. Note the application's AUD tag and your team's address (https://<team>.cloudflareaccess.com).

Write the shared settings

/etc/brain/mcp.env (no secrets in it):

123BRAIN_MCP_ISSUER=https://<team>.cloudflareaccess.com
BRAIN_MCP_JWKS_URL=https://<team>.cloudflareaccess.com/cdn-cgi/access/certs
BRAIN_MCP_AUDIENCE=<the application's AUD tag>

Add each person
For each person (alice here), a settings file /etc/brain/mcp.d/alice.env:
BRAIN_MCP_PORT=8901 BRAIN_MCP_EMAIL=alice@acme.com
a spool folder for saved notes, owned by the user the service runs as:
install -d -o brain -m 0700 /srv/brain/spool/alice
brain cycle must run as the same user that owns the spool (the unit's User=). A spool the cycle can't read can't be emptied; the cycle prints a warning naming the folder, and saved notes pile up until Claude says the queue is full.
and the service:
install -m 644 deploy/brain-box/brain-mcp@.service /etc/systemd/system/ systemctl enable --now brain-mcp@alice
Start the router
/etc/brain/mcp-routes.yaml maps each email to that person's port:
version: 1 routes: alice@acme.com: 8901 bob@acme.com: 8902
install -m 644 deploy/brain-box/brain-mcp-router.service /etc/systemd/system/ systemctl enable --now brain-mcp-router
The router reloads this file when it changes. A broken edit is ignored and the last good table stays in force.
Let the cycle file saved notes
Add --spool-root /srv/brain/spool to the brain cycle line in your cron. Saved notes are filed into each person's Inbox on the next cycle.

Adjust User= in both unit files for your install, and add an EnvironmentFile for your embedding settings to the per-person unit if you want semantic search.

Troubleshooting

Each failed request returns a small JSON body: {"error": "<code>", "message": "..."}.

Code	Status	What it means
`unauthenticated`	401	No signed identity, or it is expired or from the wrong place. Check `BRAIN_MCP_ISSUER` and `BRAIN_MCP_AUDIENCE`.
`no_identity`	403	The request was signed but names no person (for example a service token).
`no_route`	403	The email is not in the route table. Add it to `mcp-routes.yaml`.
`wrong_person`	403	The router sent a request to someone else's process. Check the ports in the route table.
`rate_limited`	429	Too many requests; retry after the `Retry-After` seconds.
`too_large`	413	The request was over 1 MB.
`unsupported_encoding`	415	Compressed request bodies are not accepted.
`method_not_allowed`	405	Use `POST`.
`upstream_unavailable`	503	That person's process is down or restarting.

If a person's brain does not answer, check journalctl -u brain-mcp@<id> and curl http://127.0.0.1:<port>/healthz. If saved notes never appear, check that the cycle runs with --spool-root and look in /srv/brain/spool/<id>/.rejected/.

Ask AI about this page