MCP: OAuth

Some MCP servers require OAuth authentication. Flapjack supports the full OAuth 2.1 flow with PKCE, automatic token refresh, and encrypted token storage.

How OAuth Works in Flapjack

1. Start OAuth flow → Flapjack generates PKCE challenge
2. User redirected to MCP server's auth page
3. User authorizes access
4. Callback to Flapjack with auth code
5. Flapjack exchanges code for tokens
6. Tokens encrypted and stored
7. Auto-refreshed 2 minutes before expiry

Starting the OAuth Flow

Via Dashboard

1. Add an MCP server that requires OAuth
2. Click Connect with OAuth
3. Authorize in the popup
4. Connection confirmed automatically

Via API

Note: OAuth endpoints require user authentication (Supabase JWT). API keys (fj_live_*) are rejected.

curl -X POST https://api.flapjack.dev/api/mcps/{mcpId}/oauth/start \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-oauth-client-id",
    "authorizeUrl": "https://provider.com/oauth/authorize",
    "tokenUrl": "https://provider.com/oauth/token",
    "scope": "read write"
  }'

Response:

{
  "authorizationUrl": "https://provider.com/oauth/authorize?client_id=...&code_challenge=..."
}

Redirect the user to this URL. After authorization, the callback is handled automatically.

📋 Copy as prompt

Start an OAuth flow for my Flapjack MCP server. POST to /api/mcps/{mcpId}/oauth/start with the OAuth client ID, authorize URL, token URL, and scopes.

OAuth Security

Feature	Implementation
PKCE	SHA-256 code challenge (512-bit entropy)
State parameter	AES-encrypted with server-side validation
Token storage	AES-256-GCM encrypted at rest
Refresh	Automatic, 2 minutes before expiry
Transport	HTTPS only

Token Refresh

Flapjack automatically refreshes OAuth tokens before they expire. When a tool call is made:

1. Flapjack checks if the token expires within 2 minutes
2. If so, refreshes using the stored refresh token
3. Encrypts and stores the new tokens
4. Proceeds with the tool call using the fresh access token

No manual intervention needed.

Supported OAuth Providers

Any OAuth 2.0/2.1 compatible provider works. Common examples:

• GitHub
• Google Workspace — Gmail, Calendar, Drive, Sheets, Contacts, Tasks (managed MCP with incremental consent)
• Slack
• Microsoft (Azure AD)
• Custom OAuth providers

Troubleshooting

Issue	Solution
OAuth flow fails	Verify client ID, authorize URL, and token URL
Token refresh fails	Check that the refresh token hasn't been revoked
"invalid_grant" error	Re-authorize — the grant may have expired
Redirect mismatch	Ensure callback URL is registered with the provider

Next Steps

• MCP: Connecting Servers — add servers
• MCP: Building Tools — create custom MCP tools
• API: MCP Servers — endpoint reference