Brief MCP Setup Guide

Why Connect Brief to Your AI Coding Assistant?

Brief MCP navigates your AI coding assistant to your product context. Instead of AI that's building blind, you get AI that's aligned with your decisions, customers, and strategy.

Without Brief MCP	With Brief MCP
AI is building blind	AI is aligned with your vision
Context resets every session	Context persists and compounds
Generic coding suggestions	Navigated to the right approach
No decision memory	Validates approach against past decisions

Setup takes 2 minutes and works with Cursor, Claude Code, VS Code, Claude Desktop, Codex, and any other MCP-compatible host that supports Streamable HTTP + OAuth.

---

What is Brief MCP?

Brief's Model Context Protocol (MCP) integration navigates your AI coding assistant to your product context. When you're coding in Cursor, Claude Code, VS Code, or other MCP-compatible tools, Brief keeps your AI aligned with your decisions automatically.

What You Get

• Navigate to 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 your Navigator that keeps every builder aligned.

---

How Brief MCP authenticates

Brief MCP is OAuth-first. Every client installation triggers a browser popup on first tool call — you sign in once, tokens refresh automatically, and there is no API key to copy or rotate.

• ✅ No API key management
• ✅ Automatic token refresh
• ✅ Per-org scoped tokens
• ✅ One canonical endpoint: https://app.briefhq.ai/mcp

The legacy mcp-remote wrapper and the /api/mcp/sse endpoint are no longer used. If an older guide (or an LLM from last year) tells you to set them up, that guide is stale.

---

Cursor

Fastest path: one-click install via the Cursor deep link from the Brief app. From Integrations → MCP → Install, click the "Add to Cursor" button.

Or add to ~/.cursor/mcp.json manually:

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

When Cursor connects, a browser window opens for OAuth. No API key required.

---

Claude Code

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

Then run /mcp inside Claude Code and pick brief to authenticate. Verify with:

claude mcp list

Look for brief ✔ connected.

---

VS Code

Extension (recommended)

Install the Brief extension from the VS Code Marketplace — it registers the MCP server automatically:

code --install-extension brief-hq.brief-vscode-extension

Or open Extensions (Ctrl/Cmd+Shift+X), search for Brief, and click Install. Then open Copilot Chat in Agent mode and run Brief: Sign In from the Command Palette.

Manual .vscode/mcp.json

If you prefer manual config (no extension), add this to .vscode/mcp.json in your project root:

{
  "servers": {
    "brief": {
      "url": "https://app.briefhq.ai/mcp",
      "type": "http"
    }
  }
}

VS Code opens a browser window for OAuth on first tool call.

---

Claude Desktop

Add as a Custom Connector (recommended)

1. Claude Desktop → Settings → Connectors → Add custom connector
2. URL: https://app.briefhq.ai/mcp
3. Sign in via browser when prompted
4. Restart Claude Desktop

Claude Desktop handles OAuth natively — no API keys, no config files, no extensions to install.

---

Codex

Codex reads MCP server config from ~/.codex/config.toml (not .mcp.json). Add:

[mcp_servers.brief]
url = "https://app.briefhq.ai/mcp"

Restart Codex. A browser window opens for OAuth on first tool call.

---

JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.)

JetBrains AI Assistant (2025.1+) supports MCP via Settings → Tools → AI Assistant → Model Context Protocol (MCP). Click +, then Command → As JSON, and paste:

{
  "mcpServers": {
    "brief": {
      "url": "https://app.briefhq.ai/mcp"
    }
  }
}

Save and invoke a Brief tool from an AI Assistant chat — a browser popup should open for OAuth.

---

Windsurf

Settings → Cascade → MCP Servers → Add custom server, with URL https://app.briefhq.ai/mcp and transport http. Windsurf opens a browser window for OAuth on first connect.

---

ChatGPT

Brief works with ChatGPT via Connected Apps. Setup is done via ChatGPT Settings → Apps & Connectors → Enable Developer Mode (if eligible) → Create, then enter connector metadata and your HTTPS MCP server URL (https://app.briefhq.ai/mcp). Create the connector via ChatGPT Settings and optionally contact hello@briefhq.ai for help.

---

Other MCP clients

Any MCP client that supports Streamable HTTP + OAuth can connect to Brief at https://app.briefhq.ai/mcp. Point your client at the URL with transport http and trigger a tool call — the browser popup will handle OAuth.

---

Step 2: Install the Brief agent behavior layer

Once MCP is connected, the agent has access to Brief's tools — but it won't know when to use them unless you tell it. For repo-aware coding agents (Cursor, Claude Code, VS Code, Codex), paste this into a new agent chat in your project's root directory:

Brief MCP is already connected here. Fetch and follow https://briefhq.ai/docs/agent-setup.md to install the Brief agent behavior layer in this project. If Brief prompts are available, use /brief-setup for first-time setup or /brief-welcome-back when this workspace is already set up.

Your agent will fetch `agent-setup.md`, detect your repo's existing agent conventions (Cursor rules, CLAUDE.md, AGENTS.md, .cursorrules, etc.), and install Brief skills, rules, and commands — the same setup the Brief team uses internally. Claude Desktop and ChatGPT don't auto-install repo-local skills (no project root), but you can still give them behavioral guidance via a Project's custom instructions.

Onboarding-specific entry points

Once the behavior layer is installed, prefer these onboarding entry points:

• /brief-setup — first-time setup on hosts that surface Brief prompts
• /brief-welcome-back — returning workspace, new surface
• brief_get_onboarding_context — raw fallback when prompts are not surfaced
• brief_ask with onboarding: true — fresh coding-repo synthesis path after reading the README, package/manifest files, and recent git log --oneline -20

Example fresh-repo onboarding call for coding agents:

brief_ask({
  question: "What should I know before building?",
  context: "<README summary + tech stack + recent commits + open questions>",
  onboarding: true
})

Not every host surfaces Brief prompts consistently. If you don't see /brief-setup or /brief-welcome-back, fall back to brief_get_onboarding_context, then use brief_ask(..., onboarding: true) on a fresh coding repo.

---

Available Tools

The Brief MCP server exposes a small flat top-level surface plus one escape-hatch tool.

Top-level tools (direct tool picker)

Tool names use the brief_* prefix. Older clients may still show aliases such as ask_brief or bare search / browse — they call the same tools; use the brief_* names in new prompts and docs.

Tool	What it does
brief_get_onboarding_context	Load Brief's strategic snapshot — decisions, features, personas, velocity, recent work. Call at session start. Supports scopes full, product, or identity.
brief_ask	Talk to Brief. mode: 'advise' for open-ended strategic guidance, mode: 'check' to validate an approach against existing decisions, mode: 'fast' for sub-second inline lookups.
brief_search	Universal search across decisions, documents, and features. Panel-backed — MCP Apps hosts render results as an interactive card. Pass types: 'decision' to narrow to decisions.
brief_browse	Browse folders and documents by path or folder ID.
brief_record_decision	Propose a new decision. Renders an approval card; the decision persists after the user clicks Approve.
brief_confirm_decision	Transition a proposed decision to active by ID.
brief_reject_decision	Reject a proposed decision with a required reason.
brief_archive_decision	Archive an outdated decision by ID.
brief_list_pending_decisions	List decisions awaiting confirmation (status: proposed). Prefer this when you need the pending queue; use brief_search with types: 'decision' for keyword search across decision history.
brief_update_product_context	Partial update to product context (company, goals, velocity, team, metrics).
brief_execute_operation	Escape hatch. Run operations that don't have a direct top-level tool: create_document, folder operations, bulk ops, guard_approach (prefer brief_ask with mode: 'check'), personas/features/market listings, etc. Takes operation + parameters. Prefer direct tools when they exist.

---

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 D-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 D-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:

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

---

CLI as a sibling channel

Brief MCP and the Brief CLI are separate install paths, and you can use both at once.

• MCP wires your coding agent to Brief via tool calls inside the host (Cursor, Claude Code, VS Code, etc.).
• CLI wires your coding agent to Brief via shell commands — your agent runs brief ask, brief decisions search, etc. from a terminal.

If shell-based access is your primary path, follow the Brief CLI setup guide — it's independent of the MCP installation above.

---

Troubleshooting

"Connection failed" or "Internal server error"

Restart your MCP client to clear its in-memory connection state. If that doesn't help, reinstall the host-native config above.

"401 Unauthorized"

Your OAuth token expired or was revoked. Sign in again from your host:

• Claude Code: /mcp → pick brief → re-auth
• Cursor / VS Code / Windsurf: trigger any Brief tool; the browser popup will reappear
• Claude Desktop: restart and invoke a Brief tool; the popup will reappear
• Codex: restart; the popup will reappear

MCP not showing up in your client

1. Verify your config is in the right place:

- Cursor: ~/.cursor/mcp.json - Claude Code: managed by claude mcp add — check claude mcp list - VS Code: .vscode/mcp.json (or the extension) - Claude Desktop: Settings → Connectors - Codex: ~/.codex/config.toml

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.

Multi-org mismatch

If you're in multiple Brief workspaces and MCP is returning data from the wrong one, switch to the correct org in the Brief web app first, then re-run the install steps (this rotates the token to the active org).

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
• Brief CLI Setup — shell-based access for coding agents