Connect ChatGPT and Claude

This page connects ChatGPT and Claude to an MCP server built with Add MCP to your application. Each host gets its own OAuth client. A person connects, signs in to your application, and allows access on your consent page. The host then calls your tools with a ten-minute access token and renews it while the person's session lasts.

Before you connect

• Deploy the application and Convex with HTTPS origins. Hosts do not connect to a loopback address.
• Set SITE_URL to the exact public Nuxt origin. The OAuth issuer is ${SITE_URL}/api/auth.
• Run auth:ensureSigningKey and check that its key ID appears at https://your-app.example/api/auth/jwks.
• List each host in the profile: oauth: { mcp: { scopes, hosts: ['chatgpt', 'claude'] } }.
• Export an internal mutation that calls auth.oauthOperator.createHostClient, as in the recipe's convex/connections.ts.
• Test the flow with MCP Inspector first.

What each host needs

The clients are public clients with S256 PKCE. They have no secret. Dynamic client registration is off, so the host cannot create a client itself.

Connect Claude

1. Create the client:

   pnpm exec better-convex convex run connections:createHostClient '{"host":"claude"}'

   Record the returned clientId. The client accepts only Claude's fixed callback and every scope in your profile.

2. In Claude, add a custom connector. Enter the MCP server URL.
3. Select Use your own OAuth client and paste the client ID. Leave the secret empty.
4. Connect. Claude opens your login page, then your consent page. Sign in and select Allow.
5. Start a new conversation and ask for something one of your tools can do.

Claude reads scopes_supported from your protected-resource metadata. It can request read access and renewal first, and ask for write consent the first time a write tool needs it.

Connect ChatGPT

ChatGPT shows its callback URL during setup, so create the client in the middle of the setup.

1. In ChatGPT, start a new connector in the developer connection settings. Enter the MCP server URL and select OAuth.
2. Copy the exact callback URL that ChatGPT displays. It is https://chatgpt.com/connector_platform_oauth_redirect or https://chatgpt.com/connector/oauth/<callback-id>. Do not guess the callback ID.

3. Create the client with that callback:

   pnpm exec better-convex convex run connections:createHostClient \
     '{"host":"chatgpt","redirectUri":"https://chatgpt.com/connector_platform_oauth_redirect"}'

4. In Advanced OAuth settings, set Registration method to User-Defined OAuth Client and Token endpoint auth method to none. Paste the client ID and leave the client secret empty.
5. Under Default scopes, select the scopes the connection needs. Enter offline_access in Base scopes so that ChatGPT receives a refresh token. Without it, ChatGPT asks the person to reconnect after ten minutes.
6. Connect, sign in, and allow access. Refresh the connector's tools, then start a new conversation.

Scopes and consent

Your consent page shows the verified client name, the exact resource, and each requested scope with its description from oauth.mcp.scopes. Consent grants exactly the requested scopes, never more.

• A tool with scopes: ['notes:write'] is visible to every connection. A connection without that scope receives an HTTP 403 insufficient_scope challenge when it calls the tool. The host can then ask the person for consent again.
• offline_access allows renewal. The refresh token ends with the Better Auth session that granted consent, and after at most seven days. Signing out of your application ends renewal.
• A broader permission always needs new consent. An earlier grant is never widened silently.

Each connection is one row on the person's connections page (auth.oauthConnections.list). Disconnect there revokes the consent and the refresh tokens on the server. The host's next request fails.

Disconnecting inside the host does not always revoke the grant on your server. Revoke it on your connections page. To stop a host for every user, disable its client with auth.oauthOperator.setClientDisabled.

Test with MCP Inspector

Test the OAuth flow and your tools locally before you connect a real host.

1. Create a client for Inspector's local callback. Run this internal mutation only in development:

   export const createInspectorClient = internalMutation({
     args: {},
     handler: async (ctx) =>
       await auth.oauthOperator.createPublicClient(ctx, {
         name: 'MCP Inspector',
         profile: 'mcp-inspector',
         redirectUris: ['http://localhost:6274/oauth/callback'],
         resource: { identifier: auth.mcp.resource().href, name: 'MCP', ownership: 'application' },
         scopes: ['notes:read'],
       }),
   })

   Use the same resource name as createHostClient: your appName, or MCP when you have not set one.

2. Run pnpm dlx @modelcontextprotocol/inspector.
3. Select the Streamable HTTP transport and enter your CONVEX_SITE_URL followed by /mcp.
4. In the OAuth settings, enter the client ID, leave the secret empty, and request your scopes.
5. Connect, sign in, and allow access. List the tools and call one.
6. Disconnect on your connections page, then call the tool again. The call must fail with HTTP 401.

For automated checks, snapshot the catalog with listMcpCatalog as shown in MCP on Convex.

Update tools after a deploy

Hosts cache the tool list. After you change tools:

• In ChatGPT, refresh the connector's tools, then start a new conversation.
• In Claude, start a new conversation. Claude can keep an older catalog for a while.
• Keep MCP Apps ui:// URIs stable. See MCP Apps.

Common failures