Brief MCP Setup Guide

Why Connect Brief to Your AI Coding Assistant?

Brief MCP transforms your AI coding assistant from a code generator into a strategic partner. Instead of AI tools that only understand syntax, you get AI that understands your customers, remembers past decisions, and knows your product strategy.

Setup takes 2 minutes and works with Cursor, Claude Code, Claude Desktop, Windsurf, VS Code, and any MCP-compatible tool.

What is Brief MCP?

Brief's Model Context Protocol (MCP) integration connects your AI coding assistant to your product context. When you're coding in Cursor, Claude Code, Windsurf, or other MCP-compatible tools, you can ask questions and make decisions that automatically sync with Brief.

What You Get

• Search documents and decisions without leaving your IDE
• Record technical decisions as you make them
• Access personas and features when designing UX
• Validate your approach against past decisions before implementing

Think of it as giving your AI coding assistant a direct line to your product brain.

Quick Start: OAuth (Recommended)

The easiest way to connect Brief is via OAuth authentication using the mcp-remote package. This method:

• ✅ No API key to copy/paste
• ✅ Automatic token refresh
• ✅ Works with any MCP client
• ✅ Browser-based authentication

Claude Code

claude mcp add --transport http brief https://app.briefhq.ai/mcp

Then run /mcp inside Claude Code to authenticate. Verify with claude mcp list.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "brief": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.briefhq.ai/api/mcp/sse"]
    }
  }
}

Restart Claude Desktop. A browser window opens for authentication on first use.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "brief": {
      "type": "sse",
      "url": "https://app.briefhq.ai/api/mcp/sse"
    }
  }
}

When Cursor connects, a browser window opens for authentication.

Windsurf

Add to your Windsurf MCP config (Settings → Cascade → MCP Servers → Add custom server):

{
  "mcpServers": {
    "brief": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.briefhq.ai/api/mcp/sse"]
    }
  }
}

Codex CLI

codex mcp add brief --url https://app.briefhq.ai/mcp

Then run codex mcp login brief to authenticate.

[features]
experimental_use_rmcp_client = true

Never commit your API key to version control.

npx -y @briefhq/mcp-server@latest configure

This stores your API key securely in your system keychain.

Step 3: Add to Your Client

Use this configuration for any MCP client:

{
  "mcpServers": {
    "brief": {
      "command": "npx",
      "args": ["-y", "@briefhq/mcp-server@latest", "serve"]
    }
  }
}

This runs the Brief MCP server locally using your stored API key.

Migrating from CLI/API Key to OAuth

If you previously set up Brief using the CLI installer (npx @briefhq/mcp-server@latest init), you can migrate to OAuth:

Claude Code

claude mcp remove brief
claude mcp add --transport http brief https://app.briefhq.ai/mcp

Cursor

Replace your old configuration with native SSE:

{
  "mcpServers": {
    "brief": {
      "type": "sse",
      "url": "https://app.briefhq.ai/api/mcp/sse"
    }
  }
}

Claude Desktop, Windsurf, VS Code

Replace your old configuration with mcp-remote:

{
  "mcpServers": {
    "brief": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.briefhq.ai/api/mcp/sse"]
    }
  }
}

Restart your client and authenticate when prompted.

Codex CLI

codex mcp add brief --url https://app.briefhq.ai/mcp
codex mcp login brief

Benefits of OAuth Migration

• No key management — No need to generate, copy, or rotate API keys
• Automatic refresh — Tokens refresh automatically, no disconnections
• Faster setup — One command instead of multiple steps
• More secure — Short-lived tokens instead of long-lived API keys

Available Tools

The Brief MCP server provides these tools:

Using Brief in Your IDE

Example 1: Check for Past Decisions

You:

"I'm about to implement authentication. Are there any existing decisions about this?"

AI:

Searches Brief "Yes, we decided to use Clerk for authentication (Decision BRI-42, logged 2 weeks ago). The rationale was to avoid building auth from scratch and get SSO support out of the box."

Example 2: Record a New Decision

You:

"We're using Postgres instead of MongoDB for the new API because of our relational data needs."

AI:

Records decision to Brief "I've logged that decision to Brief as BRI-89. Would you like to add any additional tags or link it to a feature?"

Example 3: Get User Personas

You:

"Who are we building this feature for? What do they care about?"

AI:

Fetches personas from Brief "You have 3 personas: 1. Product Founders (Primary) — Care about velocity, need strategic clarity 2. Solo Makers — Want simplicity, low maintenance 3. Small Teams — Need collaboration, shared context"

Example 4: Validate Your Approach

You:

"I'm planning to refactor the API to use GraphQL. Does this conflict with anything?"

AI:

Runs guard_approach "⚠️ Potential conflict: We decided to stick with REST for simplicity (BRI-56, 3 months ago). Should we revisit that decision or keep the current approach?"

Troubleshooting

"Connection failed" or "Internal server error"

Clear saved OAuth credentials and try again:

rm -rf ~/.mcp-auth

Then restart your MCP client and re-authenticate.

"401 Unauthorized"

• OAuth users: Clear auth cache with rm -rf ~/.mcp-auth and re-authenticate
• API key users: Verify your key at Brief → Settings → Integrations

MCP not showing up in your client

- Cursor: ~/.cursor/mcp.json - Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json - Windsurf: Settings → Cascade → MCP Servers - Codex: ~/.codex/config.toml - Claude Code: ~/.claude.json

1. Verify the config file location:

1. Check JSON/TOML syntax is valid
2. Restart your client

"Tools not found" or AI doesn't respond

The MCP server needs to initialize. Restart your IDE/client after configuring.

Verify Your Setup

Claude Code:

claude mcp list

Look for brief ✔ connected.

Cursor: Go to Settings → Features → MCP Servers. Status should be green.

Test a query: Ask your AI: "Search Brief for recent decisions" — if it works, you're connected.

What's Next?

Now that Brief is connected to your IDE:

1. Try the example workflows above to get comfortable
2. Let your AI guide you — it will proactively suggest using Brief
3. Record decisions as you go — don't wait until later
4. Search before implementing — avoid redoing solved problems

For more on using Brief effectively, see:

• Tips for Better Answers
• Example Prompts