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.

💡

The MCP server endpoint is the protected resource at /v1/ai/mcp. The OAuth browser flow is handled by the backend under /v1/oauth/* and the discovery documents under /.well-known/*.

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:

Field	Value
Grant Type	`Authorization Code`
Authorization URL	`http://localhost:3333/v1/oauth/authorize`
Access Token URL	`http://localhost:3333/v1/oauth/token`
Client ID	returned `client_id`
Client Secret	leave empty
Use PKCE	enabled
Code Challenge Method	`SHA-256`
Redirect URL	exactly the same URI you registered
Scope	`mcp`
State	any random value
Credentials	`In Request Body` is preferred
Header Prefix	`Bearer`
Audience	leave empty
Resource	`http://localhost:3333/v1/ai/mcp`
Origin	leave empty

3. Complete the flow

When Insomnia fetches a token:

It opens /v1/oauth/authorize in the browser.
You sign in with a normal backend user account.
You approve consent.
Insomnia exchanges the code at /v1/oauth/token.
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:

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:

In ChatGPT developer mode, create a new custom MCP connector.
Enter the remote MCP endpoint URL.
ChatGPT reads the MCP and OAuth metadata.
ChatGPT registers itself dynamically as an OAuth client.
ChatGPT opens the backend login and consent flow.
The user signs in and approves access.
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. 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.

4. 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.
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

Verify the flow in Insomnia first.
Confirm the MCP endpoint works with the issued bearer token.
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.

Overview