# Use a documentação no seu editor (MCP)

Fonte: https://lunahia.com.br/docs/mcp

A documentação da Luna tem um servidor MCP público. Ligado ao seu editor ou assistente, a IA busca nos guias e na referência por conta própria, e lê o contrato exato de cada rota antes de escrever o código da integração. O endereço é `https://lunahia.com.br/mcp`.

O servidor é só de leitura, não pede chave e não guarda nada sobre você. Ele lê do mesmo conteúdo que gera esta documentação, os arquivos `.md` de cada página e o `llms-full.txt`: quando um guia ou a [referência da API](https://lunahia.com.br/docs/referencia) muda, o MCP muda junto, sem você atualizar nada. Ele não chama a API da Luna e não envia mensagem; para isso use a [chave de API](https://lunahia.com.br/docs/conta-e-chaves) e a referência.

## As quatro ferramentas

| Ferramenta | O que faz |
| --- | --- |
| `list_pages` | Lista as páginas (guias e referência) com o identificador (`slug`), o título e uma linha de resumo. |
| `read_page` | Devolve o Markdown de uma página, idêntico ao do arquivo `.md` dela. Páginas longas vêm em pedaços; a resposta diz qual `offset` pedir para continuar. |
| `search_docs` | Busca nos guias, nas rotas, nos eventos de webhook e nos códigos de erro, e devolve as melhores seções com `slug`, âncora, link e um trecho. |
| `get_endpoint` | Devolve a operação OpenAPI de uma rota (`method` e `path`), com os esquemas já resolvidos: é o contrato exato para gerar o código do cliente. Rotas grandes aceitam `part` (`request` ou `responses`) para trazer só metade. |

Todas aceitam `lang`: `pt` (padrão) ou `en`. Cada resposta tem no máximo 24 000 caracteres; passando disso o texto é cortado com um aviso, e `read_page` e `get_endpoint` aceitam `offset` para pedir o resto.

## Conectar o seu cliente

Em todos, o nome `luna-docs` é só um rótulo; troque se quiser. Não há cabeçalho de autenticação para configurar.

### Claude Code

Uma linha no terminal:

```bash
claude mcp add --transport http luna-docs https://lunahia.com.br/mcp
```

Por padrão a configuração vale só para você, no projeto atual. Com `--scope user` ela vale em todos os seus projetos, e com `--scope project` o comando grava o `.mcp.json` abaixo na raiz do repositório, para o time inteiro usar. Confira com `claude mcp list` ou, dentro do Claude Code, com `/mcp`.

.mcp.json

```json
{
  "mcpServers": {
    "luna-docs": {
      "type": "http",
      "url": "https://lunahia.com.br/mcp"
    }
  }
}
```

### Cursor

Crie `.cursor/mcp.json` no projeto, ou `~/.cursor/mcp.json` para valer em todos:

.cursor/mcp.json

```json
{
  "mcpServers": {
    "luna-docs": {
      "url": "https://lunahia.com.br/mcp"
    }
  }
}
```

### VS Code

Crie `.vscode/mcp.json`. Atenção: o VS Code usa a chave `servers`, e não `mcpServers`. Também dá para usar o comando **MCP: Add Server** da paleta de comandos, escolher **HTTP** e colar o endereço.

.vscode/mcp.json

```json
{
  "servers": {
    "luna-docs": {
      "type": "http",
      "url": "https://lunahia.com.br/mcp"
    }
  }
}
```

### Claude (conector remoto)

No claude.ai, vá em **Customize > Connectors**, clique em **Add** e em **Add custom connector**, dê um nome (por exemplo `Luna docs`) e cole `https://lunahia.com.br/mcp` como endereço. Em autenticação, escolha **No sign in**. Planos Team e Enterprise: quem adiciona é o administrador da organização, em **Organization settings > Connectors**. Depois, em cada conversa, ative o conector pelo botão **+**.

### ChatGPT

O ChatGPT aceita servidor MCP remoto pelo **modo desenvolvedor**, nas configurações de apps e conectores: crie um app MCP, cole `https://lunahia.com.br/mcp` como endereço e escolha **sem autenticação**. Depois, ative-o na conversa. Esses menus mudam de lugar e de nome entre versões e planos, e a Helsen não conseguiu conferir o passo a passo na documentação da OpenAI, então siga o que o seu ChatGPT mostrar.

> Outros clientes que falam MCP por HTTP funcionam do mesmo jeito: basta o endereço. O Claude e o ChatGPT se conectam da nuvem deles, então só enxergam o servidor publicado, nunca um `localhost`.

## O que pedir à IA

- “Usando a documentação da Luna, escreva em Node o código que envia um template aprovado.”
- “Qual o contrato exato de `POST /v1/messages`? Gere os tipos em TypeScript.”
- “Como confiro a assinatura de um webhook da Luna? Mostre um exemplo em Python.”
- “O que significa o erro `window_closed` e o que eu faço?”

## Detalhes técnicos

- Transporte **Streamable HTTP**, sem sessão: cada chamada é um `POST` com uma mensagem JSON-RPC, e a resposta é um JSON. `GET` e `DELETE` respondem `405`.
- Versões do protocolo: 2025-03-26, 2025-06-18, 2025-11-25 (com `initialize`) e 2026-07-28 (sem handshake, com `server/discover`).
- CORS aberto, para clientes de navegador, e nenhuma credencial: não há cookie nem chave a proteger.

Para testar sem cliente nenhum, chame uma ferramenta direto:

```bash
curl -X POST https://lunahia.com.br/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"enviar template"}}}'
```
