OAuth 2.1

OAuth 2.1 (ChatGPT Apps SDK, clientes MCP)

Servidor de autorização OAuth 2.1 com PKCE-S256, Dynamic Client Registration (RFC 7591) e metadados de descoberta (RFC 8414 + RFC 9728). Utilizado pelo ChatGPT Apps SDK e por qualquer outro cliente MCP compatível com OAuth. Disponível em todos os planos para o recurso MCP em /api/v1/mcp. Os tokens de acesso JWT assinados com RS256 e o token de atualização reutilizável partilham um prazo de autorização fixo de um ano.

Visão geral do OAuth 2.1

Utilize OAuth 2.1 quando o seu cliente precisa de acesso delegado por utilizador ao endpoint MCP e não pode disponibilizar uma chave de API (por exemplo, um assistente de IA multi-inquilino). Utilize chaves de API quando controla ambas as partes e pretende uma integração mais simples (plano Scale ou superior). O MCP através de OAuth está disponível em todos os planos, incluindo o teste gratuito.

Endpoints: /oauth/authorize, /oauth/token, /oauth/register, /oauth/jwks.json, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource.

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

Metadados do servidor de autorização em /.well-known/oauth-authorization-server (RFC 8414) e metadados do recurso protegido em /.well-known/oauth-protected-resource (RFC 9728). O JWKS utilizado para verificar as assinaturas dos tokens de acesso está em /oauth/jwks.json. Os clientes devem obter estes metadados para descobrir os endpoints de autorização, token e registo, nunca codificá-los de forma fixa.

Sem parâmetros. Devolve JSON com issuer, authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, scopes_supported, code_challenge_methods_supported e metadados relacionados.

POST/oauth/register

Dynamic Client Registration conforme a RFC 7591. Não autenticado e limitado a 5 pedidos por hora por IP. Apenas os campos da RFC 7591 são persistidos (os campos adicionais são descartados). Os URIs de redirecionamento têm de ser HTTPS (qualquer anfitrião) ou HTTP loopback (localhost / 127.0.0.1); esquemas personalizados como javascript:, data: e file: são rejeitados. Máximo de 10 URIs de redirecionamento por cliente; client_name limitado a 200 caracteres; URIs limitados a 2048 caracteres.

Corpo JSON: redirect_uris (array obrigatório), client_name, grant_types (predefinição: authorization_code refresh_token), token_endpoint_auth_method (none para clientes PKCE públicos, client_secret_post para confidenciais), scope.

GET/oauth/authorize

Apresenta um ecrã de consentimento na aplicação. Após aprovação, redireciona o utilizador de volta para redirect_uri com um code de utilização única (TTL de 10 minutos) e o state original. O PKCE-S256 é obrigatório; os desafios plain são rejeitados.

Parâmetros: response_type=code (obrigatório), client_id (obrigatório), redirect_uri (obrigatório, tem de corresponder exatamente a um URI registado), code_challenge (obrigatório), code_challenge_method=S256 (obrigatório), scope (separado por espaços: mcp:read mcp:write), state, resource (indicador de recurso RFC 8707).

POST/oauth/token

Troca um código de autorização por um token de acesso + token de atualização, ou atualiza um token de acesso. Utiliza application/x-www-form-urlencoded. Limitado a 60 pedidos por minuto por IP. As respostas de atualização devolvem o mesmo token de atualização reutilizável, e todas as credenciais expiram no prazo de autorização fixo de um ano.

Corpo: grant_type (authorization_code ou refresh_token), client_id (obrigatório), client_secret (obrigatório para clientes confidenciais) e {code, code_verifier, redirect_uri} OU {refresh_token, scope opcional para redução de âmbito}.

Âmbitos e validação do destinatário

mcp:read (predefinição) concede acesso a ferramentas apenas de leitura. mcp:write é necessário para utilizar ferramentas de escrita, incluindo create_prompts, create_intelligence_task, create_competitor, create_collection, assign_prompt_tags, create_annotation, update_intelligence_task_content, revert_intelligence_task_content, launch_recommendations, create_technical_geo_report, update_technical_geo_report_content e revert_technical_geo_report_content. Depois de estabelecer a ligação, consulte tools/list para ver as ferramentas disponíveis para o token. Um token emitido apenas com mcp:read não pode invocar ferramentas de escrita: tools/list oculta-as e uma chamada direta a tools/call devolve um erro. A declaração aud (audiência) do JWT tem de corresponder ao URL anunciado do recurso MCP, ao URL base do anfitrião do pedido, ao emissor do servidor de autorização ou a esse emissor seguido de /api/v1/mcp. Quando não é fornecido um indicador de recurso, utiliza-se o emissor; qualquer outra audiência é rejeitada em /api/v1/mcp.

Ao atualizar um token, PODE indicar um scope mais restrito; qualquer âmbito mais amplo do que a concessão original devolve invalid_grant.