Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.gyramais.com.br/llms.txt

Use this file to discover all available pages before exploring further.

Resumo: o MCP da GYRA+ é hospedado pela GYRA+ em https://mcp.gyramais.com.br. Você só configura o cliente (Claude.ai, Claude Desktop, Cursor, etc.) e autentica com as credenciais (clientId + clientSecret) enviadas pelo suporte. Existem duas formas de conectar: custom connector (OAuth), indicado para Claude.ai e Claude Desktop, e stdio local, indicado para Claude Code, Cursor, VS Code e SDKs próprios.

​
Obter credenciais

As credenciais do MCP são as mesmas credenciais de API da sua organização: clientId e clientSecret. Não existe tela no toolbox para gerá-las. Solicite por e-mail: 
atendimento@gyramais.com
Assunto: Credenciais de API / MCP — [nome da organização]
O suporte responde com clientId e clientSecret. Guarde em cofre seguro (1Password, Vault, etc.) — elas dão acesso a todas as tools do MCP e endpoints da API REST.
Credenciais não expiram sozinhas, mas podem ser revogadas e reemitidas pelo suporte a qualquer momento em caso de vazamento. Avise imediatamente se suspeitar de comprometimento.

​
Endpoint do servidor

https://mcp.gyramais.com.br

​
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 uma página de login onde você informa o clientId e clientSecret recebidos do suporte. O Claude volta conectado.
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

Informar clientId e clientSecret

Na página de login da GYRA+, cole as credenciais recebidas do suporte:
  • Client ID
  • Client Secret
Confirmar. Se as credenciais estiverem corretas, você é redirecionado de volta ao Claude com o connector marcado como conectado.
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

VariávelObrigatórioDescrição
GYRA_CLIENT_IDSim (ou GYRA_ACCESS_TOKEN)Client ID recebido do suporte.
GYRA_CLIENT_SECRETSim (ou GYRA_ACCESS_TOKEN)Client Secret recebido do suporte. O MCP troca por um JWT automaticamente e renova antes de expirar.
GYRA_ACCESS_TOKENAlternativaJWT obtido manualmente via POST /auth/authenticate. Estático, você é responsável por renovar.
GYRA_BASE_URLNãoDefault https://gyra-core.gyramais.com.br.
GYRA_PROFILENãoexternal (default) ou internal. Use external para uso normal.
Use uma das duas opções: GYRA_CLIENT_ID + GYRA_CLIENT_SECRET (recomendado, com renovação automática) ou GYRA_ACCESS_TOKEN (estático).

​
Claude Code (CLI)

claude mcp add gyra \
  --command "npx -y @gyramais/mcp-server" \
  --env GYRA_CLIENT_ID=seu_client_id \
  --env GYRA_CLIENT_SECRET=seu_client_secret
Verificar: 
claude mcp list

​
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=seu_client_id
    • GYRA_CLIENT_SECRET=seu_client_secret
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
{
  "mcpServers": {
    "gyra": {
      "command": "npx",
      "args": ["-y", "@gyramais/mcp-server"],
      "env": {
        "GYRA_CLIENT_ID": "seu_client_id",
        "GYRA_CLIENT_SECRET": "seu_client_secret"
      }
    }
  }
}
Reiniciar totalmente o Claude Desktop (Cmd+Q no macOS).

​
VS Code via Continue

~/.continue/config.json: 
{
  "mcpServers": [
    {
      "name": "gyra",
      "command": "npx",
      "args": ["-y", "@gyramais/mcp-server"],
      "env": {
        "GYRA_CLIENT_ID": "seu_client_id",
        "GYRA_CLIENT_SECRET": "seu_client_secret"
      }
    }
  ]
}
Recarregar a janela do VS Code.

​
Cliente customizado (SDK)

Python: 
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="npx",
    args=["-y", "@gyramais/mcp-server"],
    env={
        "GYRA_CLIENT_ID": "seu_client_id",
        "GYRA_CLIENT_SECRET": "seu_client_secret",
    },
)

async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print(tools)
TypeScript: 
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@gyramais/mcp-server'],
  env: {
    GYRA_CLIENT_ID: 'seu_client_id',
    GYRA_CLIENT_SECRET: 'seu_client_secret',
  },
});

const client = new Client({ name: 'meu-cliente', version: '1.0' }, { capabilities: {} });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

​
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.

​
Segurança das credenciais

  • Nunca commitar config com clientSecret em repositório.
  • Em configs JSON, referenciar via variáveis de ambiente do sistema (${env:GYRA_CLIENT_SECRET}) quando o cliente suportar.
  • Em caso de vazamento, acione atendimento@gyramais.com para reemissão — a credencial antiga é invalidada.
  • No fluxo OAuth (Opção 1), as credenciais ficam armazenadas de forma segura no cliente (Claude) e o MCP recebe apenas um token de sessão revogável.

​
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. Para stdio, adicione várias entradas em mcpServers com nomes distintos (ex: gyra-orgA, gyra-orgB) e credenciais específicas. Para custom connector, adicione múltiplos connectors no Claude, cada um com suas credenciais.
Se estiver usando GYRA_ACCESS_TOKEN, chame POST /auth/authenticate com headers gyra-client-id e gyra-client-secret e use o accessToken retornado. Usando GYRA_CLIENT_ID + GYRA_CLIENT_SECRET o MCP faz isso automaticamente.

​
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.