ribbo-mcp

Servidor MCP (Model Context Protocol) da Ribbo. Conecta o seu assistente de IA (Claude Desktop, Cursor, etc.) à API de cobrança recorrente da Ribbo e o transforma em um operador: a IA passa a executar ações reais — criar e gerenciar assinaturas, consultar entitlements, estornar pagamentos, cobrar na hora e gerar links de pagamento/renovação.

Autenticação pela sua API key de tenant (prefixo bk_), gerada no painel em Desenvolvedores → API keys. O servidor é um cliente fino da API pública: nenhum segredo fica no código — você fornece a sua chave por variável de ambiente.

Requisitos

• Node.js 18+

• Uma API key da Ribbo (bk_…). Use uma chave de escopo read para só consultar, ou write para deixar a IA agir (estornar, cobrar, cancelar, etc.).

Related MCP server: Agent Billy MCP Server

Instalação

A forma mais rápida — sem clonar nada — é apontar o seu cliente de IA para o pacote via npx. Para testar no terminal:

# direto do GitHub (funciona já):
npx -y github:andrespadeto/ribbo-mcp

# ou, depois de publicado no npm:
npx -y ribbo-mcp

Ele fica aguardando no stdio — é assim que um servidor MCP roda. Quem "conversa" com ele é o seu cliente de IA (abaixo), não o terminal. Para sair: Ctrl+C.

Configuração

Duas variáveis de ambiente:

Claude Desktop

Em claude_desktop_config.json (menu → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ribbo": {
      "command": "npx",
      "args": ["-y", "github:andrespadeto/ribbo-mcp"],
      "env": {
        "RIBBO_API_KEY": "bk_sua_chave_aqui",
        "RIBBO_API_BASE": "https://api.ribbo.app"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas da Ribbo aparecem no ícone de ferramentas do chat.

Cursor

Em .cursor/mcp.json (no projeto) ou nas configurações globais de MCP, use o mesmo bloco mcpServers acima.

Depois de publicado no npm, troque "github:andrespadeto/ribbo-mcp" por "ribbo-mcp".

Ferramentas

Leitura (a chave read basta):

Escrita (exigem chave write — movem dinheiro/estado):

Segurança

• A chave identifica e isola o seu tenant — dados de outros tenants nunca são acessíveis.

• As ferramentas de escrita movem dinheiro/estado (estorno, cobrança, cancelamento). Use uma chave read quando a IA só precisa consultar, e uma write apenas onde for agir.

• A chave vive no env do cliente MCP (na sua máquina) — trate como segredo; nunca a comite.

• O código é aberto e não contém segredos: toda credencial vem do ambiente.

Convenções da API

Dinheiro em centavos (inteiro); IDs com prefixo (sub_, cus_, pay_, ord_…); datas em ISO-8601 UTC. Erros chegam como Erro <status>: {…}. O contrato completo (OpenAPI 3.1) fica em GET {RIBBO_API_BASE}/v1/public/schema/.

Desenvolvimento

git clone https://github.com/andrespadeto/ribbo-mcp.git
cd ribbo-mcp
npm install          # o "prepare" compila o TypeScript para dist/
cp .env.example .env # preencha RIBBO_API_KEY e RIBBO_API_BASE
npm run dev          # build + start

• Código-fonte em src/ (TypeScript ESM). src/index.ts registra as ferramentas; src/api.ts é o cliente HTTP (Bearer).

• O build (dist/) é gerado por npm run build e não é versionado.

Licença

MIT © Ribbo