Conectores claude.ai e ChatGPT

Onde no admin: System › Settings › API & AI agents (/agent/keys), aba Connected apps. A tela de consentimento é aberta em /agent/consent quando um conector solicita acesso (ela não fica no menu).

O que faz

Aplicativos de IA na web não podem ler uma chave do seu disco. Eles se conectam com OAuth: você adiciona a URL de MCP do painel, o aplicativo o direciona para o seu próprio admin para fazer login, você escolhe o que o aplicativo pode fazer e por quanto tempo, e o aplicativo recebe tokens de curta duração. Nenhuma chave é copiada ou colada. Você pode cortar o acesso do aplicativo a qualquer momento.

Use isto para conectores personalizados do claude.ai, conectores em modo de desenvolvedor do ChatGPT e qualquer outro cliente MCP que ofereça suporte a OAuth com registro dinâmico de clientes. Ferramentas de linha de comando podem usar o mesmo fluxo, mas uma chave de API de admin é mais simples para elas.

Requisitos

Item	Requisito
URL	https://cloud.example.com/mcp/admin, acessível pela internet (os servidores do fornecedor se conectam a ele).
Proxy reverso	Se você colocar seu próprio proxy na frente do painel, ele deverá encaminhar os caminhos /mcp/admin, /oauth-admin/ e /.well-known/ para o painel.
Você	Logado no admin do NexCMP no mesmo navegador que você usa para a tela de consentimento.
Cliente	Suporta MCP sobre HTTP streamable, OAuth 2.1 com PKCE (S256) e registro dinâmico de clientes.

Conectar

1. No aplicativo de IA, adicione um conector MCP personalizado e cole https://cloud.example.com/mcp/admin. No claude.ai, isso fica nas configurações de conectores (adicionar conector personalizado); no ChatGPT, fica no modo de desenvolvedor (adicionar um conector MCP, autenticação OAuth).
2. Escolha Sign in (ou "Connect") no aplicativo. Seu navegador abre a tela de consentimento do admin do NexCMP. Se você não estiver logado, faça login primeiro; a tela continuará em seguida.
3. Leia o cartão: "Example AI app wants to manage this NexCMP admin" (o nome do aplicativo que está solicitando), junto com o endereço para o qual você será enviado de volta.
4. Marque os escopos a serem concedidos. Os que o aplicativo solicitou já vêm marcados; se ele não solicitou nenhum, apenas admin:read estará marcado. Consulte Scopes.
5. Escolha quanto tempo a conexão dura: 7, 30 ou 90 dias (padrão 30).
6. Clique em Allow. O navegador retorna ao aplicativo, que agora está conectado. Clique em Deny para recusar.

::: important Escolha os escopos como faria para uma chave Conceda o menor conjunto que realize a tarefa. Dinheiro, ações de exclusão e de segurança ainda param em uma prévia e precisam da sua aprovação, mas uma conexão com settings:write ainda pode alterar sua identidade visual e seu e-mail. :::

Gerenciar e revogar

Abra System › Settings › API & AI agents › Connected apps. A tabela lista cada aplicativo que você conectou: aplicativo, escopos, quando se conectou, quando expira e quando foi usado pela última vez.

Para cortar o acesso de um aplicativo, clique em Revoke e confirme. Os tokens dele deixam de funcionar imediatamente; o aplicativo precisará passar pela tela de consentimento novamente para se reconectar.

Como o fluxo funciona

Etapa	Detalhe
Descoberta	O aplicativo lê /.well-known/oauth-protected-resource/mcp/admin e depois /.well-known/oauth-authorization-server/oauth-admin. O emissor é https://cloud.example.com/oauth-admin.
Registro	O aplicativo se registra (POST /oauth-admin/register, RFC 7591). Apenas clientes públicos são suportados (sem segredo de cliente). O endereço de redirecionamento deve ser https, ou http no mesmo computador (loopback).
Autorização	GET /oauth-admin/authorize com o método PKCE S256. Um parâmetro resource, quando enviado, deve ser a URL /mcp/admin deste painel. A solicitação é válida por 10 minutos e está vinculada ao navegador que a iniciou.
Consentimento	Você escolhe os escopos e a duração (acima). O código de autorização é válido por 60 segundos e funciona uma vez.
Tokens	POST /oauth-admin/token retorna um access token (um ak_o... chave, válido por 1 hora ou até o término da conexão, o que ocorrer primeiro) e um refresh token (akr_...). Cada atualização retorna um novo refresh token; o antigo deixa de funcionar. A conexão termina após os dias escolhidos.
Revogação	Revoke em Aplicativos conectados, ou o aplicativo chama POST /oauth-admin/revoke (RFC 7009).

O access token se comporta como uma chave de administrador com os escopos que você concedeu: mesmas regras de escopo, confirmação, limite de taxa e log de atividades. Suas chamadas aparecem na aba Activity.

Verificar

1. No aplicativo, pergunte "run system_health" (ou "what tools do you have?"). O aplicativo lista as ferramentas que seus escopos permitem (a lista de ferramentas).
2. Abra Connected apps: Last used é atualizado.
3. Abra Activity: as chamadas são listadas com o nome do aplicativo e mcp.

Limites e notas

• Se o aplicativo pedir novamente para fazer login após uma hora, isso é normal quando um cliente não atualiza; reconecte.
• Um refresh token usado duas vezes é tratado como roubado: toda a conexão é revogada. Reconecte a partir do aplicativo.
• Um código de autorização usado duas vezes é rejeitado (invalid_grant) e os tokens já emitidos a partir dele são revogados.
• O acesso OAuth nunca concede mais do que as regras de escopo permitem: o que uma chave nunca pode fazer também se aplica aos aplicativos conectados.
• Os fornecedores alteram seus menus e o que suportam. Se o aplicativo de um fornecedor não oferecer conectores personalizados no seu plano, use uma admin API key com um cliente de desktop ou de linha de comando em vez disso.

Resolução de problemas

Sintoma	Causa	Correção
A tela de consentimento diz "Wrong browser"	A solicitação foi iniciada em um navegador diferente daquele em que você está conectado	Inicie a conexão novamente a partir do aplicativo de IA no mesmo navegador.
A tela de consentimento diz que a solicitação expirou ou está ausente	Mais de 10 minutos se passaram ou o link foi aberto duas vezes	Inicie a conexão novamente a partir do aplicativo de IA.
Página "Unknown client" ou "redirect address does not match"	O registro do aplicativo está desatualizado ou ele usa um endereço de redirecionamento que não registrou	Remova o conector no aplicativo e adicione-o novamente.
invalid_target	O resource enviado não é a URL /mcp/admin deste painel	Use a URL exata exibida na aba Connect an AI.
invalid_request sobre PKCE	O cliente não envia code_challenge_method=S256	Use um cliente que suporte OAuth 2.1 com PKCE.
O aplicativo se conecta, mas uma chamada retorna insufficient_scope	Você não marcou esse escopo	Revogue a conexão e conecte-se novamente com o escopo marcado.
O aplicativo não consegue alcançar a URL	DNS, TLS ou o proxy reverso bloqueiam /mcp/admin, /oauth-admin/ ou /.well-known/	Verifique as regras do proxy.