Ir para o conteúdo

Clientes MCP

O Nodexa expõe tools compatíveis com MCP pela interface admin. Clientes MCP conectam no domínio do admin, não diretamente no backend.

Endpoint

Use este endpoint para as tools nativas do Nodexa:

https://your-admin.example.com/mcp-gateway/nodexa

Para testes locais:

http://localhost:4000/mcp-gateway/nodexa

Não adicione /api nesse caminho. A interface admin faz proxy de /mcp-gateway/* para o backend e mantém a URL do backend privada.

Autenticação

Clientes MCP autenticam com tokens bearer OAuth padrão. O gateway publica OAuth Protected Resource Metadata em:

https://your-admin.example.com/mcp-gateway/nodexa/.well-known/oauth-protected-resource

O client do Keycloak usado por clientes MCP é:

nodexa-mcp

Esse client deve ser um client OAuth público usando Authorization Code + PKCE.

Configuração no Keycloak

Crie o client OAuth do MCP no mesmo realm do Keycloak usado pelo backend do Nodexa.

No Nodexa Cloud, o issuer do realm é:

https://auth.nodexa.cloud/realms/nodexa-cloud

No Keycloak Admin Console:

  1. Selecione o realm nodexa-cloud.
  2. Abra Clients.
  3. Crie ou atualize um client com Client ID nodexa-mcp.
  4. Use OpenID Connect.
  5. Defina Client authentication como Off. Este deve ser um client público.
  6. Ative Standard flow.
  7. Desative Direct access grants em produção.
  8. Defina PKCE Code Challenge Method como S256.
  9. Adicione os redirect URIs válidos:
http://localhost:*
http://127.0.0.1:*

Para testes locais com Claude Code, o redirect URI usa uma porta localhost aleatória, por exemplo:

http://localhost:55042/callback

O wildcard acima permite essas portas dinâmicas de callback.

Se o Keycloak ainda rejeitar o redirect durante o teste, adicione o callback URI exato exibido no erro do navegador, por exemplo:

http://localhost:56963/callback

Defina Web origins como:

+

ou explicitamente:

http://localhost:*
http://127.0.0.1:*

Protocol Mappers

O access token emitido para clientes MCP precisa conter os mesmos claims de organização e audiência que o backend valida.

Adicione um mapper Group Membership:

Configuração Valor
Mapper type Group Membership
Token claim name groups
Add to access token On
Full group path On

Isso permite que o backend derive a organização a partir de paths de grupo como:

/nanndoj

Adicione um mapper Audience para que tokens emitidos para nodexa-mcp sejam aceitos pelo backend:

Configuração Valor
Mapper type Audience
Included Client Audience nodexa-cloud-backend
Add to access token On

O backend também deve aceitar o client MCP como audiência adicional:

OIDC_CLIENT_ID=nodexa-cloud-backend
OIDC_EXTRA_AUDIENCES=nodexa-mcp
OIDC_VALIDATE_AUDIENCE=true
OIDC_GROUPS_CLAIM=groups

Se o client ID do seu backend for diferente, use esse client ID no mapper de audiência e em OIDC_CLIENT_ID.

Claude Code

Remova qualquer configuração MCP antiga do Nodexa e adicione o novo endpoint do gateway:

claude mcp remove nodexa -s local
claude mcp add-json nodexa '{"type":"http","url":"http://localhost:4000/mcp-gateway/nodexa","oauth":{"clientId":"nodexa-mcp"}}' -s local

Em produção, troque a URL pelo domínio do admin:

claude mcp add-json nodexa '{"type":"http","url":"https://your-admin.example.com/mcp-gateway/nodexa","oauth":{"clientId":"nodexa-mcp"}}' -s local

Verifique a URL configurada:

claude mcp get nodexa

No primeiro uso, o Claude Code deve iniciar o fluxo OAuth e redirecionar você para o Keycloak.

Teste HTTP Rápido

Sem token, o endpoint deve retornar 401 Unauthorized e incluir um header WWW-Authenticate apontando para a URL de metadata:

curl -i -X POST http://localhost:4000/mcp-gateway/nodexa \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Troubleshooting

Keycloak mostra client not found

Isso significa que o Keycloak não encontrou um client ativo com:

client_id=nodexa-mcp

no realm configurado. Verifique se o client existe no realm nodexa-cloud e se o client ID é exatamente nodexa-mcp.

Keycloak mostra invalid redirect_uri

Adicione o callback URI usado pelo cliente MCP. O Claude Code usa uma porta localhost aleatória:

http://localhost:*
http://127.0.0.1:*

Se você configurou http://localhost:*/callback, substitua por http://localhost:*. O wildcard do Keycloak é mais confiável quando o * fica no final do padrão da URI. Você também pode adicionar temporariamente a URI exata da página de erro, por exemplo http://localhost:56963/callback.

O backend rejeita o token

Verifique os claims do access token. Ele precisa incluir:

  • groups, com o path do grupo da organização do usuário
  • uma audiência aceita pelo backend, normalmente nodexa-cloud-backend e/ou nodexa-mcp

Decodifique o token localmente:

echo "$TOKEN" | jq -R 'split(".")[1] | @base64d | fromjson | {aud, azp, groups}'

A metadata OAuth aponta para o host errado

A resposta de metadata deve usar o domínio do admin, não o domínio do backend:

{
  "resource": "http://localhost:4000/mcp-gateway/nodexa"
}

Se aparecer localhost:3001, a request está chegando diretamente no backend em vez de passar pelo proxy do admin.