Como usar o MCP de cartões HubCard: dê a Claude e GPT acesso programático a cartões pré-pago

O MCP (Model Context Protocol) virou o jeito padrão de dar ferramentas a agentes de IA. Claude Desktop, Claude Code, Cursor, Windsurf e a maioria dos clientes modernos consomem MCP nativamente. Esse post é o tutorial prático de como instalar e usar o MCP server do HubCard — para que seu agente de IA possa emitir, listar e cancelar cartões pré-pago sem você escrever uma linha de orquestração.

O que o MCP do HubCard expõe

Sete ferramentas:

Tool	O que faz
`hubcard.emit_card`	Emite um cartão pré-pago novo com limite, MCC, currency, validade
`hubcard.list_cards`	Lista cartões da organização com filtros (status, supplier, tags)
`hubcard.get_card`	Detalhes de um cartão específico (sem expor PAN por default)
`hubcard.update_card`	Atualiza limite, status (pause/resume), tags
`hubcard.cancel_card`	Cancela cartão definitivamente
`hubcard.list_transactions`	Lista transações com filtros (card_id, period, MCC)
`hubcard.get_balance`	Saldo da organização e teto disponível para novas emissões

Cada ferramenta é descrita com schema JSON-Schema, descrição clara, exemplos de uso e limitações. O agente decide quando usar baseado no contexto.

Pré-requisitos

Conta no HubCard (free é suficiente pra começar — 3 cartões ativos, 100 transações/mês).
Uma API key com permissão cards:* e transactions:read. Gere em /dashboard/settings/api-keys.
Node.js 20+ instalado localmente (o MCP server roda como subprocess).

Instalação no Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

E adicione:

{
  "mcpServers": {
    "hubcard": {
      "command": "npx",
      "args": ["-y", "@hubcard/mcp@latest"],
      "env": {
        "HUBCARD_API_KEY": "sk_live_••••",
        "HUBCARD_API_URL": "https://api.hubcard.one"
      }
    }
  }
}

Salve, reinicie o Claude Desktop. Você verá um ícone de ferramentas indicando que o MCP do HubCard está conectado.

Instalação no Claude Code (terminal)

No Claude Code (CLI), basta:

claude mcp add hubcard \
  --command "npx -y @hubcard/mcp@latest" \
  --env HUBCARD_API_KEY=sk_live_••••

Pronto. O /mcp lista o server ativo, e o agente já tem acesso às 7 ferramentas em qualquer sessão.

Instalação no Cursor / Windsurf

Cursor e Windsurf usam o mesmo formato do Claude Desktop. O caminho do config varia, mas o JSON é idêntico.

Primeira conversa com o cartão

Com o MCP rodando, abra uma conversa nova e teste:

Emita um cartão pré-pago dedicado para a OpenAI com limite de US$ 50, válido por 30 dias.

O agente vai:

Identificar que precisa de hubcard.emit_card.
Preencher os parâmetros: supplier: "openai", limit_cents: 5000, currency: "USD", mcc_allow: [5734, 5818], active_until: ISO 30 dias adiante.
Gerar uma Idempotency-Key única.
Chamar a ferramenta.
Retornar o id, pan mascarado e dados de expiração.

Você confirma o uso (ou pré-aprova se está em modo agente). O cartão sai. Sem você ter aberto o painel.

Casos de uso reais

1. Agente de pesquisa que provisiona GPU

Você é um agente de pesquisa. Toda vez que precisar provisionar GPU spot:
1. Estime o custo da job em USD.
2. Use hubcard.emit_card para criar um cartão com esse limite + 10%.
3. Use o cartão no provedor (Lambda, RunPod, Hyperstack).
4. Ao final da job, use hubcard.cancel_card para limpar.
5. Salve o card_id nos logs da execução.

2. Agente operador financeiro

Quando o owner pedir relatório de fornecedores:
1. Use hubcard.list_cards com status=active para listar tudo.
2. Para cada um, use hubcard.list_transactions com period=last_30_days.
3. Agregue por supplier, identifique anomalias (cobrança 2x acima da média).
4. Retorne sumário em markdown.

3. Bot de Slack que emite cartão sob demanda

Em vez de o time pedir cartão por mensagem para o ops, o agente faz:

@bot /card google-ads R$ 50000 mensal

O agente entende, chama hubcard.emit_card, devolve o PAN mascarado e o ID. Quem precisar do PAN completo abre o painel com 2FA.

Segurança e escopo

A API key que você dá ao MCP define o escopo do que o agente pode fazer. Recomendações:

Crie uma API key dedicada para o MCP, não reutilize a key da sua integração de prod.
Use role cards:create:limited se quiser cap automático de limit_cents por cartão.
Configure rate limit na key (e.g., 10 cartões/hora) para conter loops.
Ative alertas para anomalias: cartão emitido fora de horário comercial, valor acima do P95 histórico, etc.
Revogue a key se trocar de máquina, especialmente se tiver compartilhado com claude-code session de outro user.

A chave nunca sai da sua máquina (o MCP server é local), mas tratar como password é a higiene mínima.

Auditoria

Toda chamada do MCP fica registrada no audit log do HubCard com:

caller_metadata.client: indica que veio do MCP (hubcard-mcp/1.x)
caller_metadata.user_agent: nome do cliente MCP (Claude Desktop, Claude Code, etc.)
caller_metadata.hostname (opcional): pra identificar a máquina

Você consegue ver no painel exatamente quando e por qual ferramenta cada cartão foi emitido. Em time, é a forma de saber qual dev/agente fez o quê.

Limitações conhecidas

PAN completo nunca retorna via MCP por default. Para usar o cartão programaticamente, o agente recebe pan_masked (5288 •••• •••• 7102). Para receber o PAN completo, configure --full-pan-mode no MCP server (não recomendado por default).
hubcard.list_transactions retorna até 100 por chamada. Para volume maior, pagine via cursor.
MCP é stateless. Cada call carrega seu próprio contexto. Para fluxos com múltiplas chamadas, o agente reusa o card_id retornado.

Próximos passos

Se você opera agentes em produção, o MCP é a forma mais barata de dar a eles acesso a cartões corporativos pré-pago. Para o padrão por trás disso, leia dê um cartão para seu robô.

Quem está construindo plataforma de agentes (LangChain, LangGraph, AutoGen, frameworks próprios) também tem SDK Python e TypeScript caso prefira integração direta. MCP é o caminho rápido; SDK é o caminho profundo.

Instalou? Manda @hubcard no Twitter/X com print do primeiro cartão emitido pelo agente. Curtimos esse tipo de coisa.