Plugin para Claude e Codex

A TroqPay fornece um plugin MCP para agentes criarem checkouts, consultarem checkouts, lerem saldo e operarem saques quando isso for explicitamente pedido.

O plugin usa um cliente HTTP mínimo embutido e a mesma API pública da TroqPay. A chave da API fica em variável de ambiente, não como argumento de ferramenta.

Ferramentas

Ferramenta	O que faz
`troqpay_create_checkout`	Cria um checkout Pix.
`troqpay_get_checkout`	Consulta um checkout por ID.
`troqpay_get_balance`	Consulta o saldo agregado da conta.
`troqpay_create_withdrawal`	Cria uma solicitação de saque em produção quando saques estão habilitados.
`troqpay_get_withdrawal`	Consulta um saque por ID quando saques estão habilitados.

Variáveis de ambiente

export TROQPAY_API_KEY="trq_test_xxxxxxxxx"
export TROQPAY_BASE_URL="https://api.troqpay.com"

Para staging:

export TROQPAY_BASE_URL="https://api.staging.troqpay.com"

Para expor ferramentas de saque no agente, habilite explicitamente:

export TROQPAY_ENABLE_WITHDRAWALS="true"

Claude Desktop

Depois de instalar e compilar o plugin local, adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "troqpay": {
      "command": "node",
      "args": ["/absolute/path/to/plugins/troqpay/dist/mcp.js"],
      "env": {
        "TROQPAY_API_KEY": "trq_test_xxxxxxxxx",
        "TROQPAY_BASE_URL": "https://api.troqpay.com"
      }
    }
  }
}

Codex

O bundle do plugin inclui:

.codex-plugin/plugin.json
.claude-plugin/plugin.json
.mcp.json
skills/troqpay/SKILL.md
servidor MCP em dist/mcp.js

O código oficial do plugin fica em:

https://github.com/troqpay/agent-plugin

No Codex, instale o plugin e mantenha TROQPAY_API_KEY no ambiente da sessão. Para staging, configure também TROQPAY_BASE_URL.

Regras de segurança

use trq_test_ para testes e demos
não cole chaves em prompts
mantenha ferramentas de saque desabilitadas quando não forem necessárias
não crie saques sem confirmação explícita
use Idempotency-Key em toda criação sensível
confira requestId quando uma chamada falhar

Exemplo de prompt

Crie um checkout Pix de teste de R$ 129,90 para order_1001 e me devolva o checkoutUrl.

Próximos passos

SDK JavaScript

Veja como usar o mesmo cliente sem agente.

Webhooks

Complete o fluxo recebendo eventos de pagamento.

Erros

Entenda code, message e requestId.

​Plugin para Claude e Codex

​Ferramentas

​Variáveis de ambiente

​Claude Desktop

​Codex

​Regras de segurança

​Exemplo de prompt

​Próximos passos

SDK JavaScript

Webhooks

Erros

Plugin para Claude e Codex

Ferramentas

Variáveis de ambiente

Claude Desktop

Codex

Regras de segurança

Exemplo de prompt

Próximos passos