ToolYour

Servidor MCP remoto

Ver em toolyour.com

Documentação

Conecte ações e playbooks gerenciados do ToolYour MCP ao ChatGPT, Claude, Cursor, Codex ou outro cliente compatível.

Conecte a plataforma de ações gerenciadas do ToolYour a um cliente MCP compatível. Descubra ações focadas em APIs, execute playbooks baseados em resultados e verifique verificações suportadas. Ferramentas exclusivas de site não são expostas.

Relacionados: TypeScript SDK · SDK Tool Map · MCP discovery · Playbook catalog · SEO agent · Ship gate · Security audit

Endpoint

https://api.toolyour.com/mcp

SSE (padrão para Cursor): GET https://api.toolyour.com/mcp
Streamable HTTP (Smithery e clientes do spec 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.

Escolha um loop por objetivo

Skill loop (SEO, segurança, ship-gate, segredos, catálogo): plan_task → run_playbook ou solve_task → o host aplica o item rank-1 loop.nextActions (veja patchType, acceptance, roleHint) → verify_task até loop.gate passar.

Cada resposta também contém um envelope aditivo execution com runId, intentId, intentType, idempotencyKey e projectScope. Preserve-o entre chamadas. Com async: true, execution.runId é o mesmo id retornado por get_run.

Feature Memory (quente, sistema-primeiro): ToolYour registra automaticamente memória tipada por propósito em loop.gate=pass. Libere recall_context (ou plan_task.featureMemory) antes de reconstruir. Guia completo: Feature Memory. Painel: /dashboard/feature-memory.

Completion loop (somente jobId de codificação congelada): job_status → edite no host → execute npx toolyour-check-run (runner do host HMAC — não invente payloads check_submit). Não chame plan_task nesse jobId.

Contrato do host (qualquer agente MCP)

O ToolYour mede e prioriza na nuvem. O host (Cursor, Claude ou qualquer cliente MCP) aplica correções no workspace — este servidor não substitui o host.

  1. Aplique apenas o item rank-1 loop.nextActions entre verificações
  2. O backlog completo permanece em loop.remainingFixes
  3. Pare quando loop.stop / loop.initiate for falso — não gaste créditos nos mesmos achados
  4. Nunca passe URLs localhost

Caminhos dourados Tier-1 (valem os créditos)

JobExemplo de objetivoHost aplica
Ship-gateship gate for https://your-preview.exampleCorreções de headers/TLS/mixed (roleHint: config) depois verifique
Preview deploy (dev loop)verify my preview deploy is production ready + https://…run_playbook("production-readiness-gate") → leia verification.evidence → corrija → verify_task com profileId
SEOseo audit https://… ou input.html localEdições de template/meta (roleHint: edit) depois verifique
Segredoscole env/diff em input.textRedija/rotacione (roleHint: config) depois verifique o texto limpo
Feature entre projetoscapture_feature após o ship; depois plan_task("add OCR…")Leia featureMemory.capabilityGaps antes de reconstruir

Use uma URL que você controla quando precisar de loop.gate = pass após uma correção. example.com é suficiente para demonstrar falha + remainingFixes.

Feature Memory (entre projetos, sistema-primeiro)

O ToolYour é o registro institucional — agentes não possuem persistência.

  1. plan_task(goal) — sempre inclui featureMemory.recordKeeping (+ lembretes quando trabalho similar existe)
  2. verify_task / run_playbook / solve_task em loop.gate=pass → ToolYour registra automaticamente (featureMemoryRecord com featureId)
  3. Opte por sair apenas: input.featureMemory.capture=false
  4. Refinamento manual: capture_feature({ title, requirements, supersedesFeatureId, baseline })
  5. list_feature_memory · compare_feature_memory · publish_feature_pattern · list_community_patterns
  6. Painel: /dashboard/feature-memory (notificações quando a matriz melhora)

Skill loop canônico

1. plan_task(goal)              → free plan + credit estimate (+ goldenPath for preview deploy goals)
2. run_playbook or solve_task   → jobReport + verification.evidence + 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 (profileId reuses stored snapshots)
5. fetch_payload(dataRefId)     → only if you need full raw detail

Em run_playbook / verify_task, leia verification.evidence (critérios de aceitação) antes de loop.remainingFixes. A primeira execução de https:// cria automaticamente profileId para regressão vs a última verificação aprovada.

invoke_tool é avançado (um operationId explícito). Não o use como caminho padrão para jobs de ship-gate, SEO ou 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 uso único, ou o MCP não tem correção remediável — pare.

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

Configuração 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 workflow 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, receipt)
  • Após a primeira execução, aplique o item rank-1 em loop.nextActions (lista completa é loop.remainingFixes) no repositório do host, depois verify_task com este resultado inteiro como baseline. Não invoke_tool para o mesmo job.
  • loop.receipt — { round, maxRounds, toolsUsed, estimatedCredits, note } em cada resultado de execução/verificação (apenas estimativa; SaaS cobra 1–10 créditos por ferramenta)
  • Status verify_task: verified somente quando loop.gate for pass; caso contrário fail / continue / stopped (nunca afirme verificado em um gate com falha)
  • Nunca passe localhost — o MCP não pode buscá-lo; você recebe need_input / local_preview_required. Use HTML/texto/código do workspace ou uma URL https:// pública/preview.
  • status: "partial" / jobReport.incomplete nunca conta como pass de gate — corrija a URL/entrada e execute novamente
  • SEO HTML local retorna um jobReport fechável + remainingFixes (re-passe input.html e verifique)
  • responseMode: "full" — inclua payloads brutos de etapas
  • responseMode: "dataRef" — armazenamento compacto + TTL; recupere com fetch_payload
  • async: true — retorne { status: "accepted", runId } imediatamente; sempre faça poll de 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 job 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 best-effort — webhooks não configurados ou com falha nunca quebram o job.
  • Em status: "suggest" / "need_input", leia hint, nextActions e exampleGoals / exampleInput — depois re-chame com um objetivo mais claro ou campos ausentes (não invente operationIds).
  • input.html / input.text / input.code local: análise gratuita a menos que enhance: true
  • Payload primeiro: leia arquivos do workspace e passe conteúdos. Inclua input.url somente se o usuário pediu para analisar um link ao vivo/preview, ou o job não pode rodar sem um fetch (PageSpeed, TLS, mixed content, headers 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

Re-execute o mesmo objetivo e retorne deltas vs uma linha de base. Requer uma linha de base jobReport utilizável — sem uma, a ferramenta retorna status: "need_input" / code: "need_baseline" e não re-executa. A linha de base pode ser:

  • um resultado anterior de solve_task ou run_playbook
  • verify_task.after de uma verificação anterior
  • um payload de poll get_run (usa result aninhado)
  • um jobReport bruto
  • profileId opcional — carrega automaticamente lastRunSnapshot quando baseline é omitido (após o primeiro run_playbook em uma URL https://)

Suporta async: true (faça poll de get_run da mesma forma). Falhas de nova execução propagam como status: error|partial|suggest|… em vez de afirmar falsamente verified.

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

  • delta.remainingFindings — achados abertos na nova execução
  • delta.remainingFixes / loop.remainingFixes — correções ranqueadas com findingId, patchType (http-header | html | file | config | content | investigate) e acceptance
  • delta.nextActions / loop.nextActions — apenas rank-1 (o próximo patch do host). A lista completa permanece em remainingFixes.
  • delta.gate / loop.gate — pass | fail | unknown (falha se achados de alta severidade ou pontuações ruins permanecerem)
  • Política de ship-gate: relatórios com gatePolicy: "ship" também falham quando TLS, headers de segurança, status HTTP ou mixed content estão needs_improvement ou unknown. O proxy de page-speed needs_improvement sozinho não falha o ship-gate.
  • loop.round / loop.maxRounds (padrão 5) — contador de iteração de verificação (solve = 0)
  • loop.sameFindingsStreak / loop.sameFindingsLimit (padrão 2) — para quando o mesmo conjunto de achados restantes se repete
  • loop.stop — quando definido (max_rounds | same_findings), loop.initiate é falso; escale para um humano — não chame verify_task novamente

Agentes do host devem aplicar o item rank-1 loop.nextActions, depois chamar verify_task novamente até loop.gate === "pass", ou até loop.initiate ser falso / loop.stop estar definido (ou aceitar achados residuais médios/baixos por política).

Pontuações de Page-speed / Core Web Vitals nesses relatórios são proxies HTML, não métricas de campo CrUX do Chrome ou métricas de laboratório Lighthouse.

CI: script toolyour-mcp npm run ci:ship-gate (após npm run build; SHIP_URL=… TOOLYOUR_API_KEY=ty_…) usa o mesmo helper de ship gate do servidor. Copie examples/github-actions/ship-gate.yml para o repositório do seu app. Smoke test ao vivo opcional em monorepo: .github/workflows/ship-gate-live.yml.

Helper 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

FerramentaCobra?Propósito
plan_taskGrátisPlanejamento + estimativa heurística de créditos (não é cobrança; ferramentas custam 1–10)
recall_contextGrátisRecuperação de Feature Memory antes de reconstruir trabalho similar
run_playbookComo workflowSkill → workflow mapeado; anexa verification.evidence
solve_taskComo workflowObjetivo → job correspondente; execuções de workflow anexam verification.evidence
verify_taskComo solve_taskDelta vs linha de base (async opcional)
capture_feature / list_feature_memory / compare_feature_memoryGrátisRefinamento manual de Feature Memory / listar / comparar
publish_feature_pattern / unpublish_feature_pattern / delete_feature / list_community_patternsGrátisFeature Memory da comunidade
discover_toolsGrátisBusca avançada no catálogo (não é o caminho padrão de jobs)
get_tool_schemaGrátisSchema para uma ferramenta (avançado)
invoke_toolSimoperationId único (avançado; não é padrão para ship/SEO/segurança)
fetch_payloadGrátisPayload truncado completo
get_runGrátisPoll de runId async (leia resultStatus)
list_skills / load_skillGrátisPlaybooks
run_workflowSimid de workflow nomeado
job_status / job_start / …Completion-loopApenas jobs de codificação congelada — execute npx toolyour-check-run para verificações (não invente check_submit)

Quota

A execução compartilha créditos mensais de REST. Grátis: plan_task, ferramentas de Feature Memory, navegação no catálogo, sugestões sem execução, fetch_payload, get_run, conteúdo local sem enhance. Créditos são liquidados em 1–10 por ferramenta de gateway — estimatedCredits é sempre uma heurística.

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)[

Memória de Recursos (MCP)

O ToolYour registra automaticamente recursos concluídos para memória de agente entre projetos — ferramentas meta gratuitas, priorizando o sistema.

](https://www.toolyour.com/developers/docs/feature-memory)