Skip to main content
Resumo: o MCP da GYRA+ é hospedado por nós em https://mcp.gyramais.com.br. Você configura só o cliente (Claude.ai, Claude Desktop, Cursor, etc.) e entra com o seu próprio login da plataforma: o mesmo e-mail e senha que você usa no toolbox. Nada de credencial separada, nada de abrir chamado. E, principalmente: o agente enxerga exatamente o que você enxerga.

Entre com o seu login

Não existe credencial de MCP para pedir ao suporte. Suas credenciais são as que você já tem: Os nomes dos campos vêm do padrão OAuth de client credentials, mas o conteúdo é o seu login. É a mesma autenticação da plataforma, pela mesma rota.

Por que isso importa

Porque o permissionamento vem junto. O agente não é um usuário privilegiado: ele é você.

Mesmo escopo, sem configuração

Se o seu perfil só enxerga os relatórios que você mesmo criou, o agente também só enxerga esses. Se você não tem permissão para gerenciar políticas, o agente não gerencia.

Auditoria com nome e sobrenome

Toda ação disparada pelo agente fica registrada como sua, não como “a integração”. Uma análise criada por conversa é rastreável ao usuário que a pediu.

Onboarding em segundos

Um novo analista conecta o MCP sozinho, com a senha que já tem. Sem ticket, sem espera, sem uma credencial compartilhada circulando pelo time.

Offboarding que funciona

Desligou o usuário na plataforma? O acesso do agente dele morre junto. Não sobra credencial órfã ativa em nenhum laptop.
O contraste é com o modelo de credencial de serviço: uma chave da organização, com escopo amplo, emitida por chamado e compartilhada entre pessoas. Esse modelo continua existindo para integrações servidor a servidor (ver API Keys). Para o MCP, que é uma ferramenta de pessoa, o login da pessoa é o modelo certo.
Se você acessa a plataforma por SSO (Google ou Microsoft) e nunca definiu uma senha, este fluxo não funciona até você cadastrar uma. Fale com o administrador da sua organização.

Endpoint do servidor

Opção 1, Custom connector no Claude.ai ou Claude Desktop (recomendado)

Fluxo via OAuth: você adiciona o endpoint uma única vez, clica em Autenticar e a GYRA+ abre a própria página de login. Você entra com e-mail e senha, e o Claude volta conectado. É a opção mais segura: a sua senha é digitada na página da GYRA+ e nunca fica gravada em arquivo de configuração.
1

Abrir a tela de connectors

  • Claude.ai: Settings > Connectors > Add custom connector.
  • Claude Desktop: Settings > Connectors > Add custom connector.
2

Adicionar o endpoint da GYRA+

  • Name: GYRA+
  • URL: https://mcp.gyramais.com.br
Salvar.
3

Autenticar

Clicar em Authenticate ao lado do connector recém-adicionado. O Claude abre uma aba no navegador com a página de login da GYRA+.
4

Entrar com o seu login

Na página de login da GYRA+, informe:
  • Client ID: o seu e-mail de acesso ao toolbox
  • Client Secret: a sua senha
Confirmar. Você é redirecionado de volta ao Claude com o connector conectado, e o agente passa a operar com as suas permissões.
5

Testar

Na conversa, pergunte: “liste minhas últimas 5 análises”. O Claude escolhe list_reports e traz a resposta.

Opção 2, Stdio local (Claude Code, Cursor, VS Code, SDKs)

Para clientes que rodam o MCP como processo local via stdio, use o pacote @gyramais/mcp-server (binário gyra-mcp) e passe as credenciais como variáveis de ambiente.

Variáveis de ambiente

Use uma das duas opções: GYRA_CLIENT_ID + GYRA_CLIENT_SECRET (recomendado, com renovação automática) ou GYRA_ACCESS_TOKEN (estático, expira em 24h).

Claude Code (CLI)

Verificar:

Cursor

1

Abrir settings

Cmd/Ctrl + Shift + J, aba MCP.
2

Add new MCP server

  • Name: gyra
  • Type: command
  • Command: npx -y @gyramais/mcp-server
  • Env:
    • GYRA_CLIENT_ID=voce@suaempresa.com
    • GYRA_CLIENT_SECRET=sua_senha
3

Salvar e reiniciar o Cursor

As tools são reconhecidas automaticamente.

Claude Desktop, config manual via stdio

Se preferir configurar via arquivo em vez de usar o custom connector:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Reiniciar totalmente o Claude Desktop (Cmd+Q no macOS).

VS Code via Continue

~/.continue/config.json:
Recarregar a janela do VS Code.

Cliente customizado (SDK)

Python:
TypeScript:

Verificação rápida

Depois de conectar, no cliente MCP:
  1. Pergunte: “quais tools da gyra estão disponíveis?” — deve listar create_report, list_reports, list_policies, etc.
  2. Pergunte: “quais políticas tenho ativas?” — deve chamar list_policies e retornar a lista.
Se as tools não aparecem, consulte Troubleshooting.

Sessão e renovação

Você informa as credenciais uma vez. A partir daí o MCP administra a sessão sozinho:
É por isso que GYRA_CLIENT_ID + GYRA_CLIENT_SECRET é a configuração recomendada, e não GYRA_ACCESS_TOKEN. Com as credenciais, o MCP se recupera sozinho de qualquer interrupção de sessão. Com um token estático, ele fica sem como renovar e a conexão simplesmente para de funcionar depois de 24h.

Segurança

A sua senha vira uma sessão de 24 horas e é isso que trafega nas chamadas. Ainda assim, trate a configuração com o mesmo cuidado que você trata a senha em si.
No modo stdio, a senha fica em texto plano no arquivo de configuração do cliente. Prefira a Opção 1 (custom connector) sempre que o seu cliente suportar: nesse fluxo a senha é digitada na página da GYRA+ e o cliente guarda apenas um token de sessão revogável.
Quando o stdio for necessário:
  • Nunca commite a configuração em repositório. Vale para claude_desktop_config.json, config.json do Continue e afins.
  • Referencie variáveis de ambiente do sistema (${env:GYRA_CLIENT_SECRET}) em vez de escrever a senha no JSON, quando o cliente suportar.
  • Não compartilhe a configuração com colegas. Cada pessoa conecta com o próprio login: é isso que faz o permissionamento e a auditoria funcionarem.
  • Trocou a senha na plataforma? Atualize a configuração do MCP. As sessões em aberto continuam válidas até expirar, e a próxima renovação falha com a senha antiga.
  • Suspeita de comprometimento? Troque a senha no toolbox. Isso invalida a credencial em todos os clientes conectados, sem depender de chamado.

Perguntas frequentes

Hoje o custom connector com OAuth é suportado no Claude.ai e Claude Desktop. Cursor, Claude Code e VS Code usam configuração stdio local (Opção 2).
Para a Opção 2, npx @gyramais/mcp-server é baixado on demand. Se o ambiente não tem npm, instale Node.js 18+.
Não. O MCP depende do backend da GYRA+, exige internet.
Sim, desde que você tenha uma conta em cada uma. Na plataforma, um e-mail pertence a uma única organização, e não há seleção de organização no login: a sessão já vem amarrada à organização daquele usuário.Então cada entrada precisa de um e-mail diferente. Para stdio, adicione várias entradas em mcpServers com nomes distintos (ex: gyra-orgA, gyra-orgB), cada uma com as credenciais da conta correspondente. Para custom connector, adicione múltiplos connectors no Claude e autentique cada um com a sua conta.Repetir o mesmo e-mail em duas entradas não conecta duas organizações: as duas apontam para a mesma.
Só é necessário no modo GYRA_ACCESS_TOKEN: chame POST /auth/authenticate com os headers gyra-client-id (seu e-mail) e gyra-client-secret (sua senha) e use o accessToken retornado, válido por 24h. Com GYRA_CLIENT_ID + GYRA_CLIENT_SECRET o MCP faz isso sozinho, inclusive se a sessão cair no meio do caminho.
Não. A sessão do MCP carrega o seu usuário e o seu papel. Se você não enxerga um relatório no toolbox, o agente também não enxerga; se você não tem permissão para gerenciar políticas, a tool correspondente falha do mesmo jeito que a tela falharia.
Não para o MCP: use o seu login da plataforma. Credenciais emitidas pelo suporte continuam existindo para integrações servidor a servidor na API REST, que é outro caso de uso. Ver API Keys.
Este fluxo exige senha. Se você nunca definiu uma, fale com o administrador da sua organização antes de configurar o MCP.

Próximos passos

Ferramentas disponíveis

Catálogo completo de tools.

Casos de uso

Exemplos de conversas úteis.

Troubleshooting

Problemas comuns na instalação.

API Keys e webhooks

Uso das credenciais na API REST.