MCP OAuth Setup

This guide explains how to test the backend MCP OAuth flow with Insomnia and how the same backend is expected to be connected from ChatGPT.

Backend OAuth summary

The current backend implementation supports:

• Authorization Code flow
• Refresh tokens
• Dynamic client registration
• Public clients only with token_endpoint_auth_method=none
• Scope mcp
• Resource indicator https://YOUR_API_HOST/v1/ai/mcp

Discovery endpoints:

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource

OAuth endpoints:

GET  /v1/oauth/authorize
POST /v1/oauth/authorize
POST /v1/oauth/token
POST /v1/oauth/register

Insomnia setup

Insomnia is useful when you want to test the backend OAuth flow directly before configuring ChatGPT.

1. Register an OAuth client

In Insomnia, first open the OAuth 2 settings for the request and copy the exact value from the Redirect URL field.

Then register that redirect URI in the backend:

curl -X POST http://localhost:3333/v1/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Insomnia Local Test",
    "redirect_uris": ["PASTE_THE_INSOMNIA_REDIRECT_URI_HERE"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "mcp",
    "token_endpoint_auth_method": "none"
  }'

Save the returned client_id.

2. Fill in the Insomnia OAuth fields

Use these values:

3. Complete the flow

When Insomnia fetches a token:

1. It opens /v1/oauth/authorize in the browser.
2. You sign in with a normal backend user account.
3. You approve consent.
4. Insomnia exchanges the code at /v1/oauth/token.
5. Insomnia stores the returned bearer token and can call /v1/ai/mcp.

4. Common errors

• Redirect URI mismatch: the Insomnia redirect URI must exactly match the value registered with /v1/oauth/register.
• Missing resource: the resource field must match the MCP endpoint exactly.
• PKCE disabled: Insomnia should send PKCE with S256.
• Wrong scope: use mcp.

ChatGPT setup

As of May 11, 2026, OpenAI documents remote MCP connector support in ChatGPT developer mode and recommends OAuth plus dynamic client registration for custom remote MCP servers. See:

• Building MCP servers for ChatGPT and API integrations 
• Developer mode, apps and full MCP connectors in ChatGPT [beta] 

1. Requirements

• Your MCP server must be reachable over public HTTPS.
• The MCP endpoint you enter in ChatGPT should be the remote MCP URL, for example:

https://api.example.com/v1/ai/mcp

• The OAuth metadata endpoints must also be reachable from ChatGPT:

https://api.example.com/.well-known/oauth-authorization-server
https://api.example.com/.well-known/oauth-protected-resource

2. How ChatGPT connects

The expected flow is:

1. In ChatGPT developer mode, create a new custom MCP connector.
2. Enter the remote MCP endpoint URL.
3. ChatGPT reads the MCP and OAuth metadata.
4. ChatGPT registers itself dynamically as an OAuth client.
5. ChatGPT opens the backend login and consent flow.
6. The user signs in and approves access.
7. ChatGPT stores the issued access token and uses it for MCP requests.

For this backend, no manual client secret setup is required because the server currently supports public clients only with token_endpoint_auth_method=none.

3. Register the ChatGPT callback URL

When using ChatGPT’s Benutzerdefinierter OAuth-Client setup, first copy the exact Callback-URL shown in the connector form.

Then register that callback URL against the backend and save the returned client_id:

curl -X POST https://api.example.com/v1/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "ChatGPT MCP",
    "redirect_uris": ["PASTE_THE_CALLBACK_URL_FROM_CHATGPT_HERE"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "mcp",
    "token_endpoint_auth_method": "none"
  }'

Important:

• The callback URL must match exactly, including letter casing.
• If ChatGPT shows a different callback URL later, register that new value again and use the newly returned client_id.
• Leave client_secret empty for this backend.

4. Fill in the ChatGPT fields

For a deployment where the backend is exposed under https://api.example.com, use the following values in the ChatGPT connector form:

If your deployment uses a different public API host or path prefix, replace https://api.example.com consistently in every value above.

5. ChatGPT-specific compatibility note

ChatGPT’s current MCP OAuth setup does not expose a PKCE configuration surface in the connector UI.

Because of that, the backend includes a narrow compatibility exception for specific OpenAI callback hosts. Those allowlisted redirect hosts may complete the authorization flow without sending PKCE, while regular OAuth clients still need PKCE.

This means:

• Insomnia and other direct OAuth clients should continue using PKCE.
• ChatGPT can still connect successfully through the OAuth flow even when it omits PKCE.

6. Troubleshooting ChatGPT setup

• If ChatGPT cannot connect, first verify the MCP endpoint is public and HTTPS.
• Confirm the resource the backend expects is the same MCP endpoint URL.
• Confirm the backend discovery documents are reachable without authentication.
• Confirm the client_id belongs to the exact callback URL currently shown in ChatGPT.
• If the OAuth browser flow opens but fails, inspect the authorize request and callback redirect URI.
• If ChatGPT reconnects repeatedly, verify the token and refresh-token handling on the backend and confirm the connector was recreated after auth changes.

Recommended testing order

1. Verify the flow in Insomnia first.
2. Confirm the MCP endpoint works with the issued bearer token.
3. Move to ChatGPT only after the backend OAuth flow works in a normal OAuth client.

That makes it much easier to distinguish backend issues from ChatGPT connector configuration issues.