MCP Quickstart

Connect API-backed tools only to any MCP client through ToolYour’s remote MCP harness: plan → run → verify until pass. 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.

Canonical agent loop

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 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)
• After the first run, apply loop.remainingFixes in the host repo, then verify_task with this entire result as baseline. Do not invoke_tool for the same job.
• 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. Baseline may be:

• a prior solve_task result
• verify_task.after from an earlier verify
• a get_run poll payload (uses nested result)
• a raw jobReport

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 patchType (http-header | html | file | config | content | investigate) and acceptance
• delta.nextActions / loop.nextActions — short ordered labels for the host loop
• delta.gate / loop.gate — pass | fail | unknown (fail if high-severity findings or poor scores remain)

Host agents should apply loop.remainingFixes, then call verify_task again until loop.gate === "pass" (or accept residual medium/low findings by policy).

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

Quota

Execution shares REST monthly credits. Free: plan_task, catalog browse, suggestions without execution, fetch_payload, get_run, local content without enhance.

See Usage & plans.