ToolYour

Connect ToolYour managed MCP actions and playbooks to ChatGPT, Claude, Cursor, Codex, or another compatible client.

Connect ToolYour’s managed action platform to a compatible MCP client. Discover focused API-backed actions, run outcome-based playbooks, and verify supported checks. Website-only tools are not exposed.

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

Endpoint

https://api.toolyour.com/mcp

SSE (default for Cursor): GET https://api.toolyour.com/mcp
Streamable HTTP (Smithery and MCP spec clients): POST https://api.toolyour.com/mcp (alias https://api.toolyour.com/mcp/http)

Authentication

X-Api-Key: ty_your_key_here

Create keys in the ToolYour dashboard.

Pick one loop per goal

Skill loop (SEO, security, ship-gate, secrets, catalog): plan_task → run_playbook or solve_task → host applies rank-1 loop.nextActions (see patchType, acceptance, roleHint) → verify_task until loop.gate is pass.

Each response also contains an additive execution envelope with runId, intentId, intentType, idempotencyKey, and projectScope. Preserve it between calls. With async: true, execution.runId is the same id returned by get_run.

Feature Memory (hot, system-first): ToolYour auto-records purpose-typed memory on loop.gate=pass. Free recall_context (or plan_task.featureMemory) before rebuilding. Full guide: Feature Memory. Dashboard: /dashboard/feature-memory.

Completion loop (frozen coding jobId only): job_status → edit on the host → run npx toolyour-check-run (HMAC host runner — do not invent check_submit payloads). Do not call plan_task on that jobId.

Host contract (any MCP agent)

ToolYour measures and prioritizes in the cloud. The host (Cursor, Claude, or any MCP client) applies fixes in the workspace — this server does not replace the host.

1. Apply only the rank-1 loop.nextActions item between verifies
2. Full backlog stays on loop.remainingFixes
3. Stop when loop.stop / loop.initiate is false — do not burn credits on the same findings
4. Never pass localhost URLs

Tier-1 golden paths (worth the credits)

Job	Goal example	Host applies
Ship-gate	ship gate for https://your-preview.example	Headers/TLS/mixed fixes (roleHint: config) then verify
Preview deploy (dev loop)	verify my preview deploy is production ready + https://…	run_playbook("production-readiness-gate") → read verification.evidence → fix → verify_task with profileId
SEO	seo audit https://… or local input.html	Template/meta edits (roleHint: edit) then verify
Secrets	paste env/diff into input.text	Redact/rotate (roleHint: config) then verify cleaned text
Cross-project feature	capture_feature after ship; later plan_task("add OCR…")	Read featureMemory.capabilityGaps before rebuilding

Use a URL you control when you need loop.gate = pass after a fix. example.com is fine to demo fail + remainingFixes.

Feature Memory (cross-project, system-first)

ToolYour is the institutional record — agents do not own persistence.

1. plan_task(goal) — always includes featureMemory.recordKeeping (+ reminders when similar work exists)
2. verify_task / run_playbook / solve_task on loop.gate=pass → ToolYour auto-records (featureMemoryRecord with featureId)
3. Opt out only: input.featureMemory.capture=false
4. Manual refine: capture_feature({ title, requirements, supersedesFeatureId, baseline })
5. list_feature_memory · compare_feature_memory · publish_feature_pattern · list_community_patterns
6. Dashboard: /dashboard/feature-memory (notifications when matrix improves)

Canonical skill loop

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

On run_playbook / verify_task, read verification.evidence (acceptance criteria) before loop.remainingFixes. First https:// run auto-creates profileId for regression vs last verified pass.

invoke_tool is advanced (one explicit operationId). Do not use it as the default path for ship-gate, SEO, or security jobs.

Do not start the verify loop unless the last plan_task / solve_task / run_playbook result has loop.initiate: true. If it is false, the goal is out of scope, a one-shot converter, or MCP has no remediable fix — stop.

Or run a skill in one step: run_playbook(skillId, input).

Cursor / Claude config

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

Describe the goal in plain language. The server picks a workflow or tool (fuzzy matching + confidence gating). Ambiguous goals return status: "suggest" (free).

• Default responseMode: compact (jobReport without duplicated steps) plus loop (gate, remainingFixes with patchType + acceptance, next, receipt)
• After the first run, apply the rank-1 item in loop.nextActions (full list is loop.remainingFixes) in the host repo, then verify_task with this entire result as baseline. Do not invoke_tool for the same job.
• loop.receipt — { round, maxRounds, toolsUsed, estimatedCredits, note } on every run/verify result (estimate only; SaaS bills 1–10 credits per tool)
• verify_task status: verified only when loop.gate is pass; otherwise fail / continue / stopped (never claim verified on a failing gate)
• Never pass localhost — MCP cannot fetch it; you get need_input / local_preview_required. Use workspace HTML/text/code or a public/preview https:// URL.
• status: "partial" / jobReport.incomplete never counts as gate pass — fix the URL/input and re-run
• Local HTML SEO returns a closable jobReport + remainingFixes (re-pass input.html and verify)
• responseMode: "full" — include raw step payloads
• responseMode: "dataRef" — compact + TTL store; retrieve with fetch_payload
• async: true — return { status: "accepted", runId } immediately; always poll get_run. When status is completed / partial / error, also read resultStatus (and result.status) — e.g. suggest, need_input, verified — run completed only means the job finished, not that routing succeeded. Optional REDIS_URL on MCP enables cross-replica get_run. An optional dashboard webhook (mcp.job.finished) is best-effort only — unset or failing webhooks never break the job.
• On status: "suggest" / "need_input", read hint, nextActions, and exampleGoals / exampleInput — then re-call with a clearer goal or missing fields (do not invent operationIds).
• Local input.html / input.text / input.code: free analysis unless enhance: true
• Payload first: read workspace files and pass contents. Include input.url only if the user asked to analyze a live/preview link, or the job cannot run without a fetch (PageSpeed, TLS, mixed content, live headers).

Example: SEO audit for this HTML with input.html from the repo — or SEO audit for https://example.com when they asked to crawl a live page.

verify_task

Re-run the same goal and return deltas vs a baseline. Requires a usable jobReport baseline — without one, the tool returns status: "need_input" / code: "need_baseline" and does not re-run. Baseline may be:

• a prior solve_task or run_playbook result
• verify_task.after from an earlier verify
• a get_run poll payload (uses nested result)
• a raw jobReport
• optional profileId — auto-loads lastRunSnapshot when baseline is omitted (after first run_playbook on an https:// URL)

Supports async: true (poll get_run the same way). Fresh-run failures propagate as status: error|partial|suggest|… instead of falsely claiming verified.

Delta contract (harness-facing): delta.status, delta.scoreDeltas, delta.newFindings / resolvedFindings, plus:

• delta.remainingFindings — open findings on the fresh run
• delta.remainingFixes / loop.remainingFixes — ranked fixes with findingId, patchType (http-header | html | file | config | content | investigate) and acceptance
• delta.nextActions / loop.nextActions — rank-1 only (the next host patch). Full list stays on remainingFixes.
• delta.gate / loop.gate — pass | fail | unknown (fail if high-severity findings or poor scores remain)
• Ship-gate policy: reports with gatePolicy: "ship" also fail when TLS, security headers, HTTP status, or mixed content are needs_improvement or unknown. Page-speed proxy needs_improvement alone does not fail ship-gate.
• loop.round / loop.maxRounds (default 5) — verify iteration counter (solve = 0)
• loop.sameFindingsStreak / loop.sameFindingsLimit (default 2) — stops when the same remaining-finding set repeats
• loop.stop — when set (max_rounds | same_findings), loop.initiate is false; escalate to a human — do not call verify_task again

Host agents should apply the rank-1 loop.nextActions item, then call verify_task again until loop.gate === "pass", or until loop.initiate is false / loop.stop is set (or accept residual medium/low findings by policy).

Page-speed / Core Web Vitals scores on these reports are HTML proxies, not Chrome field CrUX or Lighthouse lab metrics.

CI: toolyour-mcp script npm run ci:ship-gate (after npm run build; SHIP_URL=… TOOLYOUR_API_KEY=ty_…) uses the same ship gate helper as the server. Copy examples/github-actions/ship-gate.yml into your app repo. Monorepo optional live smoke: .github/workflows/ship-gate-live.yml.

SDK helper: @toolyour/sdk (0.1.2+) exports verifyUntilPass from @toolyour/sdk/mcp for the same loop in Node/CI. CI can also run the MCP package script scripts/ci-ship-gate.mjs (see CI-AGENT-LOOP.md).

See also: MCP repo docs HARNESS-MIGRATION.md and CI-AGENT-LOOP.md.

Other meta-tools

Tool	Bills?	Purpose
plan_task	Free	Plan + heuristic credit estimate (not a bill; tools cost 1–10)
recall_context	Free	Feature Memory recall before rebuilding similar work
run_playbook	Like workflow	Skill → mapped workflow; attaches verification.evidence
solve_task	Like workflow	Goal → matched job; workflow runs attach verification.evidence
verify_task	Like solve_task	Delta vs baseline (optional async)
capture_feature / list_feature_memory / compare_feature_memory	Free	Manual Feature Memory refine / list / compare
publish_feature_pattern / unpublish_feature_pattern / delete_feature / list_community_patterns	Free	Community Feature Memory
discover_tools	Free	Advanced catalog search (not the default job path)
get_tool_schema	Free	Schema for one tool (advanced)
invoke_tool	Yes	One-off operationId (advanced; not ship/SEO/security default)
fetch_payload	Free	Full truncated payload
get_run	Free	Poll async runId (read resultStatus)
list_skills / load_skill	Free	Playbooks
run_workflow	Yes	Named workflow id
job_status / job_start / …	Completion-loop	Frozen coding jobs only — run npx toolyour-check-run for checks (do not invent check_submit)

Quota

Execution shares REST monthly credits. Free: plan_task, Feature Memory tools, catalog browse, suggestions without execution, fetch_payload, get_run, local content without enhance. Credits settle 1–10 per gateway tool — estimatedCredits is always a heuristic.

See Usage & plans.

[

Errors

Common HTTP status codes for tool API calls and how to fix them.

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

Feature Memory (MCP)

ToolYour auto-records completed features for cross-project agent memory — system-first, free meta-tools.

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