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

# Instalação do MCP

> Conectar o MCP Server da GYRA+ no Claude.ai, Claude Desktop, Cursor, Claude Code e outros clientes MCP.

<Info>
  **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.
</Info>

## 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:

```text theme={null}
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.

<Warning>
  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.
</Warning>

## Endpoint do servidor

```text theme={null}
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.

<Steps>
  <Step title="Abrir a tela de connectors">
    * **Claude.ai**: *Settings > Connectors > Add custom connector*.
    * **Claude Desktop**: *Settings > Connectors > Add custom connector*.
  </Step>

  <Step title="Adicionar o endpoint da GYRA+">
    * **Name**: `GYRA+`
    * **URL**: `https://mcp.gyramais.com.br`

    Salvar.
  </Step>

  <Step title="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+.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Testar">
    Na conversa, pergunte: *"liste minhas últimas 5 análises"*. O Claude escolhe `list_reports` e traz a resposta.
  </Step>
</Steps>

## 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)

```bash theme={null}
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:

```bash theme={null}
claude mcp list
```

### Cursor

<Steps>
  <Step title="Abrir settings">
    Cmd/Ctrl + Shift + J, aba *MCP*.
  </Step>

  <Step title="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`
  </Step>

  <Step title="Salvar e reiniciar o Cursor">
    As tools são reconhecidas automaticamente.
  </Step>
</Steps>

### 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`

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:**

```python theme={null}
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:**

```typescript theme={null}
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](/mcp/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

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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+.
  </Accordion>

  <Accordion title="Funciona offline?">
    Não. O MCP depende do backend da GYRA+, exige internet.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ferramentas disponíveis" icon="toolbox" href="/mcp/ferramentas-disponiveis">
    Catálogo completo de tools.
  </Card>

  <Card title="Casos de uso" icon="lightbulb" href="/mcp/casos-de-uso">
    Exemplos de conversas úteis.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Problemas comuns na instalação.
  </Card>

  <Card title="API Keys e webhooks" icon="key" href="/toolbox/webhooks-e-api-keys">
    Uso das credenciais na API REST.
  </Card>
</CardGroup>