ToolRoute

ToolRoute

Camada de roteamento para agentes de IA. Uma única chamada retorna o melhor servidor MCP e LLM para qualquer tarefa — avaliado em 132 execuções reais de benchmark.

---

Início rápido

Adicione a qualquer cliente MCP (Claude Code, Cursor, Windsurf, Cline):

{
  "mcpServers": {
    "toolroute": {
      "url": "https://toolroute.io/api/mcp"
    }
  }
}

Ou via HTTP:

curl -X POST https://toolroute.io/api/route \
  -H "Content-Type: application/json" \
  -d '{"task": "search the web for recent AI papers"}'

{
  "approach": "mcp_server",
  "recommended_skill": "exa-mcp-server",
  "recommended_skill_name": "Exa MCP Server",
  "recommended_model": {
    "slug": "claude-haiku-4-5-20251001",
    "display_name": "Claude Haiku 4.5",
    "provider": "anthropic",
    "tier": "cheap_chat",
    "provider_model_id": "anthropic/claude-haiku-4-5-20251001",
    "input_cost_per_mtok": 1.00,
    "output_cost_per_mtok": 5.00
  },
  "confidence": 0.91,
  "alternatives": ["brave-search-mcp", "tavily-mcp"],
  "fallback": "brave-search-mcp"
}

recommended_model é sempre um objeto, não uma string simples — o slug interno é o identificador canônico do modelo.

---

Como funciona

Cada tarefa se enquadra em uma de três abordagens:

Abordagem	Quando	Retorno
direct_llm	A tarefa precisa apenas de um LLM (código, escrita, análise)	Melhor modelo + estimativa de custo
mcp_server	A tarefa precisa de uma ferramenta externa (busca, e-mail, calendário)	Melhor ferramenta + melhor modelo
multi_tool	Tarefa composta ("enviar Slack E atualizar Jira E e-mail")	Cadeia de orquestração ordenada

O roteamento usa um classificador LLM (~$0,00001/chamada) para entender a tarefa e, em seguida, classifica os candidatos em uma pontuação de 5 dimensões:

Value Score = 0.35 × Output Quality
            + 0.25 × Reliability
            + 0.15 × Efficiency
            + 0.15 × Cost
            + 0.10 × Trust

Cada resultado relatado atualiza as pontuações. O roteamento fica mais preciso conforme mais agentes o utilizam.

---

Resultados de benchmark

132 execuções cegas A/B em código, escrita, análise, saída estruturada e tradução.

	ToolRoute	GPT-4o fixo
Vitórias de qualidade	6	0
Empates	9	9
Derrotas	0	—
Custo médio	$0,001–0,01	$0,03–0,10

---

API

Endpoint	Método	Descrição
/api/route	POST	Roteia uma tarefa para o melhor servidor MCP + LLM (unificado)
/api/route/model	POST	Roteia apenas para o melhor modelo LLM (sem servidor MCP)
/api/mcp	POST (JSON-RPC)	Servidor MCP — 16 ferramentas
/api/mcp	GET (SSE)	Transporte SSE para clientes MCP
/api/report	POST	Relata o resultado do servidor MCP (leve)
/api/contributions	POST	Telemetria avançada de habilidades MCP (requer skill_id ou skill_slug no payload)
/api/report/model	POST	Relata o resultado do modelo LLM — use isto para telemetria de modelo, não /api/contributions
/api/verify/model	POST	Verifica a qualidade da saída do modelo
/api/skills	GET	Pesquisa no catálogo de servidores MCP
/api/agents/register	POST	Registra a identidade do agente
/api/agents/preferences	POST	Define preferências de roteamento (Estratégia D Fase 2 — allow_china, regulated_industries)
/api/health	GET	Verificação de saúde do serviço (DB + uptime)
/api/metrics	GET	Métricas públicas agregadas da plataforma (sem autenticação)

Referência completa em toolroute.io/api-docs

---

SDK

npm install @toolroute/sdk

import { ToolRoute } from '@toolroute/sdk'

const tr = new ToolRoute()
const rec = await tr.route({ task: 'parse this CSV and summarize it' })
// execute with rec.recommended_model ...
await tr.report({ skill: rec.recommended_skill, outcome: 'success', latency_ms: 1400 })

---

Auto-hospedagem

git clone https://github.com/grossiweb/ToolRoute.git
cd ToolRoute
cp .env.local.example .env.local
npm install
npm run dev

Requer: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY

---

Como o roteamento funciona

O ToolRoute classifica cada tarefa usando um classificador LLM (Gemini Flash Lite, ~$0,00001/chamada) com fallback por palavras-chave. O nível resultante mapeia para um modelo específico via src/lib/routing/tiers.ts. Dados de preços e capacidades em tempo real vêm da tabela models. Veja docs/architecture.md para o panorama completo.

---

Stack

Next.js 14 (App Router) · Supabase (Postgres) · Vercel

Licença

MIT