SDK vs MCP Workflows

When to use @toolyour/sdk single-tool calls vs MCP skills and run_workflow jobs. Same API key and quota.

ToolYour exposes one catalog with three surfaces: browser, REST, and MCP. The @toolyour/sdk package wraps every API-backed tool as typed TypeScript. MCP adds agent-oriented layers on top: curated skills (playbooks) and workflows (multi-step jobs with merged jobReport).

Surface	What you get	Best for
SDK	`ty.seo.metaTagsAnalyzer({ url })` — one tool, one response	Node/TS apps, CI scripts, explicit control
REST	Same routes as SDK — any HTTP client	Non-Node stacks, curl, OpenAPI playground
MCP skills	`load_skill("seo-site-audit")` → markdown playbook	Cursor, Claude Desktop, agents that need guidance
MCP workflows	`run_workflow("full-seo-audit", { url })` → merged `jobReport`	Multi-tool audits without orchestrating each call

Browser-only tools (no API) are not in the SDK or MCP tool list — use toolyour.com in the browser.

Decision guide

Need exactly one known tool with typed input/output?
  → SDK (or REST). See SDK Tool Map for purpose + example call.

Building an agent in Cursor / Claude with playbooks?
  → MCP: plan_task → solve_task(compact) or run_playbook(skillId).

Want a pre-built multi-step audit with one merged report?
  → MCP: run_playbook / run_workflow. Replicate manually in SDK by calling each step yourself.

Quota: Every underlying tool call counts once — whether you use SDK, REST, MCP invoke_tool, or workflow steps. plan_task and catalog browse are free.

MCP skills (playbooks)

Skills are markdown resources plus an optional mapped workflow. Prefer run_playbook(skillId) to execute in one step. Use load_skill only when you need the markdown guidance.

plan_task(goal) → run_playbook("ship-gate", { url }) → verify_task(...)
# or
list_skills() → load_skill("seo-site-audit") → invoke_tool("seoAnalyze", { url })

Skill ID	Purpose	Typical SDK alternative
`seo-site-audit`	On-page SEO audit for a URL	`ty.seo.seoAnalyze`, `ty.seo.pageSpeedAnalyzer`
`page-performance`	Core Web Vitals proxy + fixes	`ty.seo.pageSpeedAnalyzer` (+ workflow below)
`content-refresh`	Refresh outdated page copy	`ty.ai.aiTextAi`, `ty.seo.contentOptimization`
`content-quality`	Content depth / readability	`ty.seo.contentOptimization`, `ty.seo.rankCheckerKeywords`
`document-pipeline`	DOCX → PDF with download URL	`ty.documents.docxToPdf({ file })`
`social-preview`	Open Graph / Twitter Card audit	`ty.seo.socialMediaIntegration({ url })`
`crawl-analysis`	Link graph / internal linking	`ty.seo.internalLinking`, `ty.seo.linkExtractor`
`seo-deploy-regression`	Post-deploy bulk URL scorecard	`ty.seo.bulkUrlSeoAuditor`, `ty.seo.seoChangeDiff`
`web-security-audit`	Headers, TLS, cookies, email auth	`ty.security.*` analyzers per URL
`secrets-and-auth-hygiene`	Leaked secrets, JWT, passwords, HMAC	`ty.security.secretLeakScanner`, `ty.security.jwtDecoder`, …
`developer-ship-checklist`	Pre-deploy security + speed gate	Multiple `ty.security.*` + `ty.seo.pageSpeedAnalyzer`
`dns-email-security`	SPF/DKIM/DMARC, DNS, security.txt	`ty.security.spfDkimDmarcChecker`, `ty.security.dnsLookup`

Full skill reference: MCP Skills & Workflows.

SDK metadata for skills

The SDK exports read-only skill metadata (for docs generators and agent bootstrapping):

import { MCP_SKILLS } from "@toolyour/sdk/mcp";

console.log(MCP_SKILLS.find((s) => s.id === "seo-site-audit")?.description);
// → related operationIds for manual SDK orchestration

Skills are not callable SDK methods — use MCP load_skill or implement the playbook with SDK tool calls.

MCP workflows (multi-step jobs)

run_workflow(workflowId, input) runs several API tools server-side and returns a merged jobReport when a synthesizer is configured. Steps bill one request each, same as calling the SDK for each tool separately.

run_workflow("full-seo-audit", { url: "https://example.com" })

Workflow ID	Purpose	Underlying tools (SDK equivalents)
`full-seo-audit`	SEO + page speed merged report	`seoAnalyze`, `pageSpeedAnalyzer`
`core-web-vitals-job`	CWV diagnosis + prioritized fixes	`pageSpeedAnalyzer`, `seoAnalyze`, `socialMediaIntegration`
`full-seo-optimization-job`	Full SEO optimization (6 tools)	SEO, content, speed, links, extract, social
`internal-link-architecture-job`	Internal link graph + hub SEO	`internalLinking`, `linkExtractor`, `seoAnalyze`
`technical-seo-audit-job`	Technical SEO lite	`seoAnalyze`, `linkExtractor`, `pageSpeedAnalyzer`
`social-preview-audit-job`	OG / Twitter Card audit	`socialMediaIntegration`
`content-quality-audit-job`	Content + keyword signals	`contentOptimization`, `rankCheckerKeywords`
`keyword-opportunity-review-job`	Keyword gaps + content	`rankCheckerKeywords`, `contentOptimization`
`seo-deploy-regression-job`	Post-deploy bulk URL scorecard	`bulkUrlSeoAuditor`
`seo-deploy-regression-diff-job`	Bulk scorecard + staging/prod diff	`bulkUrlSeoAuditor`, `seoChangeDiff`
`full-security-audit`	Headers + TLS + cookies	`securityHeadersAnalyzer`, `sslTlsCertificateChecker`, `cookieSecurityAnalyzer`
`security-headers-job`	Security headers only	`securityHeadersAnalyzer`
`developer-ship-checklist-job`	Pre-deploy ship gate	headers, TLS, mixed content, status, speed
`ship-gate-job`	Pass/fail deploy gate (alias)	same steps as developer ship checklist
`secrets-hygiene-job`	Scan pasted text for secrets	`secretLeakScanner`
`email-auth-security-job`	SPF/DKIM/DMARC + DNS + security.txt	`spfDkimDmarcChecker`, `dnsLookup`, `securityTxtChecker`
`content-optimization`	Single content optimization pass	`contentOptimization`
`document-convert-pipeline`	DOCX → PDF pipeline	`docxToPdf`

Workflows with a synthesizer return jobReport (toolyour.jobReport@1) — scores, findings, and prioritized actions. Partial failures may return status: "partial" with failedStep.

Replicating a workflow in the SDK

There is no ty.workflows.run() in the SDK today. To match a workflow in TypeScript:

import { ToolYour } from "@toolyour/sdk";

const ty = ToolYour({ apiKey: process.env.TOOLYOUR_API_KEY! });

const url = "https://example.com";
const [seo, speed] = await Promise.all([
  ty.seo.seoAnalyze({ url }),
  ty.seo.pageSpeedAnalyzer({ url }),
]);
// Merge seo.result + speed.result in your app (workflow synthesizer logic is MCP-only)

For production agents, prefer MCP run_workflow when you want the platform merge logic. Prefer the SDK when you need custom orchestration, caching, or non-MCP runtimes.

SDK metadata for workflows

import { MCP_WORKFLOWS } from "@toolyour/sdk/mcp";

const wf = MCP_WORKFLOWS.find((w) => w.id === "full-seo-audit");
console.log(wf?.steps.map((s) => s.operationId));
// → ["seoAnalyze", "pageSpeedAnalyzer"]

MCP helpers in the SDK

Generate Cursor/Claude MCP config and call tools by MCP name via the REST shim (same quota):

import {
  toolYourMcpServerConfigJson,
  invokeMcpTool,
  MCP_WORKFLOWS,
} from "@toolyour/sdk/mcp";

console.log(toolYourMcpServerConfigJson({ apiKey: process.env.TOOLYOUR_API_KEY! }));

await invokeMcpTool("metaTagsAnalyzer", { url: "https://example.com" }, {
  apiKey: process.env.TOOLYOUR_API_KEY!,
});

invokeMcpTool maps to the same REST routes as ty.seo.metaTagsAnalyzer. It does not expose load_skill or run_workflow — connect an MCP client for those.

Example agent prompt

Plan then run a ship gate for https://example.com and list the top blockers.

Expected MCP sequence: plan_task → run_playbook("ship-gate", { url }) or solve_task → optional verify_task after fixes.

Equivalent SDK script: call the underlying security + speed tools yourself — see SDK Tool Map. Starter kits: toolyour-sdk/examples/agent-starter/.

Next steps

TypeScript SDK — install, namespaces, file uploads
SDK Tool Map — every tool with purpose + example call
MCP quickstart — connect Cursor or Claude
MCP Playbooks — skill → workflow map
MCP Skills & Workflows — full workflow step list and billing notes

SDK vs MCP Workflows

On this page