O sintoma (todos com a mesma causa)

• Login termina sem tokenmcp login <servidor> (ou o botão “conectar/autenticar”) termina com algo como “o servidor respondeu, mas nenhum token OAuth foi obtido”.
• Nenhuma janela, nenhuma URLNão aparece navegador, URL de consentimento nem device code — o fluxo simplesmente não começa.
• Só o registro do cliente existeNo diretório de tokens há o *.client.json (resultado do registro dinâmico) e não o *.json com access_token.
• Conectado e 401 em tudo que é da contaFerramentas públicas (busca, catálogo, docs) funcionam; perfil, biblioteca, pedidos e créditos devolvem 401.

A causa: o 401 que nunca chega durante o login

A especificação de autorização do MCP faz o cliente começar o fluxo de forma reativa: ele só descobre o servidor de autorização e começa o OAuth quando recebe de volta

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource"

Um servidor que responde initialize e tools/list sem exigir autenticação (200) e só desafia 401 nas chamadas de conta nunca dispara esse gatilho durante a sondagem de login. A sondagem vê “conectado” e para — e o cliente encerra sem URL, sem consentimento e sem token.

Isso é uma escolha de desenho do servidor (superfície pública + ferramentas de conta privadas), não um servidor quebrado nem um cliente quebrado: o que falha é a interação entre os dois.

Diagnóstico: 4 comandos, nesta ordem

1. O servidor desafia você?Chame uma ferramenta que exige conta e procure 401 + WWW-Authenticate com resource_metadata=. Se vier 200, a ferramenta é pública: escolha outra (perfil / biblioteca / créditos / pedidos). curl -sS -i -m 20 -X POST "$MCP_URL" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"<ferramenta_de_conta>","arguments":{}}}' | head -30
2. Qual servidor de autorização ele anuncia?Procure authorization_servers[] e scopes_supported[]. curl -sS -m 20 "$MCP_URL_ORIGIN/.well-known/oauth-protected-resource"
3. O servidor aceita cliente criado na hora?Procure registration_endpoint (você não precisa registrar cliente à mão), authorization_endpoint, token_endpoint, code_challenge_methods_supported: S256 e token_endpoint_auth_methods_supported: none (cliente público + PKCE). curl -sS -m 20 "$AUTH_SERVER/.well-known/oauth-authorization-server"
4. Algum token chegou ao disco?Registro não é autenticação. Só o *.client.json significa OAuth não concluído. ls -la "$TOKEN_DIR" # ~/.config/<cliente>/mcp-tokens/, ~/.mcp/tokens/

Leitura: (1) 401 com WWW-Authenticate = servidor corretamente configurado, o cliente é que nunca perguntou; (3) com registration_endpoint = o fluxo é automático e não existe cliente para registrar à mão — seja qual for a sugestão do erro do cliente.

O conserto: forçar um 401 com o provedor OAuth vivo

• A. Pelo próprio cliente (melhor)Procure a chave que marca o servidor como OAuth e, se existir, o comando “autenticar agora / login”. Configure e chame uma ferramenta de conta numa sessão normal: a maioria dos clientes roda o fluxo na primeira vez que um 401 volta no meio da sessão. As chaves costumam ser <servidor>.auth: oauth com um bloco oauth (flow: browser ou device, timeout).
• B. Scriptar o challenge (funciona em qualquer cliente)Importe a própria camada de conexão MCP do cliente, envolva a conexão no contexto de OAuth interativo e chame uma ferramenta de conta. O 401 chega, o provedor começa o fluxo e a URL de consentimento é impressa para uma pessoa aprovar.
• C. Manual (último recurso)Registre um cliente no registration_endpoint (JSON com redirect_uris, client_name, grant_types:["authorization_code","refresh_token"], response_types:["code"], token_endpoint_auth_method:"none"), abra o authorization_endpoint com response_type=code, code_challenge (S256) e state, capture o code no redirect de loopback, troque no token_endpoint com o code_verifier e grave o token no formato que o cliente espera.

Os tropeços que custam mais tempo

• Timeout curto cancela a espera do callbackNo fluxo interativo, a espera pelo retorno do navegador acontece dentro da chamada da ferramenta. Se ela estoura, a pessoa aprova, o código se perde e a aprovação tem de ser repetida. Suba o timeout da chamada e o do fluxo OAuth acima do tempo que um humano precisa.
• registration_endpoint presente, token ausenteO arquivo de registro prova só o registro dinâmico. Confira se existe access_token.
• Sessão já aberta não ganha as ferramentasServidores MCP são registrados quando a sessão do agente começa. Depois do token, abra uma sessão nova (ou reinicie o cliente/gateway) — senão você conclui “ainda quebrado” com o conserto já aplicado.
• Verifique com uma chamada real, não com “conectado”Passar na sondagem de login não significa nada aqui: chame uma ferramenta de conta e leia a resposta. Sem essa saída, a autenticação não está verificada — diga isso.
• Refresh tokenDepois do primeiro conserto, guarde o refresh_token e releia o arquivo de token quando o access token expirar, em vez de repetir o fluxo interativo.

Como reportar (formato que não deixa dúvida)

CAUSE: <uma frase: qual passo do fluxo nunca aconteceu>
EVIDENCE: <a linha do 401 + WWW-Authenticate, a linha do registration_endpoint, o caminho do token>
FIX APPLIED: <A | B | C + o que mudou>
VERIFIED: <a chamada de conta exata e o texto devolvido, ou "NOT VERIFIED: <por quê>">
NEXT: <uma única próxima ação>

A última linha é a que mais importa: VERIFIED com a saída crua, ou a confissão de que não deu para verificar. “Conectado” não é evidência.

Comece agora

A skill MCP OAuth Debug traz o diagnóstico completo, o checklist de uma página e a implementação de referência do fix B (scripts/force-oauth-challenge.py), para qualquer cliente MCP e qualquer servidor protegido por OAuth.

Ver a skill MCP OAuth Debug Ver todas as skills

Precisa resolver isso no seu projeto? Setup guiado a partir de R$ 1.500, com o primeiro ciclo rodado junto.