Connecting claude.ai

Overview

Claude.ai (the web interface) supports MCP through custom connectors. Unlike Desktop or Code, the web version uses a full OAuth 2.1 + PKCE flow. The good news: it's mostly automatic. Claude registers itself and handles tokens — you just paste your API key once.

Prerequisites

• A claude.ai account with access to custom connectors
• An active API key (generate one here)
• Your platform URL (e.g., https://api.v2.affinitydesign.ca)

How It Works

Your platform implements the complete OAuth 2.1 authorization server:

1. Dynamic Client Registration (RFC 7591) — Claude registers itself automatically
2. Protected Resource Metadata (RFC 9728) — Claude discovers auth endpoints
3. Authorization Server Metadata (RFC 8414) — Standard OAuth discovery
4. PKCE with S256 — Secure authorization code flow
5. Refresh token rotation — New refresh token issued on every exchange

Tokens are signed JWTs (HS256) bound to your client's origin:

• Access tokens: 1 hour expiry
• Refresh tokens: 30 days expiry

Step-by-Step Connection

1. Open Custom Connectors

In claude.ai:

1. Click your profile → Customize
2. Go to the Connectors tab
3. Click Add custom connector

2. Enter Your Platform URL

3. Connect

Click Connect. Claude will:

1. Fetch /.well-known/oauth-protected-resource to discover auth endpoints
2. Register itself via POST /oauth/register
3. Redirect you to the sign-in form

4. Authenticate with Your API Key

You'll see a dark-themed form titled "Authorize Claude":

1. Paste your afk_... API key into the field
2. Click Authorize

The server resolves your client from the key and issues an authorization code. Claude exchanges it for access/refresh tokens automatically.

5. Start Using Tools

Once connected, Claude shows a tools indicator in chat. You can now ask things like:

"Check my GHL calendar for tomorrow and book a follow-up call with the lead who called today"

"Run a GA4 report on last month's traffic and create a summary in my WordPress drafts"

Security Notes

• Your API key is only used once during the OAuth flow. It's not stored by Claude.
• Tokens are scoped to the specific client resolved from your API key.
• Plugin restrictions from the API key are inherited — if your key only allows ga4 and gbp, Claude can only use those plugins.
• No admin access: You cannot use an admin JWT for the web connector. It must be a client-scoped API key.

Managing Connections

View Active Sessions

As an admin, you can view active MCP sessions:

GET /mcp/sessions
Authorization: Bearer YOUR_ADMIN_JWT

This returns:

• Session IDs
• Client IDs
• Initialization status
• Plugin counts

Revoke Access

To disconnect Claude:

1. Go to claude.ai → Customize → Connectors
2. Find your connector
3. Click Disconnect

This invalidates the session on Claude's side. The tokens on your platform expire naturally (1 hour for access tokens).

Force Logout (Admin)

If you need to immediately terminate all sessions for a client, rotate their API keys:

1. Revoke the old key in Admin → Clients → API Keys
2. Generate a new key
3. Re-authenticate Claude with the new key

Troubleshooting

"Unable to connect" during setup

• Verify your platform URL is correct and publicly accessible
• Ensure /.well-known/oauth-protected-resource is reachable
• Check that the client is Active in your admin dashboard

"Invalid API key" during authorization

• The key may have been revoked or the client deactivated
• Verify you're using the full raw key (not just the prefix)
• Ensure the key has mcp:access scope

Tools disappear after an hour

• This is normal — access tokens expire after 1 hour
• Claude should auto-refresh using the refresh token
• If it doesn't, disconnect and reconnect the connector

"Unauthorized" on every request

• The OAuth client may have been deleted or changed
• Try disconnecting and reconnecting the connector in Claude's settings