Como conectar agentes de IA ao Vertal Run com MCP

Passo a passo para dar a Claude, KUBO IA ou ao seu IDE uma ferramenta run_code que executa código em sandboxes isoladas do Vertal Run.

O Model Context Protocol (MCP) é o padrão aberto que permite a assistentes de IA usar ferramentas externas. O Vertal Run tem um servidor MCP próprio: ao conectá-lo, seu agente ganha a capacidade de executar código em sandboxes isoladas, com a mesma chave, cota e medição da API.

1. Tenha uma chave de API

As chaves têm o formato kubo_sk_…. Elas são exibidas uma única vez e armazenadas apenas como hash, então guarde a sua em um gerenciador de segredos ou variável de ambiente.

2. Instale o pacote

O servidor MCP faz parte do pacote Python vertal2kubo, disponível no repositório do projeto. Siga as instruções de instalação do README.

3. Configure o cliente MCP

No Claude Desktop, Claude Code ou em outro cliente compatível, adicione o servidor:

{
  "mcpServers": {
    "vertal-run": {
      "command": "python",
      "args": ["-m", "vertal2kubo.mcp"],
      "env": {
        "KUBO_API_URL": "https://vertalrun.com/api",
        "KUBO_API_KEY": "kubo_sk_..."
      }
    }
  }
}

4. Use as ferramentas

O agente passa a ter duas ferramentas:

• run_code: recebe code, language (padrão python) e timeout_s; devolve status, saída, erros, código de saída e duração.
• get_usage: mostra as execuções do dia, segundos de sandbox, plano e limites.

Experimente pedir ao agente: "calcule a média e o desvio padrão destes preços usando Python". Ele escreve o programa, chama run_code e responde com o resultado real da execução.

Boas práticas

• Defina um timeout_s curto para tarefas simples; ele é limitado pelo seu plano.
• Peça ao agente para imprimir só o necessário: a saída muito longa é truncada.
• Use get_usage para acompanhar o consumo da cota diária.

A referência completa do servidor MCP está na documentação.