Skip to main content
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 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
  • 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 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: 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

The Flex MCP landing page generates the exact install snippet for either path.