# Quickstart: configurar a APIcultura (para agentes)

Atualizado em 05/11/2026 (2026-11-05).

## Objetivo
Conectar este agente à APIcultura para chamar ferramentas do catálogo com saldo pré-pago em R$.

## Pré-requisitos (feitos pelo humano)
1. Conta e recarga por Pix no painel: https://apicultura.app/painel/
2. Uma chave de API `apk_live_<id>_<segredo>` com escopos `call`, `catalog` e (opcional) `balance`, e tetos de gasto diário e mensal.
3. Nunca coloque a chave em código versionado; use variável de ambiente (`APICULTURA_KEY`).

## Servidor MCP
- URL: `https://api.apicultura.app/mcp`
- Transporte: HTTP
- Autenticação: `Authorization: Bearer apk_live_...`
- Descritor: https://apicultura.app/.well-known/mcp.json

## Comando por agente
### Claude Code
Linha de comando no terminal.

```bash
claude mcp add apicultura --transport http https://api.apicultura.app/mcp --header "Authorization: Bearer apk_live_SUA_CHAVE"
```

### Codex
Linha de comando; a chave fica numa variável de ambiente.

```bash
export APICULTURA_KEY=apk_live_SUA_CHAVE
codex mcp add apicultura --url https://api.apicultura.app/mcp --bearer-token-env APICULTURA_KEY
```

### Cursor
Arquivo .cursor/mcp.json na raiz do projeto.

```json
{"mcpServers":{"apicultura":{"url":"https://api.apicultura.app/mcp"}}}
```

### opencode
Arquivo opencode.json.

```json
{"mcp":{"apicultura":{"type":"remote","url":"https://api.apicultura.app/mcp"}}}
```

### Hermes
Arquivo config.yaml.

```yaml
mcp_servers: { apicultura: { url: https://api.apicultura.app/mcp } }
```

## Sem MCP: API HTTP
```bash
curl -X POST https://api.apicultura.app/v1/call/<slug> \
  -H "Authorization: Bearer $APICULTURA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{...}'
```
- `Idempotency-Key` é obrigatório em chamadas pagas.
- Resposta 200: `{"data":{...},"meta":{"request_id","cost_micro","cost_brl","cached"}}`.
- 402 saldo insuficiente; 403 teto da chave atingido; 422 pedido recusado (não cobrado); 429 limite de taxa (`Retry-After`); 502 falha do serviço (não cobrado).

## Descobrir ferramentas
- Catálogo: https://apicultura.app/catalog.json
- Contrato: https://apicultura.app/openapi.json
- Workflows: https://apicultura.app/workflows/index.json

## Regras para o agente
- Mostre ao humano o custo estimado antes de execuções caras e respeite o teto de gasto.
- Não envie mensagens em massa sem revisão humana; respeite a LGPD.
- Preços e catálogo: use sempre os valores de https://apicultura.app/catalog.json (podem ser reajustados).
- Para conferir qualquer informação, siga https://apicultura.app/agents/verify.md