Servidor MCP (assistentes de IA)

MCP (Model Context Protocol) é o padrão que deixa um assistente de IA usar ferramentas externas. Com o servidor MCP da ribbo (pacote ribbo-mcp no npm), o seu assistente passa a consultar e operar a sua cobrança: ver assinaturas e pagamentos, conferir o que um cliente tem liberado, trocar plano, estornar, cobrar na hora e gerar links.

Exemplos do que você pode pedir:

• "Quais assinaturas estão em atraso hoje?"
• "O cliente user-123 tem acesso a quê agora?"
• "Gere um link para o cliente trocar o cartão da assinatura sub_...."
• "Estorne R$ 49,90 do pagamento pay_... sem cancelar a assinatura."

Antes de começar

• Node.js 18 ou mais novo (o cliente roda npx -y ribbo-mcp; não precisa clonar nada).
• Uma API key criada em Configurações → API keys. Prefira uma chave read (só consultas); use write apenas se quiser que a IA aja (estornar, cobrar, cancelar, trocar plano).

Nos métodos abaixo a chave não fica escrita em arquivo do projeto. Escolha o seu cliente, do mais fácil para o mais trabalhoso.

1. Claude Code

Opção A, um comando (só para você). A chave fica na configuração local do Claude Code:

claude mcp add ribbo --env RIBBO_API_KEY=bk_sua_chave --env RIBBO_API_BASE=https://api.ribbo.app -- npx -y ribbo-mcp

Confira com claude mcp list ou, dentro do Claude Code, com /mcp.

Opção B, na pasta do projeto (para o time). Com --scope project o Claude Code grava um .mcp.json na raiz do repositório, que pode ir para o git. Nunca escreva a chave nele: use a expansão ${RIBBO_API_KEY} (as aspas simples impedem o terminal de trocar pelo valor).

claude mcp add ribbo --scope project --env 'RIBBO_API_KEY=${RIBBO_API_KEY}' --env RIBBO_API_BASE=https://api.ribbo.app -- npx -y ribbo-mcp

O .mcp.json resultante (pode criar à mão também):

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

Cada pessoa exporta a própria chave antes de abrir o Claude Code:

# macOS / Linux
export RIBBO_API_KEY=bk_sua_chave

# Windows (PowerShell): só a sessão atual
$env:RIBBO_API_KEY = "bk_sua_chave"
# ou permanente para o seu usuário (abra um terminal novo depois)
setx RIBBO_API_KEY "bk_sua_chave"

Na primeira vez o Claude Code pergunta se você confia no servidor do projeto. Aprove.

2. Cursor

Opção A, um clique. Com RIBBO_API_KEY exportada (comandos acima), abra o link de instalação. Ele abre o Cursor e pede para confirmar:

cursor://anysphere.cursor-deeplink/mcp/install?name=ribbo&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInJpYmJvLW1jcCJdLCJlbnYiOnsiUklCQk9fQVBJX0tFWSI6IiR7ZW52OlJJQkJPX0FQSV9LRVl9IiwiUklCQk9fQVBJX0JBU0UiOiJodHRwczovL2FwaS5yaWJiby5hcHAifX0%3D

O config é esta configuração em base64: {"command":"npx","args":["-y","ribbo-mcp"],"env":{"RIBBO_API_KEY":"${env:RIBBO_API_KEY}","RIBBO_API_BASE":"https://api.ribbo.app"}}

Opção B, na pasta do projeto. Crie .cursor/mcp.json; a chave é lida da variável de ambiente com ${env:RIBBO_API_KEY}, então o arquivo pode ir para o git:

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

Exporte RIBBO_API_KEY, reabra o Cursor e confira na página Customize (barra lateral) se o ribbo está ativo.

3. VS Code (Copilot no modo agente)

Crie .vscode/mcp.json. Com inputs e "password": true, o VS Code pede a chave na primeira vez e a guarda de forma segura, fora do arquivo:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ribbo-api-key",
      "description": "API key da Ribbo (bk_...)",
      "password": true
    }
  ],
  "servers": {
    "ribbo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ribbo-mcp"],
      "env": {
        "RIBBO_API_KEY": "${input:ribbo-api-key}",
        "RIBBO_API_BASE": "https://api.ribbo.app"
      }
    }
  }
}

Abra o Chat (Ctrl+Alt+I no Windows/Linux, Ctrl+Cmd+I no macOS), escolha o modo Agent e faça uma pergunta. O VS Code inicia o servidor, pede a chave e pede para você confiar nele.

4. Claude Desktop

O Claude Desktop não lê variáveis do projeto, então a chave vai no arquivo de configuração do app (na sua máquina, fora de qualquer repositório).

1. No Claude Desktop, vá em Settings → Developer → Edit Config (abre o claude_desktop_config.json).
2. Cole o bloco abaixo (se já houver mcpServers, acrescente só a entrada ribbo):

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

3. Salve, feche o Claude Desktop por completo e abra de novo.
4. As ferramentas da ribbo aparecem no ícone de ferramentas da caixa de mensagem.

Ferramentas

Leitura (chave read): check_entitlements, list_subscriptions, get_subscription, get_gateway_events, get_payment, get_customer_subscriptions, get_customer_payments, get_referral_link, list_renewal_campaign_links, get_payment_link, get_order_payment_link.

Escrita (chave write): change_plan, cancel_plan_change, cancel_subscription (na hora ou com at_period_end), undo_cancel_subscription, charge_now, reschedule_subscription, remove_coupon, create_renewal_link, create_payment_method_link, get_renewal_campaign_link, refund_payment, update_customer, update_customer_email.

Não há ferramenta para criar assinatura: ela nasce só no checkout.