ProductBrain

The single source of truth for product knowledge — glossary, business rules, tensions, decisions, labels, and relations — accessible as an MCP server in Claude Desktop, Cursor, and any MCP-compatible AI assistant.

ProductBrain connects your AI assistant to your team's knowledge base. Ask questions, capture decisions, and build a living knowledge graph without leaving your editor.

Quick Start (Cloud)

Option A: Guided setup (recommended)

npx @productbrain/mcp setup

This opens SynergyOS → Settings → API Keys, prompts you to paste your key, and writes the config for Cursor or Claude Desktop.

Option B: Manual config

1. Get your API key

Go to SynergyOS → Settings → API Keys and click Generate Key. Copy the pb_sk_... key.

2. Configure your AI assistant

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain/mcp"],
      "env": {
        "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here"
      }
    }
  }
}

Cursor — edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain/mcp"],
      "env": {
        "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here"
      }
    }
  }
}

3. Restart your assistant and verify

Ask:

"Use the health tool to check ProductBrain connectivity"

You should see your workspace ID, collection count, and latency.

Related MCP server: @cogniahq/mcp

Self-Hosted Setup

If you're running your own Convex deployment, use the three-variable config:

{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain/mcp"],
      "env": {
        "CONVEX_SITE_URL": "https://your-deployment.convex.site",
        "MCP_API_KEY": "your-shared-api-key",
        "WORKSPACE_SLUG": "your-workspace-slug"
      }
    }
  }
}

Dev vs Production

Set PRODUCTBRAIN_URL to switch between environments:

{
  "env": {
    "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here",
    "PRODUCTBRAIN_URL": "http://localhost:3210"
  }
}

Omit PRODUCTBRAIN_URL to default to production.

What You Can Do

Search and explore

• "Search the glossary for 'tension'"

• "List all business rules in the Governance domain"

• "What is the canonical definition of 'supplier'?"

Capture knowledge

• "Capture a tension: our MCP entry creation takes too many steps"

• "Draft a decision record for choosing Convex over Supabase"

• "Create a business rule about API key rotation"

Navigate the knowledge graph

• "Gather full context around FEAT-001"

• "What entries are related to GT-019?"

• "Suggest links for this new tension"

Check quality

• "Run a quality check on TEN-graph-db"

• "Review business rules for the AI & MCP Integration domain"

• "Verify the glossary against the codebase"

Tools (20+)

Resources

Prompts

Security

• Your data stays yours. The MCP server connects only to your authenticated Convex deployment. No data is shared with third parties.

• API key handling. Cloud keys (pb_sk_...) are SHA-256 hashed before storage. Only the prefix is persisted for display. Keys are sent as Bearer tokens over HTTPS.

• Workspace scoping. Each API key is bound to a single workspace. No cross-workspace access is possible.

Troubleshooting

"Missing API key" or "Invalid API key"

Your PRODUCTBRAIN_API_KEY is missing or incorrect. Generate a new key from SynergyOS Settings → API Keys.

"CONVEX_SITE_URL environment variable is required"

You're using self-hosted mode but missing the env block. Make sure all three variables are set.

"Workspace not found"

For self-hosted: check your WORKSPACE_SLUG. For cloud: your API key may have been revoked.

"MCP call network error"

The backend is unreachable. If using PRODUCTBRAIN_URL, verify the URL is correct and the server is running.

Server doesn't appear in Claude Desktop / Cursor

Restart the application after editing the config file. In Cursor, check the MCP panel (Cmd+Shift+P → "MCP: Show Panel") for startup errors.

Enable debug logging

Set MCP_DEBUG=1 in your config's env block to see audit logs in stderr.

Development

# Clone and install
git clone https://github.com/synergyai-os/productbrain.git
cd productbrain
# Or install: npm install @productbrain/mcp
npm install

# Copy env template and fill in your values
cp .env.mcp.example .env.mcp

# Run in dev mode (TypeScript, hot reload)
npm run dev

# Build for production
npm run build

# Run the built version
npm start

# Typecheck
npm run typecheck

# Publish beta
npm run publish:beta
# (Maintainers: set SYNERGYOS_POSTHOG_KEY=phc_... for usage tracking)

License

MIT