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.

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"
      }
    }
  }
}

Variable	Where to find it
CONVEX_SITE_URL	Convex dashboard → Settings → URL (use *.convex.site, not *.convex.cloud)
MCP_API_KEY	Must match the MCP_API_KEY env var in your Convex deployment
WORKSPACE_SLUG	Your workspace slug from the SynergyOS URL

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+)

Tool	What it does
health	Verify connectivity and get workspace stats
kb-search	Full-text search across all knowledge entries
list-collections	Browse all collection schemas
list-entries	Browse entries with optional filters
get-entry	Full record with data, labels, relations, history
smart-capture	One-call entry creation with auto-linking and quality scoring
create-entry	Create with full field control
update-entry	Partial update (merges with existing data)
gather-context	Multi-hop graph traversal around an entry
suggest-links	Discover potential connections
relate-entries	Create typed relations between entries
find-related	List direct relations for an entry
quality-check	Score an entry against collection-specific criteria
review-rules	Surface business rules for a domain
verify	Check knowledge entries against the actual codebase
list-labels	Browse workspace labels
manage-labels	Create, update, or delete labels
label-entry	Apply or remove labels from entries
quick-capture	Minimal-ceremony entry creation
mcp-audit	Session audit log with call statistics

Resources

URI	Content
productbrain://orientation	System map: architecture, data model, rules, analytics
productbrain://terminology	Glossary + standards summary
productbrain://collections	All collection schemas with field definitions
productbrain://{slug}/entries	All entries in a given collection
productbrain://labels	Workspace labels with hierarchy

Prompts

Prompt	Purpose
review-against-rules	Structured compliance review against business rules
name-check	Check variable/field names against the glossary
draft-decision-record	Draft a decision record from context
draft-rule-from-context	Draft a business rule from an observation

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