Pular para o conteúdo principal
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.
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: 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 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: 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.
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 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:
Endereço
Cada assistente tem o seu caminho: veja os guias em 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 (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, 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.

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

Escolha as permissões pelo que o assistente vai fazer: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.
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.
Configuração do cliente
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:
Terminal
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:

Claude

Conector personalizado no Claude, com a imagem de cada passo, e o Claude Code no terminal.

ChatGPT

Servidor MCP personalizado no ChatGPT na web.

Cursor e VS Code

Configuração só com o endereço e login no navegador. Outros clientes usam a chave.

Conexões autorizadas

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.

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

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

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. Veja o que cada ferramenta faz.

Escopo no login

No login, a conexão recebe os escopos do nível escolhido. 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 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:
Endereço somente leitura
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, 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.

Ferramentas

Parâmetros, cuidados, erros e limites de cada ferramenta.

Autenticação da API

Escopos, rotação e guarda da chave de API.