convez.ai
MCP ServerFinanceiroAvançado
southpay

Southpay MCP Server

southpay/southpay-mcp

Gateway cripto Southpay acessível via MCP para IA gerenciar pagamentos

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para gateway de pagamentos cripto Southpay, permitindo que agentes IA gerenciem lojas de merchants (pagamentos, tokens, saques, reembolsos) via protocolo padrão. Funciona como proxy seguro da API HTTP, sem guardar secrets e com controle de autorização fail-closed.

Instalação

$npx convez-ai southpay/southpay-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de processamento de pagamentos cripto em lojas online
  • Gestão remota de saldos e tokens aceitos por agents IA
  • Integração de saques e reembolsos cripto em fluxos de atendimento

Veredito

Implementação sólida de servidor MCP para fintech cripto, com design seguro (fail-closed, sem secrets em contexto) e 18 ferramentas bem-documentadas. Exige conhecimento técnico de cripto e MCP, mas oferece integração profissional de pagamentos blockchain em agentes IA.

README

A tradução para o português deste README ainda está na fila.

southpay-mcp

A remote Model Context Protocol (MCP) server that lets an AI agent drive a Southpay merchant store: create and track payments, manage accepted crypto assets, check balances, issue refunds, and disburse payouts, all over a single hosted URL.

Southpay is a crypto payment gateway. The server is a thin proxy to the Southpay HTTP API with no business logic of its own. It holds no secrets: the only credential is the merchant's scoped agent key (spa_live_... / spa_test_...), sent per request and validated server-side by Southpay. Money movement (payouts, refunds, accepted-token changes) is fail-closed and authorization-gated by Southpay; every tool returns plain JSON and surfaces failures, including the gated denials, as data under an error key with a human-readable message rather than raising, so the agent can read the denial and respond.

It runs as a Cloudflare Worker built on McpAgent (Cloudflare Agents SDK), served over the Streamable HTTP transport at /mcp. Each session is backed by a Durable Object that can hold a key set via the login tool.

Connect a client

Point any MCP client at the hosted endpoint and attach the agent key as a Bearer token:

{
  "mcpServers": {
    "southpay": {
      "url": "https://mcp.southpay.io/mcp",
      "headers": {
        "Authorization": "Bearer spa_live_xxx"
      }
    }
  }
}

Each tool resolves the key as: the login key for the session, then the Bearer token. If neither is present it returns { "error": "not_connected" }. Prefer the Bearer header for a live key, since a key pasted into the login tool passes through the model context.

Scopes on the credential determine which tools are reachable: payments tools need payments:read / payments:write; token, balance, and payout tools need assets:read / assets:write / payouts:read / payouts:write. With those scopes the gated tools still return a fail-closed mandate_required / payout_controls_required denial until a HumanOS authorization provider or spend limit is configured. That denial is expected.

Tools

Eighteen tools. Full reference (arguments, return shape, scope, and which tools are authorization-gated) is in TOOLS.md.

ToolPurposeGated
loginPaste an agent key to connect this session (alternative to the Bearer header)
logoutForget the session's pasted key
get_accountWhoami: store, mode (live/test), agent scopes, auth provider
create_paymentCharge a fiat amount; returns deposit address(es) and crypto amount
get_paymentLook up a payment by id
list_paymentsList payments; resolve one by reference
wait_for_paymentBlock until a payment is done (terminal), polling server-side
cancel_paymentCancel a pending intent
refund_paymentRefund a payment (full or partial)yes
list_refundsList a payment's refunds
list_tokensList accepted and available crypto assets
get_balanceCrypto balances per asset plus a fiat settlement value
set_tokenEnable or disable an accepted tokenyes
create_payoutDisburse crypto to an external addressyes
get_payoutLook up a payout by id
list_payoutsList payouts
get_payout_limitsPer-asset payout spend caps and today's remaining headroom
research_tokenPublic CoinGecko market data (no credential)

Security model

  • Fail-closed. refund_payment, set_token, and create_payout are denied server-side unless a HumanOS mandate or a spend limit on the asset authorizes the action. The denial comes from the authorization layer, not a scope error.
  • Errors as data. Tool failures are returned under an error key with a friendly message, never raised, so a client reads the denial as a normal result and can respond.
  • Scoped credential. The agent key carries only the scopes it was issued; out-of-scope calls are rejected by the backend.
  • No stored secrets. The Worker holds no credential; the per-request agent key is the only one, validated by Southpay.
  • Idempotency. create_payment, refund_payment, and create_payout send an Idempotency-Key per request.

Develop and deploy

Pushing to main auto-deploys the Worker via Cloudflare Workers Builds. The GitHub repo is connected in the Cloudflare dashboard (Workers & Pages → southpay-mcp → Settings → Builds) with the production branch set to main and the root directory to cloudflare-worker; Cloudflare runs wrangler deploy on each push. Shipping a tool change is just merging to main, with no manual deploy step and no API token or GitHub secret to manage. (.github/workflows/ci.yml still typechecks every push and PR.)

To work on it locally or deploy by hand:

cd cloudflare-worker
npm install
npm run typecheck
npx wrangler deploy --dry-run   # validate
npx wrangler deploy             # ship manually

The base URL defaults to https://api.southpay.io and is overridable via the SOUTHPAY_BASE_URL var in cloudflare-worker/wrangler.jsonc. See cloudflare-worker/README.md for Worker details.

Note: deploying updates the server, but MCP clients cache the tool list per session, so a brand-new chat (or re-adding the connector) is what surfaces new tools to an already-connected client. The server advertises listChanged, but a fresh session is the reliable way to pick up changes.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados