ToolYour

Conecte o ToolYour ao Cursor, Claude Desktop ou agentes de IA personalizados via MCP.

Conecte apenas ferramentas com suporte a API a qualquer cliente MCP através do servidor MCP remoto do ToolYour: planeje → execute → verifique até passar. Ferramentas exclusivas de site não são expostas.

Relacionados: TypeScript SDK · Mapa de ferramentas do SDK · Descoberta MCP · Catálogo de playbooks · Agente de SEO · Portão de entrega · Auditoria de segurança

Endpoint

https://api.toolyour.com/mcp

SSE (padrão para Cursor): GET https://api.toolyour.com/mcp
HTTP transmissível (Smithery e clientes do padrão MCP): POST https://api.toolyour.com/mcp (alias https://api.toolyour.com/mcp/http)

Autenticação

X-Api-Key: ty_your_key_here

Crie chaves no painel do ToolYour.

Loop canônico do agente

1. plan_task(goal)              → free plan + credit estimate
2. run_playbook or solve_task   → jobReport + loop.remainingFixes + loop.gate
3. Host agent applies fixes in the repo (editor/git — not invoke_tool)
4. verify_task(goal, baseline)  → loop.gate pass|fail; repeat until pass
5. fetch_payload(dataRefId)     → only if you need full raw detail

invoke_tool é avançado (um operationId explícito). Não o use como caminho padrão para portão de entrega, SEO ou trabalhos de segurança.

Não inicie o loop de verificação a menos que o último resultado de plan_task / solve_task / run_playbook tenha loop.initiate: true. Se for false, o objetivo está fora do escopo, é um conversor de uma única execução, ou o MCP não tem correção viável — pare.

Ou execute uma skill em uma única etapa: run_playbook(skillId, input).

Configuração do Cursor / Claude

{
  "mcpServers": {
    "toolyour": {
      "url": "https://api.toolyour.com/mcp",
      "headers": {
        "X-Api-Key": "ty_YOUR_KEY"
      }
    }
  }
}

npm install @toolyour/sdk

import { toolYourMcpServerConfigJson } from "@toolyour/sdk/mcp";
console.log(toolYourMcpServerConfigJson({ apiKey: process.env.TOOLYOUR_API_KEY! }));

solve_task

Descreva o objetivo em linguagem simples. O servidor escolhe um fluxo de trabalho ou ferramenta (correspondência difusa + controle de confiança). Objetivos ambíguos retornam status: "suggest" (grátis).

• responseMode padrão: compact (jobReport sem steps duplicado) mais loop (gate, remainingFixes com patchType + acceptance, next)
• Após a primeira execução, aplique loop.remainingFixes no repositório do host, depois verify_task com este resultado inteiro como baseline. Não faça invoke_tool para o mesmo trabalho.
• responseMode: "full" — inclua payloads brutos das etapas
• responseMode: "dataRef" — compacto + armazenamento TTL; recupere com fetch_payload
• async: true — retorne { status: "accepted", runId } imediatamente; sempre consulte get_run. Quando status for completed / partial / error, também leia resultStatus (e result.status) — ex.: suggest, need_input, verified — executar completed apenas significa que o trabalho terminou, não que o roteamento foi bem-sucedido. REDIS_URL opcional no MCP habilita get_run entre réplicas. Um webhook opcional do painel (mcp.job.finished) é apenas de melhor esforço — webhooks não configurados ou com falha nunca quebram o trabalho.
• Em status: "suggest" / "need_input", leia hint, nextActions e exampleGoals / exampleInput — depois chame novamente com um objetivo mais claro ou campos ausentes (não invente operationIds).
• input.html / input.text / input.code locais: análise gratuita, a menos que enhance: true
• Payload primeiro: leia os arquivos do workspace e passe os conteúdos. Inclua input.url apenas se o usuário pediu para analisar um link ao vivo/pré-visualização, ou se o trabalho não puder ser executado sem um fetch (PageSpeed, TLS, conteúdo misto, cabeçalhos ao vivo).

Exemplo: SEO audit for this HTML com input.html do repositório — ou SEO audit for https://example.com quando pediram para rastrear uma página ao vivo.

verify_task

Execute novamente o mesmo objetivo e retorne deltas em relação a uma linha de base. A linha de base pode ser:

• um resultado anterior de solve_task
• verify_task.after de uma verificação anterior
• um payload de consulta de get_run (usa result aninhado)
• um jobReport bruto

Suporta async: true (consulte get_run da mesma forma). Falhas em execuções novas se propagam como status: error|partial|suggest|… em vez de alegar falsamente verified.

Contrato de delta (voltado ao harness): delta.status, delta.scoreDeltas, delta.newFindings / resolvedFindings, mais:

• delta.remainingFindings — descobertas abertas na execução nova
• delta.remainingFixes / loop.remainingFixes — correções classificadas com patchType (http-header | html | file | config | content | investigate) e acceptance
• delta.nextActions / loop.nextActions — rótulos curtos e ordenados para o loop do host
• delta.gate / loop.gate — pass | fail | unknown (falha se descobertas de alta gravidade ou pontuações ruins permanecerem)

Agentes host devem aplicar loop.remainingFixes, depois chamar verify_task novamente até loop.gate === "pass" (ou aceitar descobertas residuais médias/baixas por política).

Auxiliar do SDK: @toolyour/sdk (0.1.2+) exporta verifyUntilPass de @toolyour/sdk/mcp para o mesmo loop em Node/CI. O CI também pode executar o script do pacote MCP scripts/ci-ship-gate.mjs (veja CI-AGENT-LOOP.md).

Veja também: docs do repositório MCP HARNESS-MIGRATION.md e CI-AGENT-LOOP.md.

Outras meta-ferramentas

Ferramenta	Cobra?	Propósito
plan_task	Grátis	Planejamento + estimativa de créditos
run_playbook	Como fluxo de trabalho	Skill → fluxo de trabalho mapeado
verify_task	Como solve_task	Delta vs. linha de base (assíncrono opcional)
discover_tools	Grátis	Busca avançada no catálogo (não é o caminho padrão de trabalho)
get_tool_schema	Grátis	Esquema para uma ferramenta (avançado)
invoke_tool	Sim	operationId único (avançado; não é o padrão para entrega/SEO/segurança)
fetch_payload	Grátis	Payload truncado completo
get_run	Grátis	Consulta assíncrona de runId (leia resultStatus)
list_skills / load_skill	Grátis	Playbooks
run_workflow	Sim	ID de fluxo de trabalho nomeado

Cota

A execução compartilha créditos mensais da REST. Grátis: plan_task, navegação no catálogo, sugestões sem execução, fetch_payload, get_run, conteúdo local sem enhance.

Veja Uso e planos.

[

Erros

Códigos de status HTTP comuns para chamadas de API de ferramentas e como corrigi-los.

](https://www.toolyour.com/developers/docs/errors)[

Descoberta MCP

Descoberta de ferramentas eficiente em tokens para agentes de IA — apenas ferramentas com suporte a API.

](https://www.toolyour.com/developers/docs/mcp-discovery)