> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sinnu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt.
> A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais.
> A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout.
> Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade.
> Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved.
> Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno.
> Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API.

# Servidor MCP

> Conecte um assistente de IA à sua conta sinnu pelo login, autorizando a conexão no painel, ou com a chave de API da empresa.

O servidor MCP da sinnu expõe a API pública como ferramentas do Model Context Protocol (MCP). Conectado a ele, um assistente consulta links de pagamento, transações e clientes da sua empresa e, quando a conexão permite, cria e altera links e clientes.

O servidor é uma camada fina e sem estado: cada chamada de ferramenta vira uma chamada à API pública. Quem decide o que a conexão pode fazer continua sendo a API.

> [!NOTE]
>
> O servidor atende em `https://mcp.sinnu.com.br/mcp` e usa a API de produção: o que o assistente cria ou altera vale na conta da sua empresa. Não há ambiente de testes.

Há duas formas de conectar um assistente:

| | Login | Chave de API |
| - | - | - |
| Como funciona | O assistente abre o navegador, você entra no painel e autoriza a conexão para uma empresa. | A chave `sk_live_...` vai no cabeçalho `Authorization` de cada requisição. |
| Acesso | O nível escolhido na autorização: **Somente leitura** ou **Leitura e escrita**. | Os escopos da chave, com ou sem escrita. |
| Assistentes | Claude, Claude Code, ChatGPT, Cursor e VS Code. | Qualquer cliente MCP que envie um cabeçalho de requisição personalizado. |
| Como encerrar | Revogue em [Conexões autorizadas](https://docs.sinnu.com.br/servidor-mcp/conexoes-autorizadas.md). | Revogue a chave em **Chave de API**. |

Prefira o login: ninguém copia nem guarda uma credencial fixa, e cada conexão aparece no painel com quem a autorizou e o nível de acesso, e pode ser revogada sem afetar as outras. Use a chave para um cliente sem login ou para escolher os escopos um a um, em vez de um dos dois níveis do login.

## Conecte com login

Você precisa ser Titular ou Administrador da empresa no [painel sinnu](https://app.sinnu.com.br) e usar um dos assistentes da tabela acima.

### Escolha o nível de acesso

Na autorização, você escolhe o que o assistente pode fazer na empresa:

| Nível | Escopos da conexão | O que o assistente faz |
| - | - | - |
| **Somente leitura** | `links:read`, `transactions:read` e `customers:read` | Consulta links de pagamento, transações e clientes. Vê as 8 ferramentas de consulta. |
| **Leitura e escrita** | Os três de leitura, mais `links:write` e `customers:write` | Também cria e altera links de pagamento e clientes. Vê as 12 ferramentas: as 8 de consulta e as 4 de escrita. |

A conexão recebe os escopos do nível escolhido, qualquer que seja o pedido do assistente. Nenhum dos dois níveis inclui Estorno, webhooks nem Carteira: o servidor não tem ferramenta que os use.

> [!WARNING]
>
> Com **Leitura e escrita**, o assistente pode criar e alterar links de pagamento e clientes na conta da sua empresa. Leia o que ele vai fazer antes de aprovar uma escrita e aprove as ferramentas de escrita uma a uma, sem a opção de sempre permitir. Se o assistente só vai consultar, escolha **Somente leitura**.

O nível não muda depois da autorização. Para trocar, revogue a conexão em [Conexões autorizadas](https://docs.sinnu.com.br/servidor-mcp/conexoes-autorizadas.md) e conecte de novo pelo assistente, escolhendo o outro nível.

### Passo a passo

**1. Adicione o servidor no assistente**

Informe o endereço do servidor, sem parâmetros e sem cabeçalho:

```text Endereço theme={null}
https://mcp.sinnu.com.br/mcp
```

Cada assistente tem o seu caminho: veja os guias em [Conecte pelo seu assistente](#conecte-pelo-seu-assistente).

**2. Entre no painel**

O assistente abre no navegador a página de autorização da sinnu, no painel (`app.sinnu.com.br`). Se você não estiver logado, entre como de costume: ao terminar, o painel volta para a autorização.

**3. Autorize a conexão**

Confira o nome do assistente e o endereço para onde o navegador volta depois de autorizar. Escolha a empresa e o [nível de acesso](#escolha-o-nível-de-acesso) (**Somente leitura** ou **Leitura e escrita**), confirme com o código enviado ao seu e-mail, quando o painel pedir, e clique em **Autorizar**.

O pedido de autorização vale por 10 minutos e só no navegador em que foi aberto.

**4. Confira a conexão**

O navegador volta ao assistente, que passa a usar a conexão. Peça a ele a conta conectada: ele chama `get_account_context`, que devolve a empresa e os escopos da conexão. Com **Leitura e escrita**, os escopos incluem `links:write` e `customers:write`.

O login funciona só com os assistentes da tabela. Outro cliente MCP é recusado na autorização: para ele, use a chave de API.

## Conecte com a chave de API

A chave é o caminho para um cliente MCP sem login e para quem quer escolher os escopos um a um. Você precisa de um cliente MCP com suporte a servidor remoto por Streamable HTTP e a cabeçalho de requisição personalizado.

**1. Crie uma chave para o assistente**

No [painel](https://app.sinnu.com.br), abra **Desenvolvedor > Chave de API** e use **Nova chave**. Escolha as permissões, confirme a criação com o código enviado por e-mail e copie a chave: ela não é exibida de novo.

![Janela Nova chave de API do painel da sinnu, com as permissões de leitura ligadas: Leitura (tudo), Transações — leitura, Clientes — leitura, Carteira — leitura e Links — leitura.](https://mintcdn.com/sinnu/jEiOLsL1SRJmKQfz/images/servidor-mcp/chave-de-api-leitura.png?fit=max\&auto=format\&n=jEiOLsL1SRJmKQfz\&q=85\&s=354ef6440d469ea5b26043d714331a28)

As permissões de leitura na janela Nova chave de API.

Escolha as permissões pelo que o assistente vai fazer:

| O assistente vai | Permissões |
| - | - |
| Só consultar | As de leitura bastam: **Leitura (tudo)**, ou só as que ele vai usar entre **Links — leitura**, **Transações — leitura** e **Clientes — leitura**. |
| Criar ou alterar links e clientes | Ligue também **Links — escrita** e **Clientes — escrita**. Mantenha as de leitura: as ferramentas de alteração podem ler o registro antes de gravar. |

Deixe **Transações — estorno** e **Webhooks** desligadas: o servidor MCP não tem ferramenta que as use. **Carteira — leitura** também não é usada por nenhuma ferramenta. Veja o [escopo de cada ferramenta](#escopos-e-ferramentas).

**2. Configure o cliente MCP**

Informe o endereço do servidor e envie a chave no cabeçalho `Authorization`. Muitos clientes aceitam uma configuração neste formato; os nomes dos campos variam, então confira a documentação do seu cliente.

```json Configuração do cliente theme={null}
{
  "mcpServers": {
    "sinnu": {
      "type": "http",
      "url": "https://mcp.sinnu.com.br/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}
```

Substitua `sk_live_...` pela chave. Se o cliente oferecer mais de uma forma de autenticação, escolha a opção sem login e informe a chave como cabeçalho de requisição.

**3. Confira a conexão**

Peça ao assistente a conta conectada. Ele chama `get_account_context`, que devolve a empresa, os escopos da chave e se a conexão é somente leitura.

Para conferir sem o assistente, liste as ferramentas com cURL:

```bash Terminal theme={null}
export SINNU_API_KEY='SUA_CHAVE_SECRETA'

curl --request POST 'https://mcp.sinnu.com.br/mcp' \
  --header "Authorization: Bearer $SINNU_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

Com esses cabeçalhos, a resposta vem em `text/event-stream`: o JSON-RPC está na linha `data:`, e `result.tools` traz as ferramentas que a chave enxerga.

## Conecte pelo seu assistente

Para um assistente específico, siga o guia dele:

> [card] [Claude](https://docs.sinnu.com.br/servidor-mcp/conectar-claude.md)
>
> Conector personalizado no Claude, com a imagem de cada passo, e o Claude Code no terminal.

> [card] [ChatGPT](https://docs.sinnu.com.br/servidor-mcp/conectar-chatgpt.md)
>
> Servidor MCP personalizado no ChatGPT na web.

> [card] [Cursor e VS Code](https://docs.sinnu.com.br/servidor-mcp/conectar-outros.md)
>
> Configuração só com o endereço e login no navegador. Outros clientes usam a chave.

> [card] [Conexões autorizadas](https://docs.sinnu.com.br/servidor-mcp/conexoes-autorizadas.md)
>
> Onde ver, revogar e acompanhar as conexões feitas pelo login.

## Endpoint

O transporte é Streamable HTTP sem sessão: cada requisição é independente e leva uma única mensagem JSON-RPC.

| Rota | Comportamento |
| - | - |
| `POST /mcp` | Endpoint MCP. Exige uma credencial: o token do login ou a chave de API. |
| `POST /mcp?readonly=true` | O mesmo endpoint em [modo somente leitura](#modo-somente-leitura), para quem conecta com a chave. |
| `GET` ou `DELETE` em `/mcp` | `405`, com `Allow: POST`. |
| `GET /.well-known/oauth-protected-resource/mcp` | Metadados do recurso protegido (RFC 9728), sem autenticação: o endereço do servidor, o servidor de autorização e os escopos. O mesmo documento responde em `/.well-known/oauth-protected-resource`. |
| `GET /healthz` | `200` com `{"status":"ok"}`, sem autenticação. |

## Autenticação

Toda requisição a `/mcp` leva uma credencial no cabeçalho `Authorization`: o token que o assistente recebe pelo login ou a chave `sk_live_...`.

```http Header theme={null}
Authorization: Bearer SUA_CREDENCIAL
```

### Login

O login segue a autorização OAuth 2.1 da especificação MCP. O assistente conduz o fluxo sozinho; esta seção serve para entender o que acontece e investigar uma falha.

1. Sem credencial, o servidor responde `401`. O cabeçalho `WWW-Authenticate` traz `resource_metadata`, com o endereço dos metadados do recurso, e `scope`, com os escopos do nível **Somente leitura**.
2. Os metadados do recurso apontam o servidor de autorização, `https://auth.sinnu.com.br`, que publica os dele em `/.well-known/oauth-authorization-server`.
3. O assistente se registra pelo registro dinâmico de cliente e abre a autorização no navegador, com PKCE (`S256`) e o parâmetro `resource` igual a `https://mcp.sinnu.com.br/mcp`.
4. Você entra no painel, escolhe a empresa e o nível e autoriza. A conexão recebe os escopos desse nível, mesmo que o assistente tenha pedido outros. O assistente troca o código recebido por um token de acesso, válido por 1 hora, e um token de renovação.
5. O assistente renova o token de acesso sozinho. A cada renovação, o token de renovação anterior deixa de valer, e reapresentar um token de renovação já usado encerra o acesso: o assistente pede login de novo.

Só Titular ou Administrador da empresa autoriza uma conexão. As chamadas da conexão são feitas na empresa escolhida, em nome de quem autorizou. O link de pagamento criado pela conexão sai sem **Vendedor responsável**, como o criado pela chave de API. Os Titulares da empresa recebem um e-mail a cada nova conexão autorizada, com o nível de acesso dela.

A conexão vale enquanto o assistente a usa e expira depois de 30 dias sem uso. Ela termina na hora quando alguém a revoga no painel ou quando quem autorizou deixa de ser membro ativo da empresa, perde o papel de Titular ou Administrador ou tem a conta desativada. Veja [Conexões autorizadas](https://docs.sinnu.com.br/servidor-mcp/conexoes-autorizadas.md).

O servidor MCP não repassa à API o token que recebe do assistente. Ele troca esse token, no servidor de autorização, por uma credencial aceita só pela API e válida pelo tempo que resta do token do assistente. O token do assistente, sozinho, não abre a API.

### Chave de API

Com a chave, o cabeçalho leva `Bearer` e a chave `sk_live_...`. O servidor confere a chave na própria API e repassa essa mesma chave em cada chamada de ferramenta. Ele não tem usuário, senha nem credencial própria para a chave: sem ela, não lê nada.

### Se a conexão falhar

As recusas da conexão voltam em JSON, com `error` e `message`.

| HTTP | `error` | Confira |
| - | - | - |
| `401` | `unauthorized` | Nenhuma credencial foi enviada. Um assistente com login inicia a autorização a partir desta resposta. |
| `401` | `invalid_token` | O cabeçalho não segue `Bearer <credencial>`, ou a credencial é inválida, expirou ou foi revogada. Com login, o assistente renova o token ou pede login de novo. |
| `400` | `invalid_query` | O endereço aceita só o parâmetro `readonly`, uma vez, com `true`, `1`, `false` ou `0`. |
| `413` | `payload_too_large` | O corpo da requisição passa de 64 KiB. |
| `429` | `rate_limited` | Requisições ou credenciais recusadas demais em pouco tempo. Aguarde o intervalo de `Retry-After`, quando o cabeçalho vier. |
| `503` | `temporarily_unavailable` | O servidor não conseguiu validar a credencial agora. Tente de novo em instantes. |

Uma requisição com várias mensagens JSON-RPC (lote) é recusada com `400`: envie uma mensagem por requisição.

### Se a autorização falhar

Na autorização pelo login, o painel explica o motivo da recusa:

| Situação | O que fazer |
| - | - |
| O pedido expirou ou não é deste navegador. | Comece de novo pelo assistente e conclua a autorização em até 10 minutos, no navegador que ele abrir. |
| O pedido já foi respondido. | Volte ao assistente. Se ele não estiver conectado, conecte de novo. |
| Só Titular ou Administrador pode autorizar. | Peça a um Titular ou Administrador da empresa para autorizar, ou para mudar o seu papel na equipe. |
| A conexão com assistentes ainda não está disponível para a empresa. | O login não está disponível para a sua empresa neste momento. Enquanto isso, conecte com a [chave de API](#conecte-com-a-chave-de-api). |
| O assistente não foi reconhecido. | O login aceita só os assistentes da tabela do início desta página. Confira a configuração do assistente pelo guia dele ou use a chave de API. |
| A autorização está indisponível ou deu erro. | Tente de novo em instantes, começando pelo assistente. |

## Escopos e ferramentas

A lista de ferramentas reflete o que a credencial permite: o nível de acesso escolhido no login ou os escopos da chave. Uma conexão sem escopo de escrita não enxerga as ferramentas de escrita. Isso evita que o assistente tente o que a API negaria; quem autoriza cada chamada continua sendo a API.

| Ferramenta | Escopo | Tipo | Nível no login |
| - | - | - | - |
| `get_account_context` | Qualquer credencial válida | Consulta | Os dois |
| `list_payment_links` | `links:read` | Consulta | Os dois |
| `get_payment_link` | `links:read` | Consulta | Os dois |
| `list_payment_link_transactions` | `links:read` | Consulta | Os dois |
| `create_payment_link` | `links:write` | Escrita | **Leitura e escrita** |
| `update_payment_link` | `links:write`; para mudar `status`, também `links:read` | Escrita | **Leitura e escrita** |
| `list_transactions` | `transactions:read` | Consulta | Os dois |
| `get_transaction` | `transactions:read` | Consulta | Os dois |
| `list_customers` | `customers:read` | Consulta | Os dois |
| `get_customer` | `customers:read` | Consulta | Os dois |
| `create_customer` | `customers:write` | Escrita | **Leitura e escrita** |
| `update_customer` | `customers:write` e `customers:read` | Escrita | **Leitura e escrita** |

Veja o que [cada ferramenta](https://docs.sinnu.com.br/servidor-mcp/ferramentas.md) faz.

### Escopo no login

No login, a conexão recebe os escopos do [nível escolhido](#escolha-o-nível-de-acesso). **Somente leitura** vê as 8 ferramentas de consulta; **Leitura e escrita** vê as 12 e já inclui os escopos de leitura que `update_payment_link` e `update_customer` também usam.

### Escopo da chave

Com a chave, as ferramentas seguem os escopos dela. O escopo `read` cobre todos os escopos de leitura e nenhum de escrita. O escopo `transactions:refund` não libera nenhuma ferramenta: o servidor não faz estorno. Veja como [escolher os escopos](https://docs.sinnu.com.br/fundamentos/autenticacao.md#escolha-os-escopos) da chave.

## Modo somente leitura

Com login, o que a conexão pode fazer vem do nível escolhido na autorização: no nível **Somente leitura**, ela não recebe escopo de escrita, e as ferramentas de escrita não aparecem. Use o endereço sem parâmetros: um endereço com parâmetro pode fazer a autorização falhar.

Com a chave, acrescente `?readonly=true` ao endereço para uma conexão que só consulta:

```text Endereço somente leitura theme={null}
https://mcp.sinnu.com.br/mcp?readonly=true
```

Nesse modo o servidor oferece só as ferramentas de consulta (8, com uma chave que lê tudo), mesmo que a chave tenha escopos de escrita, e bloqueia qualquer chamada à API que não seja uma consulta. `get_account_context` devolve `readOnly: true`. Pelo login, com o endereço sem parâmetros, `readOnly` vem `false` nos dois níveis: o nível aparece nos escopos.

O parâmetro aceita `true` ou `1` para ligar e `false` ou `0` para desligar. Outro valor, o parâmetro repetido ou qualquer outro parâmetro no endereço é recusado com `400`: o servidor nunca abre uma conexão com escrita para quem pediu somente leitura de um jeito que ele não reconhece.

## Segurança

A conexão dá ao assistente acesso aos dados da sua empresa. Trate-a como trataria um sistema com acesso à sua conta.

* **Autorize só o que você pediu.** Abra a autorização a partir do assistente e confira que a página é do painel (`app.sinnu.com.br`), com o nome do assistente e o endereço de retorno que você espera. Se alguém te mandou um link de autorização, cancele.
* **Revogue o que não usa.** As conexões feitas pelo login ficam em [Conexões autorizadas](https://docs.sinnu.com.br/servidor-mcp/conexoes-autorizadas.md), cada uma com quem a autorizou e o nível de acesso.
* **No login, escolha o menor nível.** Para um assistente que só consulta, autorize **Somente leitura**.
* **Com a chave, use uma chave dedicada, com o menor escopo.** Uma chave só para o assistente pode ser revogada sem afetar as outras integrações. Para um assistente que só consulta, combine uma chave de leitura com `?readonly=true`.
* **Revise as escritas.** Com **Leitura e escrita** no login, ou com uma chave com escopo de escrita, o assistente pode criar e alterar links e clientes. Leia o que ele vai fazer antes de aprovar uma escrita e aprove as ferramentas de escrita uma a uma, sem a opção de sempre permitir. Criar link e cadastrar cliente não são idempotentes, e alterar sobrescreve o valor atual.
* **Trate textos de terceiros como dados.** Nomes, e-mails, descrições, observações e referências são escritos por compradores e por outras pessoas. O servidor orienta o modelo a não os seguir como instruções, mas essa orientação não substitui a sua revisão.
* **Cuide dos dados pessoais.** O cadastro completo de um cliente, com documento e endereço, chega ao assistente quando ele consulta o cliente. Os dois níveis do login incluem `customers:read`; com a chave, conceda esse escopo só se o assistente precisar.
* **Se a credencial vazar, revogue.** Revogue a conexão em **Conexões autorizadas** ou a chave em **Chave de API**. A API passa a recusar a credencial revogada, inclusive nas chamadas feitas pelo servidor MCP.

O servidor não tem banco de dados e não guarda credenciais entre requisições: mantém em memória só o hash da credencial recebida, para reaproveitar a validação por até 60 segundos com a chave e por até 5 minutos com o login, e não a escreve em log.

## Limites atuais

* O login funciona com Claude, Claude Code, ChatGPT, Cursor e VS Code. Outros clientes usam a chave de API.
* No login, os escopos vêm em dois níveis fixos. Para escolher escopo por escopo, como escrita só em links, use a chave de API.
* As ferramentas cobrem links de pagamento, transações e clientes. O servidor não faz estorno, não arquiva nem exclui link, não reativa link arquivado, não exclui cliente, não consulta o saldo da carteira nem saques e não gerencia webhooks.
* A criação de link é só de valor fixo e pagamento avulso.

> [card] [Ferramentas](https://docs.sinnu.com.br/servidor-mcp/ferramentas.md)
>
> Parâmetros, cuidados, erros e limites de cada ferramenta.

> [card] [Autenticação da API](https://docs.sinnu.com.br/fundamentos/autenticacao.md)
>
> Escopos, rotação e guarda da chave de API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.