MCP authentication & scoping

How the Brew MCP server authenticates — a native OAuth connector or a brand-scoped API key — scopes every call to one brand, and makes writes safe to retry.

Authentication

The connection URL is clean and the same for everyone:

https://brew.new/api/mcp

There are two ways to authenticate it.

OAuth connector (recommended)

Brew is its own OAuth 2.1 authorization server, so most clients connect with no key to copy. Add the URL as a connector; on first connect the client opens your browser to sign in with Brew and pick a brand. Brew issues a token scoped to that brand — you can see and revoke it under Settings → API (“Connected via OAuth”). This is the first-party flow for Claude, ChatGPT, Cursor, VS Code, and the rest — see Connect your client.

API key (alternative)

For clients with no OAuth UI, or headless / CI setups, send a brand-scoped API key as a bearer token instead:

Authorization: Bearer brew_YOUR_API_KEY

Create keys at Settings → API. A request with no / invalid credential returns 401.

Brand scoping

Every connection is scoped to exactly one brand — and there is no brand in the URL. With OAuth you choose the brand when you sign in; with an API key the key itself carries the org + brand. Either way the token or key determines the brand for every call. To operate on a different brand, connect again and pick it (OAuth) or use that brand’s key. Find brand details via the get_brand tool or the dashboard.

Safe retries (idempotency)

Every write tool accepts an optional idempotency_key (≤ 100 chars). A repeat call with the same key replays the original result instead of acting twice; the same key with a different payload returns 409 IDEMPOTENCY_CONFLICT. This reuses the API’s Redis reserve/replay, so a key is honored identically across the MCP and HTTP surfaces. Always pass one on send_email — it is fail-closed (refuses with a retryable 503 if dedupe can’t be guaranteed) so a retry never sends a campaign twice.

Errors & observability

Errors surface with an actionable code, message, suggestion, and a request_id you can quote to support. Out-of-credits → INSUFFICIENT_CREDITS. Permission gaps and validation failures each return a distinct code.

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Self-Service Tools

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.