> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brew.new/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<AccordionGroup>
  <Accordion title="OAuth connector (recommended)" defaultOpen>
    Brew is its own **OAuth 2.1 authorization server**, so most clients connect with **no key to copy**. Add the URL as a ChatGPT plugin or MCP connection; 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 ChatGPT, Claude, Grok, Cursor, Codex, VS Code, and the rest. See [Connect your client](/api-reference/mcp/connect-your-client).
  </Accordion>

  <Accordion title="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 or invalid credential returns `401`; OAuth-capable clients use its challenge to begin discovery.
  </Accordion>
</AccordionGroup>

### OAuth Discovery and Security

Compatible clients discover authentication from Brew's `401 WWW-Authenticate` challenge and protected-resource metadata. Brew publishes RFC 8414 authorization-server metadata (plus the OIDC discovery fallback), supports Dynamic Client Registration for public clients, and requires Authorization Code + PKCE S256. Redirect URIs are exact-match registered, web callbacks require HTTPS, and loopback HTTP remains available for desktop clients.

The only public scope is `brew:all`. Authorization and refresh requests are bound to the exact resource audience `https://brew.new/api/mcp`; unknown scopes and audience mismatches are rejected. Access tokens are short-lived, refresh tokens rotate, and reusing an already-rotated refresh token revokes that grant. Brew does not advertise Client ID Metadata Documents (CIMD).

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

<Tabs>
  <Tab title="Self-Service Tools">
    <CardGroup cols="2">
      <Card title="Search Documentation" icon="magnifying-glass" color="#c44925">
        Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages.
      </Card>

      <Card title="ChatGPT/Claude Integration" icon="robot" color="#c44925">
        Click "Open in ChatGPT" at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Talk to Our Team">
    <CardGroup cols="2">
      <Card title="Schedule a Call" icon="calendar" color="#c44925" href="https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ1iYoRUG1J792XQpbuQLjSRRDupr7MwraFK-HQRCtTYdBmrQi8nZu2qXfzKQigb8gbKJK3KN3-R">
        Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.
      </Card>

      <Card title="Call Us Directly" icon="phone" color="#c44925">
        Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions.
      </Card>

      <Card title="Slack Channel" icon="slack" color="#c44925">
        Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses.
      </Card>

      <Card title="Email Support" icon="envelope" color="#c44925" href="mailto:support@brew.new">
        Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>