Brain Operator MCP

A TypeScript MCP server that lets ChatGPT and other MCP clients read and safely modify TheBrain through the TheBrain REST API.

Setup

npm install
cp .env.example .env
# edit .env and set THEBRAIN_API_KEY
npm run dev

The server defaults to:

• GET /health

• POST /mcp

• TheBrain Cloud API base URL: https://api.bra.in

Related MCP server: MCP Server

Health

curl http://localhost:3000/health

Expected:

{
  "ok": true,
  "name": "brain-operator-mcp",
  "version": "0.1.0"
}

MCP Inspector

npm run inspect

Use http://localhost:3000/mcp as the Streamable HTTP endpoint.

ChatGPT App Endpoint

For development, expose the local server through HTTPS:

npm run dev
ngrok http 3000

Then add this MCP server endpoint in ChatGPT developer mode:

https://<ngrok-subdomain>.ngrok.app/mcp

If MCP_API_TOKEN is set, clients must send:

Authorization: Bearer <MCP_API_TOKEN>

Tools

Read-only:

• health_check

• list_brains

• get_brain

• search_thoughts

• get_thought

• get_thought_graph

• get_note

• list_attachments

Safe writes:

• create_thought

• update_thought

• create_link

• append_note

• add_url_attachment

Plan workflow:

• create_change_plan

• get_change_plan

• discard_change_plan

• commit_change_plan

Safety

• Never put a real API key in source, docs, tests, logs, screenshots, or commits.

• Single-step write tools respect WRITE_TOOLS_ENABLED.

• Destructive tools are not registered in v0.1.

• Batch writes must be created as a plan, reviewed by the user, then committed by planId.

• Notes are append-only and limited by MAX_NOTE_CHARS.

• URL attachments reject local and private-network hosts.

Manual Smoke Tests

Read-only:

Call list_brains.
Pick a brainId.
Call search_thoughts with queryText = "test".
Call get_thought on one result.

Single-step write:

Call create_thought:
- name: "[MCP_TEST] Brain Operator Smoke Test"
- label: "Created by brain-operator-mcp smoke test"

Call append_note on created thought:
- markdown: "This is a smoke test note."

Batch plan/commit:

The example below uses redacted placeholders. Do not paste private source notes into public docs, issues, or screenshots.

{
  "title": "[MCP_TEST] Redacted Import",
  "changes": [
    {
      "id": "c1",
      "op": "create_thought",
      "clientRef": "t_root",
      "name": "[MCP_TEST] REDACTED_ROOT_TOPIC",
      "label": "[REDACTED_LABEL]"
    },
    {
      "id": "c2",
      "op": "create_thought",
      "clientRef": "t_core_loop",
      "name": "[MCP_TEST] REDACTED_CHILD_TOPIC"
    },
    {
      "id": "c3",
      "op": "create_link",
      "fromRef": "t_root",
      "toRef": "t_core_loop",
      "relation": "child"
    },
    {
      "id": "c4",
      "op": "append_note",
      "targetRef": "t_root",
      "markdown": "[REDACTED_MARKDOWN_CONTENT]"
    }
  ]
}

Then call commit_change_plan with:

{
  "planId": "returned_plan_id",
  "confirm": true
}

Common Errors

• BRAIN_ID_REQUIRED: pass brainId or set THEBRAIN_DEFAULT_BRAIN_ID.

• WRITE_DISABLED: set WRITE_TOOLS_ENABLED=true when you intentionally want writes.

• UNSAFE_URL: use a public http or https URL.

• PLAN_NOT_PENDING: the plan was already committed, discarded, or expired.

Verification

npm run typecheck
npm run lint
npm test
npm run build