Instalação do MCP

Conectar o MCP Server da GYRA+ no Claude.ai, Claude Desktop, Cursor, Claude Code e outros clientes 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:

[e-mail]
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á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

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 [e-mail] 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.