Open BurnBar
GitHub Download
MCP integration · protocol-native

Codex forgets.
Claude forgets. Your history doesn't.

Thirty-four unique MCP tools point any agent that speaks the protocol — Codex, Claude Code, Cursor, Droid, Kimi, Forge, Hermes — at your full OpenBurnBar record. Free locally over SQLite. Encrypted in the cloud for Pro. Never plaintext on the server.

ENDPOINT · MCP/STREAMABLE-HTTP · 2025-11-25 LIVE
https://mcp.burnbar.ai/mcp
audience-bound · HMAC bearer · burnbar_pro entitlement since 2026-05-15
See install snippets Read the architecture doc Threat model
Three channels

Same tools. Three install paths. Pick the one your client speaks.

The local stdio server is free and reads your SQLite directly. The hosted Remote MCP is a BurnBar Pro feature with encrypted, multi-device session memory. The stdio shim closes the gap for clients that don't yet speak Streamable HTTP — and is the only path that decrypts hosted bodies on-device.

  1. 01 Free · local

    Local stdio MCP

    runtime
    Python 3 · mcp 1.27.0
    transport
    stdio
    auth
    Local filesystem (your user)
    audience
    Anyone running OpenBurnBar — no account
    source
    ~/Library/Application Support/OpenBurnBar/openburnbar.sqlite
    tools
    26
    • FTS5 + local deterministic semantic search over your transcripts
    • BurnBar Resume can port prior conversations across harnesses
    • Token-usage ledger writer is daemon-first, idempotent, falls back to JSONL
    • Bundles a Hermes operator skill, auto-symlinked at install time
  2. 02 BurnBar Pro · hosted

    Hosted Remote MCP

    runtime
    Cloud Run · Node 22 · 2025-11-25 spec
    transport
    Streamable HTTP
    auth
    Short-lived HMAC bearer (audience-bound)
    audience
    BurnBar Pro subscribers, any device
    source
    https://mcp.burnbar.ai/mcp
    tools
    8
    • Search hits opaque token/semantic hashes — zero Storage reads
    • Bodies and resume briefings decrypt on-device by default (local_decrypt_shim)
    • Per-client grant revoke from the OpenBurnBar app's Cloud Store
  3. 03 Bridge · stdio shim

    openburnbar-mcp-remote

    runtime
    Node 22 · zero runtime deps
    transport
    stdio ⇄ HTTPS
    auth
    macOS Keychain → 0600 file → env var
    audience
    Codex · Claude Code · Droid · Kimi · Forge
    source
    → https://mcp.burnbar.ai/mcp
    tools
    8
    • Bridges stdio-only clients to the hosted endpoint
    • Performs the on-device decrypt that keeps privacy mode honest
    • Adds openburnbar resume for print/copy/open handoff flows
    • openburnbar mcp doctor proves the whole chain in one command
Tool dossier

Thirty-four unique tools. Read-by-default. Writes stay gated by the daemon.

Every tool is declared with a scope, a cost class, a rate-limit bucket, and an input schema. Names below are exact — copy them into a tools/call payload.

Hosted · mcp.burnbar.ai 8 tools
  • burnbar_search_conversations
    search:read cost · standard

    Search encrypted OpenBurnBar hosted session memory. Sealed results require the local shim for decrypted previews.

  • burnbar_get_conversation_body
    conversation:read cost · body

    Fetch one encrypted session body page for a resource returned by search.

  • burnbar_list_search_index_status
    index:status cost · metadata

    Return encrypted search index freshness, counts, active commits, and stale-state warnings.

  • burnbar_list_search_facets
    search:read cost · metadata

    List bounded provider / model / project / harness facets for narrowing hosted search.

  • burnbar_recent_usage
    usage:read cost · metadata

    Read recent provider / model usage metadata without provider credentials.

  • burnbar_list_resumable_conversations
    index:status cost · metadata

    List recent encrypted hosted sessions eligible for resume.

  • burnbar_resume_conversation
    conversation:read cost · body

    Compose a sealed resume plan. The local shim decrypts and renders on device.

  • burnbar_resolve_capabilities
    index:status cost · metadata

    Describe the current user's hosted MCP availability, decrypt mode, scopes, and limits.

Local · openburnbar.sqlite 26 tools
  • burnbar_resolve_db_path
    read cost · metadata

    Show which DB file is in use.

  • burnbar_list_providers
    read cost · metadata

    Distinct provider values — Codex, Claude Code, Cursor, Hermes, etc.

  • burnbar_search_conversations
    read cost · standard

    FTS5 search over conversation titles and full transcripts.

  • burnbar_semantic_search_conversations
    read cost · standard

    Local deterministic semantic search over indexed conversation chunks. Returns structured unavailable when the local semantic index is absent.

  • burnbar_cloud_semantic_search_conversations
    read · opt-in cost · standard

    Hosted encrypted semantic search; query hashes derived locally, snippets decrypt locally.

  • burnbar_cloud_get_conversation_body
    read · opt-in cost · body

    Decrypt the full hosted session body for a cloud search hit.

  • burnbar_list_project_memory
    read cost · metadata

    List project memory snapshots with source counts and freshness.

  • burnbar_get_project_memory
    read cost · body

    Read one project memory snapshot by slug.

  • burnbar_cloud_sync_project_memory
    read · opt-in cost · body

    Sync a local project memory snapshot through the encrypted cloud path.

  • burnbar_get_conversation
    read cost · body

    Full row plus fullText for one conversation by ID (120k char default cap).

  • burnbar_recent_usage
    read cost · metadata

    Recent token_usage rows — cost, model, provider, session.

  • burnbar_project_summary
    read cost · metadata

    Per-project cost + session count aggregated over a rolling window.

  • burnbar_chat_messages
    read cost · metadata

    In-app assistant chat_messages tail.

  • burnbar_record_hermes_usage
    WRITE · daemon cost · standard

    Write an idempotent row to the OpenBurnBar daemon usage ledger. The only write tool.

  • burnbar_resolve_usage_ledger_path
    read cost · metadata

    Show the ledger path the writer will use.

  • burnbar_query_spend
    read cost · standard

    Query spend by provider, model, project, account, and time window.

  • burnbar_budget_status
    read cost · metadata

    Summarize active budget gates and current burn state.

  • burnbar_spend_forecast
    read cost · standard

    Forecast spend against configured budget limits.

  • burnbar_budget_audit
    read cost · metadata

    Read budget gate audit events for recent enforcement decisions.

  • burnbar_set_budget_limit
    WRITE · daemon cost · standard

    Set or update a daemon-backed budget limit.

  • burnbar_pause_budget_gate
    WRITE · daemon cost · standard

    Pause one budget gate until a specific ISO timestamp.

  • burnbar_resume_budget_gate
    WRITE · daemon cost · standard

    Resume a previously paused budget gate.

  • burnbar_org_spend
    read cost · standard

    Aggregate organization spend and usage over a bounded window.

  • burnbar_list_resumable_conversations
    read cost · metadata

    Return recent conversations eligible for native or ported resume.

  • burnbar_resume_conversation
    read cost · body

    Compose a native command hint or deterministic cross-harness briefing.

  • burnbar_spawn_resume
    process · opt-in cost · body

    Spawn the selected native or ported resume command after an explicit tool call.

Install

Drop into any client in under a minute.

The hosted path uses the openburnbar-mcp-remote stdio shim (or direct HTTP for clients that speak the 2025-11-25 spec). The local path is one shell script and a JSON snippet.

Hosted · mcp.burnbar.ai

requires BurnBar Pro · openburnbar mcp login <bearer>

~/.codex/config.toml — stdio shim, recommended 
                $ codex mcp add openburnbar -- openburnbar-mcp-remote mcp serve
# or paste this block into ~/.codex/config.toml

[mcp_servers.openburnbar]
command = "openburnbar-mcp-remote"
args = ["mcp", "serve"]
startup_timeout_sec = 15
tool_timeout_sec = 60

Local · SQLite, free, no account

tools/openburnbar-mcp · Python 3 venv

tools/openburnbar-mcp — one shell command 
                $ git clone https://github.com/Imagine-That-Ai/BurnBar
$ cd BurnBar/tools/openburnbar-mcp
$ ./setup.sh
→ creates venv, installs mcp + cryptography,
  symlinks the burnbar-operator skill into ~/.hermes/
Privacy mode · local_decrypt_shim

The hosted server never sees your queries or your bodies in the clear.

What the server sees
  • token_hashes[] — deterministic keyed digests (reveal which terms repeat and co-occur, not the terms)
  • semantic_hashes[] — deterministic keyed digests (reveal which terms repeat and co-occur, not the terms)
  • encrypted title / snippet / body-preview envelopes
  • provider · model · project · harness facets
  • audience-bound bearer (sub, scopes, exp, jti)
What the server NEVER sees
  • raw query text
  • plaintext titles, snippets, bodies
  • signed-URL markers or vault keys
  • provider credentials of any kind
  • Firebase ID tokens — those never become MCP bearers

Logs are structured + redacted. The token signing secret lives in Secret Manager and is injected via --set-secrets, never as a plaintext env var.

Production SLO

Live numbers from the 1,000-document corpus proof.

Captured on 2026-05-15 from Cloud Build against the branded endpoint — 20 iterations · 100 matching candidates · audited and reproducible.

  1. 263 ms
    search · p50
  2. 535 ms
    search · p95
  3. 286 ms
    body · p50
  4. 412 ms
    body · p95
  5. 0 reads
    storage during search
  6. 6 policies
    monitoring · alerting
verify it yourself · three commands 
$ curl -fsS https://mcp.burnbar.ai/readyz
{ "ok": true, "service": "openburnbar-hosted-mcp" }

$ curl -fsS https://mcp.burnbar.ai/.well-known/oauth-protected-resource
{ "resource": "https://mcp.burnbar.ai/mcp", ... }

$ openburnbar mcp doctor
PASS token · PASS endpoint 200 OK · PASS tools/list (8)
Cloud Store · Remote MCP

Connect, list, revoke — from inside the app.

The macOS app and the iPhone/iPad app both ship a Remote MCP card. It pulls the live remote_mcp_clients Firestore collection scoped to your user, shows the stdio shim and doctor commands, and lets you revoke any connected agent with one confirmation.

Revocation hits the revokeRemoteMcpClient callable; the next bearer-token refresh fails closed with 403 client_revoked. The signed-in flow was proved live on iPhone 17 Pro Max and iPad Pro 13" (M4) on 2026-05-15.

AgentLens/Views/Settings/CloudStoreSettingsView.swift · OpenBurnBarMobile/Views/Store/CloudStoreView.swift

Spec

MCP Streamable HTTP · protocolVersion 2025-11-25 · methods initialize, tools/list, tools/call, resources/list, resources/read.

Posture

Origin validated · oversized inputs bounded · missing bearer returns 401 with WWW-Authenticate · cross-tenant URI returns 404.

Auth

Short-lived HMAC bearer with aud=https://mcp.burnbar.ai/mcp. Every tool call re-checks scope + active client + active burnbar_pro entitlement + rate limit.

Pick a channel

Free, local, today — or hosted, encrypted, multi-device.

FREE · LOCAL · NO ACCOUNT

Run the local MCP in 30 seconds.

$ cd BurnBar/tools/openburnbar-mcp && ./setup.sh
$ /abs/path/.venv/bin/python /abs/path/server.py
View tools/openburnbar-mcp
BURNBAR PRO · HOSTED

Connect from the Cloud Store card in the app.

Subscribe inside OpenBurnBar, sign in, open Cloud Store → Remote MCP, then drop the generated config into your client. The endpoint, stdio shim, and doctor command are all right there.

See BurnBar Pro Download for macOS