## Authentication Modes

The Flex MCP supports two authentication modes. Pick the one that matches your client; both scope access to your partner account and tag every request with the calling identity for audit purposes.

## OAuth

The OAuth path is what most graphical clients use — Claude.ai, Claude Desktop, Cursor, Windsurf, VS Code. The user clicks a button, signs in to Flex through a browser, and approves the connection.

- **Endpoint:** `https://mcp.withflex.com/api/mcp/oauth`
- **Sign-in identity:** Your Flex Dashboard user (the same one you sign in to [dashboard.withflex.com](https://dashboard.withflex.com/) with).
- **Scope:** Same access as that user has in the Flex Dashboard, across the partner they belong to.
- **Tokens:** Short-lived; clients refresh transparently. No secrets to copy or paste.

OAuth is the recommended path for any client that can open a browser window.

## API Key

The API key path is for headless agents — Claude Code, CI jobs, scripts — where popping a browser is awkward. You generate a key once in the Flex Dashboard and paste it into your client’s MCP config as an `Authorization: Bearer` header.

- **Endpoint:** `https://mcp.withflex.com/api/mcp`
- **Header:** `Authorization: Bearer fsk_…` (live) or `Authorization: Bearer fsk_test_…` (test)
- **Generate keys:** [dashboard.withflex.com/apikeys](https://dashboard.withflex.com/apikeys)
- **Scope:** Whatever scopes you assigned the key (e.g. `payment_intents:read`, `refunds:write`). A key with no scopes has full partner access.

Treat MCP API keys exactly like backend API keys: never commit them, never paste them into a shared chat, and rotate them on the same cadence as the rest of your secrets. See [Security best practices](https://docs.withflex.com/developer-guides/integration/mcp/security) for recommendations.

## Test Mode

Flex separates test data from live data. The two MCP paths handle this differently — important to understand before you connect a production account.

### API Key Path

The key prefix encodes the mode:

| Prefix       | What it does                                           |
|--------------|-------------------------------------------------------|
| `fsk_test_…`| All calls hit test data. Safe for experimentation.    |
| `fsk_…`     | All calls hit live data. Real refunds, real customers.|

The mode is fixed for the lifetime of the key — there’s no per-call override. To switch, install a different key. This is atomic and hard to get wrong, which is why we recommend it for Claude Code.

### OAuth Path

OAuth tokens don’t encode test vs. live, because the same Flex user has access to both. Instead, every tool the MCP exposes takes an `api_test_mode` parameter:

- **Read tools** — Defaults to `false` (live data) if you don’t specify. Pass `true` to query test data.
- **Write tools** — The MCP requires you (or the LLM) to set `api_test_mode` explicitly. Mutating live data without saying so is blocked.

When you’re getting started, give the assistant a clear instruction up front:

> Use test mode (`api_test_mode: true`) for every Flex tool call in this conversation. Don’t touch live data unless I explicitly say so.

Then flip to live only once you’re comfortable.

Until you’re confident in how your AI assistant uses the Flex MCP, **work in test mode**. A misinterpreted instruction in live mode can create a real product, issue a real refund, or charge a real customer. Test mode is risk-free.

## Identifying Which Endpoint to Use

| If your client…                                                              | Use this endpoint                          |
|-------------------------------------------------------------------------------|--------------------------------------------|
| …can open a browser for sign-in (Claude.ai, Claude Desktop, Cursor, Windsurf, VS Code) | `https://mcp.withflex.com/api/mcp/oauth` |
| …is headless or you prefer scoped keys (Claude Code, scripts, CI)                       | `https://mcp.withflex.com/api/mcp`       |

The [Flex MCP landing page](https://mcp.withflex.com/) generates the exact install snippet for either path.