# 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](https://modelcontextprotocol.io) 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-key` e `x-fluxis-api-secret`, ou
- `Authorization: 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/quickstart`
- `fluxis://docs/payment-statuses`
- `fluxis://catalog/payment-options`
- `fluxis://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](/pt/docs/developers/payment-links).