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.

Conexão

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, 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: 10 créditos) e uma data de expiração. Veja Controles da chave.

Configure o cliente

claude mcp add --transport http respawn https://api.respawntech.dev/mcp \
  --header "Authorization: Bearer $RESPAWN_API_TOKEN"

{
  "mcpServers": {
    "respawn": {
      "url": "https://api.respawntech.dev/mcp",
      "headers": {
        "Authorization": "Bearer rsk_live_…"
      }
    }
  }
}

{
  "servers": {
    "respawn": {
      "type": "http",
      "url": "https://api.respawntech.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:respawn-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "respawn-token",
      "description": "Respawn Tech Dev API token",
      "password": true
    }
  ]
}

{
  "mcpServers": {
    "respawn": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.respawntech.dev/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer rsk_live_…"
      }
    }
  }
}

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.

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

Por exemplo, um agente de suporte que só lê a base de conhecimento, com respostas em português: https://api.respawntech.dev/mcp?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.
• 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é 60 segundos devolve o resultado anterior sem executar nem cobrar de novo (_meta["tech.respawn/replayed"]).

Limites

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"}}.

Os erros das ferramentas são os mesmos da API; veja Códigos de erro.