Pular para o conteúdo principal

Como registrar e verificar um aplicativo OAuth do AtomicMCP

Use este procedimento para conectar um aplicativo interno, agente, automação ou outro produto compatível com MCP.

Antes de começar​

O cliente deve oferecer suporte a MCP Streamable HTTP, OAuth Authorization Code, PKCE S256, tokens Bearer, rotação de refresh tokens e uma URL estável de callback HTTPS.

Etapa 1: Preparar o callback​

Escolha a URL exata que será atendida pelo aplicativo:

https://seu-app.example.com/oauth/atomicat/callback

O AtomicMCP compara o callback de forma exata, incluindo esquema, host, caminho, porta e barra final.

Etapa 2: Criar o aplicativo OAuth​

  1. Entre no Atomicat.
  2. Abra Configurações → Integrações.
  3. Em Aplicativos OAuth do AtomicMCP, selecione Criar aplicativo.
  4. Informe o nome e o callback exato.
  5. Selecione os escopos máximos que poderão ser solicitados.
  6. Salve o aplicativo e copie o Client ID, a URL de verificação e o JSON.

Etapa 3: Publicar o documento de verificação​

Sirva o JSON gerado em cada origem de callback:

https://seu-app.example.com/.well-known/atomicat-oauth-client.json
{
  "clientId": "app_client_id_gerado",
  "challenge": "desafio_de_dominio_gerado"
}

Retorne JSON público por HTTPS, sem autenticação ou redirecionamentos. Os valores devem corresponder exatamente ao Atomicat.

Etapa 4: Verificar o aplicativo​

Volte a Configurações → Integrações e selecione Verificar. Corrija qualquer erro de DNS, TLS, HTTP ou JSON antes de continuar.

Etapa 5: Configurar o OAuth​

Authorization: https://mcp.atomicat.com.br/oauth/authorize
Token:         https://mcp.atomicat.com.br/oauth/token
Revocation:    https://mcp.atomicat.com.br/oauth/revoke
MCP:           https://mcp.atomicat.com.br/mcp
Resource:      https://mcp.atomicat.com.br
Client type:   Public
PKCE method:   S256

Solicite apenas os escopos necessários, por exemplo sites pages. Todos devem ser permitidos pelo aplicativo.

Etapa 6: Concluir a autorização​

  1. Gere um state e um verifier PKCE criptograficamente aleatórios.
  2. Redirecione para o endpoint de autorização com Client ID, callback exato, escopos, resource, state e desafio S256.
  3. Valide o state no callback.
  4. Troque o código de uso único com o verifier original.
  5. Mantenha access tokens e refresh tokens no servidor sempre que possível.

Etapa 7: Testar o ciclo MCP​

  1. Conecte-se ao endpoint Streamable HTTP com o access token.
  2. Conclua initialize e a notificação initialized.
  3. Execute tools/list e confirme os grupos autorizados.
  4. Execute uma ferramenta de leitura de baixo risco.
  5. Teste a rotação do refresh token.
  6. Desconecte o aplicativo e confirme que a próxima solicitação falha imediatamente.
  7. Autorize novamente e confirme a conexão.

Atualizar escopos ou callbacks​

  • Escopos adicionados: atualize os escopos solicitados, desconecte e autorize novamente.
  • Escopos removidos: desconecte os grants existentes e autorize novamente.
  • Callback alterado: publique o documento na nova origem, atualize o aplicativo e verifique novamente.

Documentação relacionada​

Perguntas frequentes​

Por que meu token tem menos escopos do que o aplicativo?

Os tokens recebem os escopos válidos solicitados explicitamente. Os escopos permitidos definem apenas o máximo.

Por que a verificação falhou?

Confirme que a URL well-known usa HTTPS, é pública, retorna JSON diretamente e contém o Client ID e o desafio exatos.

Preciso reconectar após alterar os escopos?

Sim. Grants existentes mantêm seus escopos originais. Desconecte e autorize novamente.