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.
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
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
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)
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.comGYRA_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
VS Code via Continue
~/.continue/config.json:
Cliente customizado (SDK)
Python:Verificação rápida
Depois de conectar, no cliente MCP:- Pergunte: “quais tools da gyra estão disponíveis?” — deve listar
create_report,list_reports,list_policies, etc. - Pergunte: “quais políticas tenho ativas?” — deve chamar
list_policiese retornar a lista.
Sessão e renovação
Você informa as credenciais uma vez. A partir daí o MCP administra a sessão sozinho: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. Quando o stdio for necessário:- Nunca commite a configuração em repositório. Vale para
claude_desktop_config.json,config.jsondo 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
Posso usar a Opção 1 (custom connector) no Cursor ou Claude Code?
Posso usar a Opção 1 (custom connector) no Cursor ou Claude Code?
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).
Preciso instalar algo além do cliente?
Preciso instalar algo além do cliente?
Para a Opção 2,
npx @gyramais/mcp-server é baixado on demand. Se o ambiente não tem npm, instale Node.js 18+.Funciona offline?
Funciona offline?
Não. O MCP depende do backend da GYRA+, exige internet.
Posso conectar múltiplas organizações?
Posso conectar múltiplas organizações?
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.Como renovar o token manualmente?
Como renovar o token manualmente?
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.O agente pode fazer algo que eu não posso?
O agente pode fazer algo que eu não posso?
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.
Preciso pedir credenciais ao suporte?
Preciso pedir credenciais ao suporte?
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.
Uso SSO (Google ou Microsoft). Como conecto?
Uso SSO (Google ou Microsoft). Como conecto?
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.

