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 (when the client supports it): 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. solve_task(goal, compact)    → jobReport (default; no duplicated steps)
3. (harness applies fixes)
4. verify_task(goal, baseline)  → score/finding deltas only
5. fetch_payload(dataRefId)     → only if you need full raw detail

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)
• 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: free analysis unless enhance: true

Example: SEO audit for https://example.com

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 — ranked howToFix / prioritized actions agents should apply
• delta.nextActions — short ordered labels for the host loop
• delta.gate — pass | fail | unknown (fail if high-severity findings or poor scores remain)

Host agents should apply nextActions, then call verify_task again until 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.