Getting Started

What is ButlerBrain?

ButlerBrain is a Brain-as-a-Service platform that gives your AI assistants semantic memory via MCP (Model Context Protocol). Your AI remembers conversations, documents, web pages, and events — across every tool you use.

Connect Claude Code, Cursor, Claude.ai, OpenClaw (Discord, Signal, WhatsApp, Telegram), or any MCP-compatible tool to your ButlerBrain endpoint, and they instantly gain access to your personal knowledge base. No more re-explaining context. No more lost notes. Your brain, always available.

How It Works

When you save a thought, crawl a web page, or sync your Obsidian vault, ButlerBrain chunks, embeds, and stores the content in your private vector store. When you search, it returns semantically relevant results — not just keyword matches.

Your MCP Endpoint

Every ButlerBrain account gets a unique MCP endpoint. Find your brain_name and API key in your Dashboard → Settings.

https://api.butlerbrain.ai/v1/{brain_name}/mcp

Authenticate all requests with the x-api-key header:

x-api-key: your_api_key_here

Available MCP Tools

Your ButlerBrain endpoint exposes 10 MCP tools to any connected AI assistant:

API Reference

Building directly against ButlerBrain from your own code or a no-code tool like Bubble? Every operation is available over a simple HTTP API authenticated with your x-api-key header. The full reference covers the base URL, authentication, each operation with request and response examples, rate limits, and error shapes.

ChatGPT

ChatGPT connects to ButlerBrain via OAuth 2.1 — no API key configuration required. The recommended path is the ChatGPT Plugin Directory: ButlerBrain is listed there and installs in one click. Developer Mode remains available as a manual fallback.

https://api.butlerbrain.ai/v1/{your-brain-name}/mcp

Connect Codex CLI

OpenAI's Codex CLI supports MCP servers over streamable HTTP. You can authenticate either via OAuth (recommended) or with an API key in a custom header.

Method 1 (recommended): OAuth

OAuth is the same flow ChatGPT Plugin Directory users follow — the most secure path. Credentials auto-refresh and are shared between Codex CLI and the Codex VS Code extension.

codex mcp add butlerbrain --http https://api.butlerbrain.ai/v1/<your-tenant-name>/mcp

codex mcp login butlerbrain

codex mcp list

Method 2: API Key

Prefer a long-lived key over a browser login? Configure Codex to read your API key from an environment variable.

export BUTLERBRAIN_API_KEY='<your-api-key>'

[mcp_servers.butlerbrain]
url = "https://api.butlerbrain.ai/v1/<your-tenant-name>/mcp"

[mcp_servers.butlerbrain.http_headers_env_vars]
x-api-key = "BUTLERBRAIN_API_KEY"

codex mcp list

Verify the tools are available

Once installed, run /mcp inside any Codex session — you should see butlerbrain listed with 10 tools available:

Connect the Codex Desktop App

The Codex desktop app connects to ButlerBrain as an MCP server over streamable HTTP. Add the server once, then click Authenticate to sign in. No API key setup required.

https://api.butlerbrain.ai/v1/{your-brain-name}/mcp

Anthropic Connectors DirectoryComing Soon

ButlerBrain has been submitted to the Anthropic Connectors Directory and is pending approval. Once approved, you'll be able to add it in one click from Claude.ai — no manual URL setup, working on every Claude plan including Free. Until then, use the custom connector setup below.

Connect Claude.ai

Claude.ai connects to ButlerBrain via OAuth 2.1 — no API key configuration required. Once connected, Claude can search your brain, save thoughts, manage calendar events, and more, directly from any conversation.

Connect Claude.ai

https://api.butlerbrain.ai/v1/{your-brain-name}/mcp

Available Tools

Once connected, Claude.ai has access to all 10 ButlerBrain tools:

Connect Claude Code

Claude Code supports HTTP MCP servers natively. Adding ButlerBrain takes about 30 seconds.

claude mcp add butlerbrain \
  -t http \
  -e API_KEY=<your-api-key> \
  -- https://api.butlerbrain.ai/v1/<your-tenant-name>/mcp

claude mcp list

"Search my brain for the deployment guide"
"Save a thought: deployed v2.0 to production today"
"What do I know about the Stripe integration?"

Connect Cursor

Cursor supports MCP servers via an mcp.json config file. ButlerBrain is available across all your Cursor projects (global config) or just one project (per-project config).

{
  "mcpServers": {
    "butlerbrain": {
      "url": "https://api.butlerbrain.ai/v1/<your-brain-name>/mcp",
      "headers": {
        "x-api-key": "<API_KEY>"
      }
    }
  }
}

"Search my brain for the architecture notes"
"Save a thought: refactored auth module to use JWT"
"What meetings do I have this week?"

Connect VS Code (GitHub Copilot)

VS Code talks to MCP servers through GitHub Copilot Chat in Agent mode. Drop a config into .vscode/mcp.json and Copilot picks it up.

{
  "servers": {
    "butlerbrain": {
      "type": "http",
      "url": "https://api.butlerbrain.ai/v1/<your-brain-name>/mcp",
      "headers": {
        "x-api-key": "<API_KEY>"
      }
    }
  }
}

"Search my brain for last week's deploy notes"
"Save a thought: TODO refactor the cache layer"

"mcp": {
  "servers": {
    "butlerbrain": {
      "type": "http",
      "url": "https://api.butlerbrain.ai/v1/<your-brain-name>/mcp",
      "headers": {
        "x-api-key": "<API_KEY>"
      }
    }
  }
}

Connect Windsurf

Windsurf's Cascade panel speaks MCP. Add ButlerBrain either through the in-app MCP settings UI or by editing mcp_config.json directly.

{
  "mcpServers": {
    "butlerbrain": {
      "serverUrl": "https://api.butlerbrain.ai/v1/<your-brain-name>/mcp",
      "headers": {
        "x-api-key": "<API_KEY>"
      }
    }
  }
}

"Search my brain for the API spec"
"Save a thought: switched to streaming responses"

Connect Goose

Goose (by Block) calls MCP servers remote extensions. Add ButlerBrain via the interactive goose configure wizard, or by editing ~/.config/goose/config.yaml.

Method 1 (recommended): goose configure

goose configure

"What ButlerBrain tools do you have?"

Method 2: edit config.yaml directly

Add this block to ~/.config/goose/config.yaml under extensions:

extensions:
  butlerbrain:
    type: streamable_http
    enabled: true
    uri: https://api.butlerbrain.ai/v1/<your-brain-name>/mcp
    headers:
      x-api-key: <API_KEY>
    timeout: 300

For Goose builds that only support legacy SSE, use type: sse instead. Both work against the same ButlerBrain endpoint.

Connect PerplexityPro / Max / Enterprise

Perplexity supports custom remote MCP connectors on its paid plans (Pro, Max, Enterprise). The free plan can't add custom connectors today.

"@ButlerBrain what do I know about Stripe webhooks?"

Connect via OpenClaw

OpenClaw is an open-source AI gateway that connects messaging platforms (Discord, Signal, Telegram, WhatsApp) to AI backends. ButlerBrain integrates as an MCP tool provider via curl-based SKILL commands.

See the OpenClaw documentation for installation instructions.

curl -s https://api.butlerbrain.ai/v1/{brain_name}/mcp \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "search_brain",
      "arguments": {
        "query": "your search query",
        "owner": "your_name"
      }
    }
  }'

openclaw skill install butlerbrain

Sync Your Obsidian Vault

ButlerBrain syncs with Obsidian via the Remotely Save plugin, storing your vault notes as searchable semantic memory. Every note you write in Obsidian becomes retrievable by any connected AI tool.

Import your ChatGPT and Claude history

Bring your existing AI conversations into your brain so everything you have already worked through is searchable alongside everything new. ButlerBrain imports history from both ChatGPT and Claude.

Pick the path that fits

Bulk import, bringing your full export or a batch of chat files in one upload, is included on every paid plan (Starter and up). Capture as you go, telling your connected assistant to save the key points, is available on every plan including the free trial.

Step 1: Export your data

From ChatGPT

Settings → Data controls → Export data, then confirm. You will get an email with a link to download a ZIP. The export can take anywhere from a few minutes to a few hours depending on how much history you have, and the email arrives when it is ready. Note that ChatGPT's saved Memory is stored separately and is not part of the export. You get your conversations.

From Claude

Settings → Privacy → Export data, then confirm. You will get an email with a download link. Claude lets you bound the export by time range, all history or the last 30 or 90 days or a custom window, so you can bring in only recent conversations if you prefer.

Step 2: Import into your brain

Open the Import tab in your dashboard. Upload the export ZIP, or drop in markdown files directly if you exported or summarized individual chats. Set the owner the notes belong to, this is a member of your brain and has nothing to do with your ChatGPT or Claude login, then confirm the notice and import.

Imported conversations are shared with your brain by default, owned by the member you chose. In a brain with more than one member, the others can search them too, the same as your synced vault notes. In a solo brain this changes nothing.

Already have markdown?

If your chats are already markdown files, there is nothing to convert. Upload them straight to the Import tab, or drop them into your synced vault if you use one.

Before you import: what is in your export

Keeping your brain current

Importing covers your past. For everything new, connect your brain to ChatGPT or Claude and just ask: save the key points of this to my brain, or summarize this conversation to a markdown file and save it. That keeps your brain current without exporting anything.

Identifying yourself when sharing a brain

ButlerBrain supports multiple people sharing the same brain — useful for families, teams, or any group with shared context. When more than one person uses the same brain, identifying yourself helps ButlerBrain attribute your saves and searches correctly.

In Claude, Claude.ai, Claude Code, or ChatGPT, just mention your name at the start of a conversation, or when you're saving or searching. For example:

With your name in hand, ButlerBrain can:

• Tag saved items with the right owner.
• Filter shared and private items correctly across the brain.
• Keep your private notes private to you, while still surfacing shared family or team content for everyone.

Items saved without an explicit owner are accessible to anyone with brain access, so naming yourself is the easy way to take advantage of per-person privacy features.

Over time the same person can end up saved under more than one name, for example a first name in one place and a full name in another. The account owner can tie those names together on the dashboard Members tab by confirming them as one identity. Once confirmed, that person's content is treated as one identity and their private items become visible to them under every confirmed name. Shared content is never affected, nothing you saved is moved or rewritten, and a confirmation can be undone at any time.

Only confirm names that truly belong to the same person, since confirming unlocks that person's private items across all of their confirmed names.

Ready to give your AI a memory?

Create your account and connect your first AI tool in under two minutes.

Get Started FreeGo to Dashboard