MCP para comerciantes
O MCP da Fluxis permite que um assistente crie links de pagamento, checkouts hospedados e pagamentos cripto diretos com a sua chave de API. Ele fala Streamable HTTP e não guarda sessão.
Endpoints
| Ambiente | URL | Prefixo da chave |
|---|---|---|
| Local | http://localhost:8080/mcp | fxs.dev. |
| Sandbox (staging) | https://mcp.stgfluxis.us/mcp | fxs.stg. |
| Produção | https://mcp.fluxis.us/mcp | fxs.prd. |
GET /.well-known/mcp/server-card.json descreve o servidor quando o MCP está ativo. GET e DELETE em /mcp respondem 405.
Sandbox é o deploy de staging na mainnet. Uma cobrança em sandbox é um pagamento real. Use valores pequenos. Não há simulador de pagamentos.
Autenticação
Envie a mesma chave que você usa na API REST:
x-fluxis-api-keyex-fluxis-api-secret, ouAuthorization: Bearer <chave>:<segredo>
O prefixo da chave precisa corresponder ao host. Uma chave de produção no host de sandbox é recusada.
| Papel | Acesso MCP |
|---|---|
read | Somente tools de leitura (payments:read) |
write | Leitura e tools de criação ou exclusão (payments:read e payments:write) |
Uma credencial inválida responde 401 com {"error":"invalid_token","error_description":"..."} e WWW-Authenticate: Bearer realm="fluxis". OAuth não está disponível.
Cada tool verifica se o ponto de venda pertence à credencial. Uma chave de conta vê apenas essa conta. Uma chave de organização vê as contas do seu alcance.
Tools
Chame fluxis_get_context primeiro.
| Tool | Acesso | Para quê |
|---|---|---|
fluxis_get_context | leitura | Ambiente, dono da chave, cada ponto de venda e se aceita links e checkout, e o POS online padrão |
fluxis_list_points_of_sale | leitura | Pontos de venda que esta chave pode usar |
fluxis_list_payment_links | leitura | Links de pagamento. O status padrão é active |
fluxis_get_payment_link | leitura | Um link por id ou código, com estatísticas e cinco pagamentos recentes |
fluxis_get_payment | leitura | Um pagamento por id, ou o mais novo de uma referência |
fluxis_list_payments | leitura | Pagamentos. Janela padrão: últimos 30 dias UTC, máximo 92 |
fluxis_list_transactions | leitura | Movimentos do livro depois de confirmar um pagamento |
fluxis_get_payment_options | leitura | Ativos cripto que o ponto de venda aceita |
fluxis_create_payment_link | escrita | Link reutilizável para compartilhar com compradores |
fluxis_delete_payment_link | escrita | Exclusão lógica em dois passos |
fluxis_create_checkout | escrita | Página de checkout de uso único |
fluxis_create_crypto_payment | escrita | Solicitação de pagamento cripto direto |
Campos do link de pagamento
name é o nome que o comprador vê. buyer_reference é a sua referência interna de pedido ou fatura. O comprador não a vê como título do produto. Na API REST o mesmo campo se chama external_id.
Se você omitir expiration e expires_in_minutes, o link não vence. Envie no máximo um dos dois. expires_in_minutes vai de 5 a 43200. expiration é um timestamp RFC3339 no futuro.
Confirmação de exclusão
A primeira chamada de fluxis_delete_payment_link não exclui o link. Ela devolve um confirmation_token que dura 300 segundos. Peça confirmação ao usuário e chame a tool de novo com esse token. Excluir um link que já está excluído responde already_deleted.
Idempotência e limites
Passe idempotency_key (8 a 64 letras, dígitos, _ ou -) nas criações. A mesma chave e a mesma entrada repetem o resultado original por 24 horas. A mesma chave com outra entrada responde conflito.
Por credencial e por minuto: 120 leituras, 20 escritas e 10 exclusões. Uma tool limitada responde RATE_LIMITED e retry_after_seconds.
Recursos e prompts
fluxis://docs/quickstartfluxis://docs/payment-statusesfluxis://catalog/payment-optionsfluxis://payments/{payment_id}- Prompts:
fluxis_charge_customer,fluxis_integrate,fluxis_sales_summary
Os links de pagamento também estão na API REST. Veja Links de pagamento.