MCP server setup

The Beakr MCP server connects your knowledge base to Claude Code, Codex, Cursor, and any AI assistant that supports the Model Context Protocol.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external data sources and tools. The Beakr MCP server exposes 25 tools that give your AI assistant direct access to your knowledge base, plus a system prompt that frames Beakr as your team's organizational memory and instructs the agent to propose captures when the conversation surfaces durable information.

Recommended: beakr setup

If you used the one-line installer or ran beakr setup, the MCP server is already registered in whichever clients were detected. No further configuration needed.

# Re-run setup any time to register, repair, or update
beakr setup
beakr setup --client claude          # only Claude Code
beakr setup --client codex           # only Codex
beakr setup --force                  # overwrite existing registration
beakr setup --scope project          # write Claude .mcp.json into the current project

beakr setup prefers the official client CLIs (claude mcp add, codex mcp add) and falls back to writing config files directly when those CLIs aren't on PATH.

Get your API key

You need a Beakr API key. Go to thebeakr.com > Settings > API Keys tab > Create API Key. The key starts with bk_live_ and is shown only once.

beakr setup prompts for the key and saves it to ~/.beakr/config.json. If you already have one configured, the prompt asks whether to use the existing key or enter a new one.

Manual registration

Claude Code — user scope

Use the claude CLI (this is what beakr setup calls):

claude mcp add beakr --scope user -- beakr mcp

Or write to ~/.claude.json by hand:

{
  "mcpServers": {
    "beakr": {
      "command": "beakr",
      "args": ["mcp"]
    }
  }
}

Claude Code — project scope (shared with teammates)

claude mcp add beakr --scope project -- beakr mcp

This writes .mcp.json in your project root — designed to be committed so teammates inherit the registration when they open the project.

Codex

Codex MCP registrations live in ~/.codex/config.toml.

codex mcp add beakr -- beakr mcp

Or by hand:

[mcp_servers.beakr]
command = "beakr"
args = ["mcp"]

Codex does not have a project-scope MCP concept — its config is always user-wide.

Cursor

In Cursor, go to Settings > MCP Servers and add a new server with the same configuration:

Local development

For local development against a running Beakr API:

{
  "mcpServers": {
    "beakr": {
      "command": "beakr",
      "args": ["mcp"],
      "env": {
        "BEAKR_API_URL": "http://localhost:8000",
        "BEAKR_DEV_IDENTITY": "seed_sarah",
        "BEAKR_DEV_EMAIL": "sarah.chen@example.com",
        "BEAKR_DEV_DISPLAY_NAME": "Sarah Chen"
      }
    }
  }
}

Custom config directories

Two environment variables let you point at non-default config directories — useful for running multiple accounts side-by-side:

Verify

After configuring, your AI assistant should list beakr as a connected MCP server (run /mcp in Claude Code). Test with:

# In Claude Code or Cursor, ask:
"Use the beakr research tool to tell me about recent decisions"