# Agentes de IA (MCP)



O servidor **MCP** (Model Context Protocol) deixa um agente de IA descobrir e usar as ferramentas da plataforma, como criar um QR, converter um PDF ou buscar na base de conhecimento, com a sua conta e os seus créditos. Ele usa as mesmas regras da API: os mesmos preços, escopos e franquias.

<Callout title="Liberação gradual">
  O servidor MCP está sendo liberado aos poucos. Enquanto ele não estiver ativo no seu ambiente, `/mcp` responde `404` com o código `mcp.disabled`.
</Callout>

## Conexão

|                    |                                                |
| ------------------ | ---------------------------------------------- |
| URL                | <McpUrl />                                     |
| Transporte         | Streamable HTTP, sem sessão, respostas JSON    |
| Autenticação       | `Authorization: Bearer <token de API>`         |
| Escopo obrigatório | `mcp:use`, além dos escopos de cada ferramenta |

Nunca coloque o token na URL (`?token=`, `?api_key=`…): o servidor recusa com `400`. Conectores de produtos como Claude.ai e ChatGPT, que pedem login em vez de token, ainda não são suportados.

## Crie uma chave para o agente

No [dashboard](https://dashboard.respawntech.dev), em **APIs**, crie um token só para o agente. Os modelos prontos preenchem escopos e controles:

* **Agente de suporte**: busca na base de conhecimento e consulta de saldo.
* **Agente completo**: todas as ferramentas.
* **Somente leitura**: só consultas.

Uma chave de agente deve ter um **limite diário de gasto** (sugestão: <Limit name="mcpSuggestedDailyLimit" />) e uma **data de expiração**. Veja [Controles da chave](/autenticacao#controles-da-chave).

## Configure o cliente

<McpClientSnippets />

Clientes que só falam stdio usam a ponte `mcp-remote`, como no último exemplo.

## Ferramentas

O agente só vê as ferramentas permitidas pelos escopos da chave. As descrições que ele recebe estão em inglês por padrão; use `lang` (abaixo) para outro idioma.

<McpToolsTable />

Ferramentas **destrutivas** pedem confirmação ao usuário na maioria dos clientes. As marcadas com dry-run aceitam `dry_run: true` e devolvem só a estimativa de custo.

## Parâmetros da conexão

Todos são opcionais e vão na query string da URL. Eles só **restringem** o que a chave permite, nunca ampliam. Um parâmetro desconhecido ou com valor inválido responde `400`, para um erro de digitação não virar "sem filtro".

<McpParamsTable />

Por exemplo, um agente de suporte que só lê a base de conhecimento, com respostas em português: <McpUrl query="toolsets=rag&access=read&lang=pt" />

Parâmetros repetidos em várias conexões podem virar um **perfil** no dashboard (`profile=<slug>`), e uma chave pode ter um perfil padrão.

## Custos e controle de gasto

* Cada chamada custa o mesmo que a operação equivalente na API, e as leituras medidas entram na mesma [franquia diária](/cobranca-e-limites#franquia-diaria).
* Toda resposta traz o custo em `_meta["tech.respawn/cost"]`: créditos cobrados, estimativa (em dry-run), saldo depois e quanto resta do limite do dia.
* `simulate=true` na URL faz todas as ferramentas que cobram devolverem só a estimativa. É o jeito de testar um agente sem gastar.
* Passar do limite diário da chave responde `billing.spend_limit_reached`; passar do teto por chamada (`max_call_credits`) responde `billing.call_limit_exceeded`.
* O **botão de pânico** no dashboard desliga o acesso de todos os agentes da conta na hora (`mcp.agents_disabled`).
* O extrato do dashboard separa o gasto por canal (API, MCP, dashboard) e por chave.

## Idempotência

Agentes repetem chamadas com frequência. Ferramentas que criam ou alteram algo aceitam `idempotency_key`; sem ele, uma chamada idêntica (mesma chave, ferramenta e argumentos) em até <Limit name="mcpIdempotencyWindow" /> devolve o resultado anterior sem executar nem cobrar de novo (`_meta["tech.respawn/replayed"]`).

## Limites

| Limite                      | Valor                                                                       |
| --------------------------- | --------------------------------------------------------------------------- |
| Requisições                 | <Limit name="rateLimitPerMinute" /> por minuto por chave, somadas às da API |
| Corpo da requisição         | <Limit name="mcpRequestMax" />                                              |
| Resultado de uma ferramenta | <Limit name="mcpResultMax" />                                               |
| Chamadas de `tools_search`  | <Limit name="mcpToolsSearchPerMinute" /> por minuto                         |

## Erros

Erros de negócio voltam como resultado da ferramenta, com uma mensagem que diz ao agente o que fazer e o código em `_meta["tech.respawn/error"]`. Erros da conexão voltam como HTTP, no formato `{"error": {"code", "message"}}`.

<ErrorTable group="agents" />

Os erros das ferramentas são os mesmos da API; veja [Códigos de erro](/erros).