# Como conectar seu agente

> Quatro passos, um comando por agente.

URL: https://apicultura.app/como-conectar/
Atualizado em 05/11/2026 (2026-11-05).

> **Nota.** Servidor MCP: https://api.apicultura.app/mcp. Confira a sintaxe na documentação do seu agente, que pode mudar entre versões.

## Passo a passo

1. **Recarregue o saldo** por Pix no [painel](/painel/).
2. **Crie uma chave** (`apk_live_...`) e defina tetos de gasto diário e mensal. O segredo aparece uma única vez.
3. **Cole o comando** do seu agente (abaixo), trocando `apk_live_SUA_CHAVE` pela sua chave.
4. **Peça uma tarefa.** O agente descobre as ferramentas do catálogo; cada resposta traz o custo em `cost_brl`.

## Dados do servidor MCP

| Campo | Valor |
|---|---|
| URL | `https://api.apicultura.app/mcp` |
| Transporte | HTTP |
| Autenticação | `Authorization: Bearer apk_live_...` |
| Descritor | [/.well-known/mcp.json](/.well-known/mcp.json) |

## 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: chamada HTTP

```bash
curl -X POST https://api.apicultura.app/v1/call/serp-search \
  -H "Authorization: Bearer $APICULTURA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"q":"melhor cafe de sao paulo","limit":5}'
```

O exemplo usa o slug `serp-search` da documentação da API. Confira os slugs reais em [/catalog.json](/catalog.json) e o contrato em [/openapi.json](/openapi.json).

## Boas práticas

- Use uma chave por agente e defina teto de gasto baixo no começo.
- Guarde a chave em variável de ambiente, nunca no repositório.
- Use `Idempotency-Key` em toda chamada paga para evitar cobrança duplicada.
- Revise manualmente antes de qualquer envio de mensagem em massa e respeite a LGPD.

Veja também: [FAQ](/faq/), [glossário](/glossario/), [workflows prontos](/workflows/). Atualizado em 05/11/2026.