Instalação do MCP

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.

Abrir a tela de connectors

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

Adicionar o endpoint da GYRA+

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

Salvar.

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

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.

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ável	Obrigatório	Descrição
`GYRA_CLIENT_ID`	Sim (ou `GYRA_ACCESS_TOKEN`)	Client ID recebido do suporte.
`GYRA_CLIENT_SECRET`	Sim (ou `GYRA_ACCESS_TOKEN`)	Client Secret recebido do suporte. O MCP troca por um JWT automaticamente e renova antes de expirar.
`GYRA_ACCESS_TOKEN`	Alternativa	JWT obtido manualmente via `POST /auth/authenticate`. Estático, você é responsável por renovar.
`GYRA_BASE_URL`	Não	Default `https://gyra-core.gyramais.com.br`.
`GYRA_PROFILE`	Não	`external` (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

Abrir settings

Cmd/Ctrl + Shift + J, aba MCP.

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

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:

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_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

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?

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?

Não. O MCP depende do backend da GYRA+, exige internet.

Posso conectar múltiplas organizações?

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.

Como renovar o token manualmente?

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.

Primeiros Passos

Conceitos Fundamentais

Guia do Toolbox

Fontes de Dados

Guias

Casos de Uso

MCP Server

Referência da API

Dicionário de Dados

Integrações

Referência

Obter credenciais

Endpoint do servidor

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

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

Variáveis de ambiente

Claude Code (CLI)

Cursor

Claude Desktop, config manual via stdio

VS Code via Continue

Cliente customizado (SDK)

Verificação rápida

Segurança das credenciais

Perguntas frequentes

Próximos passos

Ferramentas disponíveis

Casos de uso

Troubleshooting

API Keys e webhooks

​Obter credenciais

​Endpoint do servidor

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

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

​Variáveis de ambiente

​Claude Code (CLI)

​Cursor

​Claude Desktop, config manual via stdio

​VS Code via Continue

​Cliente customizado (SDK)

​Verificação rápida

​Segurança das credenciais

​Perguntas frequentes

​Próximos passos

Ferramentas disponíveis

Casos de uso

Troubleshooting

API Keys e webhooks

Obter credenciais

Endpoint do servidor

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

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

Variáveis de ambiente

Claude Code (CLI)

Cursor

Claude Desktop, config manual via stdio

VS Code via Continue

Cliente customizado (SDK)

Verificação rápida

Segurança das credenciais

Perguntas frequentes

Próximos passos