> ## Documentation Index
> Fetch the complete documentation index at: https://docs.troqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude e Codex

> Use o plugin MCP da TroqPay em agentes de desenvolvimento.

# 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.

<Info>
  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.
</Info>

## 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

```bash theme={null}
export TROQPAY_API_KEY="trq_test_xxxxxxxxx"
export TROQPAY_BASE_URL="https://api.troqpay.com"
```

Para staging:

```bash theme={null}
export TROQPAY_BASE_URL="https://api.staging.troqpay.com"
```

Para expor ferramentas de saque no agente, habilite explicitamente:

```bash theme={null}
export TROQPAY_ENABLE_WITHDRAWALS="true"
```

## Claude Desktop

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

```json theme={null}
{
  "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:

```text theme={null}
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

```text theme={null}
Crie um checkout Pix de teste de R$ 129,90 para order_1001 e me devolva o checkoutUrl.
```

## Próximos passos

<CardGroup cols={3}>
  <Card title="SDK JavaScript" href="/sdks/javascript">
    Veja como usar o mesmo cliente sem agente.
  </Card>

  <Card title="Webhooks" href="/flows/webhooks">
    Complete o fluxo recebendo eventos de pagamento.
  </Card>

  <Card title="Erros" href="/flows/errors">
    Entenda `code`, `message` e `requestId`.
  </Card>
</CardGroup>