MCP setup (technical)

For step-by-step help connecting Claude, ChatGPT, Gemini, or other chat apps without editing config files, start with Connect your AI app.

This page is for developers and power users wiring MCP manually.

OpenBrain exposes an MCP server at /mcp with snake_case tool names (memory_ingest, memory_search, …).

1. Create an API key

1. Sign in at /app and complete onboarding if prompted.
2. Open API Keys for your organization.
3. Create a token with Ingest and Search (add Admin for update/delete tools).

Copy the token when shown — it is only displayed once.

2. MCP server configuration

Add a server entry in your MCP host’s configuration (JSON or UI). Replace the host, token, and organization UUID:

{
  "mcpServers": {
    "openbrain": {
      "url": "https://YOUR_OPENBRAIN_HOST/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Organization-Id": "YOUR_ORGANIZATION_UUID"
      }
    }
  }
}

Use http://localhost/mcp only for local Sail development.

3. Verify

Call the openbrain_health tool or GET /health/ready to confirm Postgres and embeddings are available.

Authentication

Use a Sanctum personal access token (API key) as Authorization: Bearer. MCP OAuth is unsupported.

Send X-Organization-Id when your host supports custom headers. MCP honors that header and it must match the token’s organization:{uuid} ability.

memory_upsert and memory_ingest_batch require Ingest (memory:ingest). Search-only keys can read but cannot write.

When billing is enforced, unpaid organizations can still search and read stored memories; ingest, upsert, batch, update, and delete return a tool error carrying the same denial as REST 402. If enforcement is on while STRIPE_SECRET is missing, write tools fail closed with the 503 denial instead. Exhausting a monthly cap returns the 429 quota_exceeded denial. See Billing and usage.

Structured tool results (OB-038)

Memory tools return structured JSON via MCP structuredContent (search scores and meta, ingest outcome/dedupe, health ready/checks). A JSON text body is still included for hosts that only read text content.

Tool reference

Generated pages live under MCP tools. Regenerate with:

php artisan openbrain:docs-mcp
php artisan openbrain:docs-api   # OpenAPI → developer-docs/public/openapi.yaml