The ChatGPT Connector (beta) offers a way to integrate your custom tools and data directly into the chat using the Model Context Protocol (MCP).

If you've tried to secure this connection, you've probably discovered that the required OAuth 2.0 flow documentation is minimal. After hours of inspecting network traffic and testing endpoints, I've pieced together the exact sequence.

This is the practical, step-by-step guide I wish I had, detailing what OpenAI's connector actually expects to get your integration working securely.

Prerequisites

This guide is for developers. I'll assume you are already familiar with two things:

How to set up a basic MCP server and define its tools.
The general concepts of OAuth 2.0 and the authorization code flow.

I will also assume you already have a token-based authentication (like a Bearer token) set up for your MCP server.

Briefly, a simple way to look at OAuth is this. If authentication is about proving you have the right key (token) to open a lock, OAuth is the process that ensures only the right person (user) is given a specific key. It's a delegation layer, not a replacement for your existing authentication.

The OAuth Flow

To connect, ChatGPT's backend and the user's browser will interact with your server in a specific sequence. To handle this flow, you need to implement four main components, more in the next section.

The diagram illustrates the complete OAuth flow for the ChatGPT Connector. It's very simple.

Essential Endpoints You Must Implement

The entire integration depends on correctly implementing four specific endpoints. The connector requires them to respond with a very specific JSON specification. Your OIDC provider may or may not provide these endpoints. However, I'll document what the ChatGPT connector specs expect.

I'll provide examples in Flask to keep things simple, but you can vibe code the actual implementation in your framework of choice (FastAPI, Express, etc.). Focus on the specification, not the example code.

1. The OpenID Configuration Endpoint

This is the starting point. When a user adds your MCP server URL to ChatGPT, the connector's backend immediately probes that URL for an OpenID Connect (OIDC) configuration file.

An Important and Non-Standard Detail

Here's the first major, non-standard behavior you need to know. ChatGPT looks for this OIDC config file on your MCP server's URL, at /.well-known/openid-configuration.

This is unusual. An OAuth/OIDC server is typically a completely separate service from the resource server (your MCP server). ChatGPT assumes your MCP server is also your auth server. This might be fixed at some point, but you must account for it for now.

How to handle this:

If you're building a simple integration, you can host this file directly on your MCP server.
If you have a separate, real OAuth server (like Cognito, Auth0, or your own), your MCP server must act as a proxy. It needs to catch the request to /.well-known/openid-configuration, proxy/forward it to your actual auth server OpenID configuration path, and return the response.

The Response Spec

Your server must return a JSON object that looks like this at this endpoint. The most important values to define are the authorization_endpoint, token_endpoint, and registration_endpoint.

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/.well-known/openid-configuration", methods=["GET"])
def openid_configuration():
    """
 Serves the OIDC discovery document that ChatGPT expects.
 """
 config = {
        "issuer": "https://your-domain.com",
        "authorization_endpoint": "https://your-domain.com/oauth2/authorize",
        "token_endpoint": "https://your-domain.com/oauth2/token",
        "registration_endpoint": "https://your-domain.com/oauth2/register",
        "response_types_supported": ["code"],
        "grant_types_supported": ["authorization_code"],
        "token_endpoint_auth_methods_supported": ["none", "client_secret_post"],
        "code_challenge_methods_supported": ["S256"],
        "scopes_supported": ["openid", "profile", "email", "token"],
        "claims_supported": ["sub", "api_token"]
 }
    return jsonify(config)

2. The Registration Endpoint

After fetching the OIDC config, ChatGPT will immediately call the registration_endpoint you defined (e.g., /oauth2/register). This is an automated POST request from their backend to register itself as a client dynamically.

The Response Spec

Your endpoint needs to receive this request and respond with a JSON object confirming the registration. You can return the OAuth client_id for ChatGPT to use.

Update (Oct 29, 2025): scope field needs to be set and limited to exactly 'openid email' or 'email'. Adding other scopes such as profile or phone would cause an error. OAuth failed: invalid_request - invalid_scope. This is possibly a bug.

@app.route("/oauth2/register", methods=["POST"])
def oauth_register():
    """
 Handles the dynamic client registration request from ChatGPT.
 We can just return a static response.
 """
    # In the actual application, you might inspect request.json['redirect_uris']
    # but for this purpose, a static response is fine.
    
 response = {
        "client_id": "your-oauth-client-id"
        "redirect_uris": [
            "https://chatgpt.com/connector_platform_oauth_redirect"
 ],
        "token_endpoint_auth_method": "none",
        "grant_types": ["authorization_code"],
        "response_types": ["code"],
        "application_type": "web"
        "scope": "openid email" # Set scope
 }
    return jsonify(response)

3. The Authorization Endpoint (User Login)

This is not a backend API. This is the user-facing login page you specified in your OIDC config's authorization_endpoint (e.g., https://your-domain.com/oauth2/authorize).

After registration, ChatGPT redirects the user's browser to this page to log in.

The Flow

Your login page authenticates the user (e.g., with a username/password form).
After successful login, your server generates a temporary, one-time-use authorization_code.
Your server redirects the user's browser back to ChatGPT's callback URL, passing that code.

An Important Point: Whitelisting the Callback URL

Your OAuth server (whether it's Cognito, Auth0, or your custom build) must have ChatGPT's callback URL added to its "allowed callback URLs" list.

The URL is: https://chatgpt.com/connector_platform_oauth_redirect

If this URL is not on your allowlist, your auth server will block the redirect and the flow will fail. You must ensure this is whitelisted in your configuration.

4. The Token Endpoint (The "Secret Sauce")

This is the final, most important step, and the secret sauce of the whole integration. It's completely undocumented, and if you get any part wrong, it just fails silently with no useful errors.

The Flow

The user has been redirected back to ChatGPT with the authorization_code.
ChatGPT's backend now makes a POST request to your token_endpoint (e.g., /oauth2/token).
This request includes the code it just received and a code_verifier (for PKCE).
Your server receives this request. This is where the magic happens.

The Response Spec

ChatGPT expects a standard OAuth token response.

Your endpoint's logic must:

Validate the authorization_code from the request.
Look up the user associated with that code.
Fetch that user's actual API key from your database.
Return that API key in the access_token field of the JSON response.

ChatGPT will then save this API key and use it as the Bearer token for all future MCP requests to your server.

from flask import request

@app.route("/oauth2/token", methods=["POST"])
def oauth_token():
    """
    It exchanges the temporary auth code for the user's
    permanent API key.
    """
    
    # Extract data from the form-encoded request
    grant_type = request.form.get("grant_type")
    code = request.form.get("code")
    client_id = request.form.get("client_id")
    code_verifier = request.form.get("code_verifier")

    f grant_type != "authorization_code":
        return jsonify({"error": "unsupported_grant_type"}), 400

    # ----------------------------------------------------
    # TODO: YOUR CUSTOM LOGIC GOES HERE
    #
    # 1. Validate the 'code' and optionally the 'code_verifier' (PKCE).
    # 2. Find the user_id associated with this validated 'code'.
    # 3. Look up that user's permanent API key from your database.
    #
    # user_api_key = my_db.get_api_key(user_id)
    #
    # ----------------------------------------------------
    
    # For this example, we'll just hardcode it.
    user_api_key = "MY_USER_PERMANENT_API_KEY_123456789"

    # Return the API key as the 'access_token'
    token_response = {
        "access_token": user_api_key,
        "token_type": "Bearer",
        "expires_in": 7776000,  # 90 days (or however long you want)
        "scope": "token"
     }
    
    return jsonify(token_response)

Conclusion

Implementing OAuth for the ChatGPT Connector is a specific, undocumented process, but it's not magic. It's a standard OIDC flow requiring a few purpose-built endpoints.

You can bridge the gap by building a shim that includes an OIDC configuration, a registration endpoint, and a custom token endpoint. This allows you to securely authenticate users with a standard login flow while using your existing API key-based system on the backend.

Your users get a seamless connection, and your server gets the static token it needs.

How to Set Up OAuth for the ChatGPT Connector