certainlogic-mcp 0.4.0

Community cache & private AI for your IDE agent. Plugs into Cursor, Claude Code, VS Code, JetBrains.

CertainLogic Brain MCP

Community cache & private AI for developers on the FIAS gig economy.

Plug into Cursor, Claude Code, VS Code, or JetBrains. Every cached query makes AI cheaper for everyone. Pro tier gives you your own private memory and audit trail.

---

🔥 OpenRouter 30% Off — Wrapped In

Every cache miss routes through OpenRouter with 30% off the standard model rate. Brain MCP negotiates it automatically — you don't need a coupon or enterprise deal. Cache hits are free anyway.

This is the hook: Your agent gets cheaper on every uncached query. Cache hits are free. Win-win.

---

Quick Install (5 minutes)

1. Install the package

pip install certainlogic-mcp

PyPI package is ready. No npm needed — Python projects install via pip.

Or install from source:

git clone https://github.com/CertainLogicAI/certainlogic-mcp.git
cd certainlogic-mcp
pip install -e .

2. Set your API key

Brain MCP routes cache misses through OpenRouter. You need an API key.

export OPENROUTER_API_KEY="sk-or-..."

Don't have one? Get a free OpenRouter key (takes 30 seconds). Free models are available — you pay only if you need faster ones.

3. Run the setup wizard

python3 -m certainlogic_mcp.server setup

Or if the shortcut is installed:

certainlogic-mcp setup

This writes your editor's MCP config automatically.

4. Restart your editor

Cursor, VS Code, and JetBrains auto-detect MCP servers on restart. Claude Code detects it on next claude command.

5. Done

Your agent now routes through Brain MCP. Every query checks the community cache first. Cache hit → instant, zero cost. Cache miss → routes to cheapest model, stores for next time.

---

Manual Config (if the wizard doesn't work)

Your editor reads mcp.json from its config directory. Here's what to add:

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "certainlogic-mcp": {
      "command": "python3",
      "args": ["-m", "certainlogic_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "certainlogic-mcp": {
      "command": "python3",
      "args": ["-m", "certainlogic_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Claude Code

Add to ~/.claude/servers.json:

{
  "mcpServers": {
    "certainlogic-mcp": {
      "command": "python3",
      "args": ["-m", "certainlogic_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

JetBrains

Go to Settings → Tools → MCP Server, add a new server:

• Name: certainlogic-mcp
• Command: python3 -m certainlogic_mcp.server
• Environment variables: OPENROUTER_API_KEY=sk-or-...

---

What You Get

Free Tier (Community Cache)

Everyone shares a community cache. When you ask a question, the cache checks if someone already asked it. If yes → instant response, zero cost. If no → routes to a model, stores the result, everyone benefits next time.

Tool	What It Does
cache_query	Check community cache. Miss → route to model → store.
cache_stats	See how many tokens the community saved.

Pro Tier ($49/mo — Private AI)

Your own private cache and full Brain OS memory. Nothing shared. Ever.

Tool	What It Does
private_query	Personal cache. Your queries never leave your control.
brain_search	Search your persistent knowledge graph across sessions.
brain_get	Retrieve any fact or page from memory.
brain_stats	Memory usage, facts stored, cache performance.

---

Pro License

Get a license key:

certainlogic-mcp setup --key YOUR_LICENSE_KEY

Or set the environment variable:

export BRAIN_MCP_LICENSE="YOUR_LICENSE_KEY"

The server validates the key and unlocks Pro tools automatically.

Need a key? Email [e-mail] or open an issue on GitHub.

---

Running the License Server (Self-Hosted)

If you want to run your own license validation server:

python3 -m certainlogic_mcp.license_server

Default port: 8899. Configure with:

export LICENSE_PORT=8899
export BRAIN_MCP_LICENSE_SERVER="http://your-server:8899"

---

Cache Location

By default, the cache lives at /tmp/brain-mcp-cache/. Change it:

export BRAIN_MCP_CACHE_DIR="$HOME/.brain-mcp-cache"

• Free tier: community.db (shared, anonymized)
• Pro tier: personal_YOURHASH16.db (isolated per license)

---

Docker

Run the full stack with Docker Compose:

# Clone the repo
git clone https://github.com/CertainLogicAI/certainlogic-mcp.git
cd certainlogic-mcp

# Start MCP server + license server
docker compose up

# Or build and run individually:
docker build -t certainlogic/mcp-server .
docker build -f Dockerfile.license -t certainlogic/license-server .

docker run -d --name license-server -p 8899:8899 certainlogic/license-server
docker run -it --rm --name mcp-server \
  -e BRAIN_MCP_LICENSE_SERVER=http://license-server:8899 \
  -e OPENROUTER_API_KEY=sk-or-... \
  certainlogic/mcp-server

Architecture

Your IDE (Cursor/VS Code/etc)
       │
       │ MCP protocol (stdio)
       ▼
Brain MCP Server
       │
       ├── Cache check (SQLite)
       │     ├── Hit → return instantly
       │     └── Miss → route to model
       │
       ├── OpenRouter (free/paid models)
       │
       └── [Pro tier] Brain OS API (port 8000)
             ├── Knowledge graph search
             ├── Fact retrieval
             └── Persistent memory

---

Troubleshooting

"mcp: command not found" or "certainlogic-mcp not found"

Make sure the package is installed:

pip install certainlogic-mcp
python3 -m certainlogic_mcp.server --help

"Cache miss is slow"

First query to a new topic takes 5-30 seconds depending on the model. Every subsequent identical query is instant.

"OpenRouter API key not set"

export OPENROUTER_API_KEY="sk-or-..."

Or add it to your editor's MCP config env vars.

Server won't start

Check the logs:

python3 -m certainlogic_mcp.server 2>&1

---

Links

• Website: certainlogic.ai/mcp
• GitHub: github.com/CertainLogicAI/certainlogic-mcp
• X: @CertainLogicAI
• Email: [e-mail]