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.

OAuth for desktop MCP (OBS-105)

See MCP OAuth for Passport authorization, dynamic client registration, and org-scoped scopes.

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