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: list_skills → load_skill → invoke_tool (or solve_task).

Want a pre-built multi-step audit with one merged report?
  → MCP: 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.

MCP skills (playbooks)

Skills are markdown resources agents load once per session. They describe which tools to call, in what order, and how to summarize results. They do not replace the SDK — they guide agents that speak MCP.

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
`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

Load the SEO site audit skill, analyze https://example.com, and summarize the top 5 fixes.

Expected MCP sequence: load_skill("seo-site-audit") → invoke_tool("seoAnalyze", …) → optional pageSpeedAnalyzer.

Equivalent SDK script: call ty.seo.seoAnalyze and ty.seo.pageSpeedAnalyzer directly — see SDK Tool Map for example calls per tool.

Next steps

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

SDK vs MCP Workflows

On this page