MCP TypeScript SDK 2.4.0: Serving Agent Skills Over MCP (SEP-2640) and What the Spec Says to Distrust

The MCP TypeScript SDK v2.4.0, published on GitHub on October 23, 2026, adds a Skills extension. A server can serve a folder of agent skills with loadSkills('./skills') and attach(server), and a client can list those skills and read their files with SkillsClient. It implements SEP-2640, extension identifier io.modelcontextprotocol/skills. The part worth reading twice is not the API. It is the spec's security section, which says skill content is untrusted model input and a higher-risk surface than a remote tool call.

I read the v2.4.0 release notes, the pull request that added the extension, the SDK's server and client skills guides, and the extension spec text at the commit the SDK pins. I did not install the SDK or run the example. What follows is what those documents say.

What shipped

The release notes list "Skills over MCP (SEP-2640)" under New. A server publishes a folder of skills, a client lists, reads and verifies them, and it works on protocol versions 2025-11-25 and 2026-07-28. The notes say attach is experimental and may change in a minor release. The same release has upgrade notes unrelated to skills: x-mcp-header on a number parameter is rejected, as the 2026-07-28 spec requires, and outputSchema built from z.object(...).meta({ id }) is no longer wrapped in { result } on a 2025-11-25 connection.

The pull request says the skills API lives under new ext/skills subpaths, and the package roots load no skills code. It reports that the work passes the SEP-2640 conformance scenarios on both protocol versions.

How a server publishes skills

Per the server guide, each folder holding a SKILL.md is one skill. The frontmatter has name, which must match the folder name, and description. The guide shows skill://git-workflow/SKILL.md and skill://acme/billing/refunds/SKILL.md as the URIs it publishes, one per skill.

Other behavior the guide documents:

• The catalog keeps metadata only: paths, digests, sizes and frontmatter. Each read goes to the folder, and the SDK serves the bytes only if they still match the published digest.
• A file edited on disk gets an error until you call reload(), which rescans and returns added, removed, changed and listChanged.
• Without a file system, memorySkillFiles serves skills defined in code. A custom SkillFiles object with list and read serves them from your own storage.
• On a server built per request through createMcpHandler, you publish a list change on the handler with handler.notify.resourcesChanged().

How a client reads them

SkillsClient.list() returns entries with frontmatter and a file list with digests, and reads no skill file. By default it throws if any entry fails validation or a URI repeats. With skipInvalid: true it returns the valid ones and reports refused entries in invalid.

read(entry) checks size and SHA-256 digest, then compares frontmatter field by field. manifest.body holds the instructions to give the model. A failed check throws SkillVerificationError with a reason of unlisted, size, digest or frontmatter. The guide says that on any reason you should not use the file, and for SKILL.md you should not load the skill. If the server declares directoryRead, the client can list a folder's children through resources/directory/read.

The spec: three methods and two limits

The extension spec adds skills/list, skills/get and an optional resources/directory/read. It delegates the skill format itself to the Agent Skills specification and defines only the transport. Two limits apply per skill: 512 entries in resources, and 16 MiB total file size. A server can mark resources as "dynamic" for generated content, but then the entry offers no content integrity, and the spec says hosts may decline to load such skills.

What the spec says to distrust

The security section opens by calling skill content "instructional text delivered to a model, which makes it a prompt-injection surface". Some of its MUST requirements for hosts:

• Treat MCP-served skill content as untrusted model input. A connected server does not make its content authoritative.
• Tag skill content with its originating server at the point it enters model context, and never present it as indistinguishable from a local filesystem skill.
• Do not allow MCP-served skill content to cause host-side code execution without explicit per-skill user approval. That covers frontmatter hooks and scripts, and body text that tells the model to run a bundled script or arbitrary command.
• Bind resource reads to the skill's originating server. A skill from server A must not cause a read against server B.
• Ignore the Agent Skills allowed-tools field for MCP-origin skills unless the user explicitly approved that grant for that skill.
• Do not let an MCP skill silently shadow a same-named skill from another origin, including local ones.

The spec also says digests are "not a trust anchor". They are unsigned and come from the same server as the content, so a match proves consistency, not trustworthiness, and an intermediary can rewrite both. That matters for the SDK's verification: it catches drift between the listing and the bytes, and per the spec it cannot tell you the server is honest.

What I would check

These are my untested suggestions, not documented behavior.

• If you build a host, read the security section before you wire SkillsClient into a model loop. The SDK verifies digests. The approval gates, origin labels and collision handling are the host's job, and I did not see the SDK do them in the guides I read.
• Show users the server label and the skill text before first load, and treat each skill as one approval.
• If you publish skills, keep them as instructions. A skill that asks the model to run a script will hit the approval gate on a conforming host.
• Pin the SDK version, since attach is documented as experimental.
• Test with skipInvalid both ways so one bad entry does not silently remove a skill you rely on.

What I would not conclude

• I would not conclude other hosts or clients support the extension. The pull request mentions Go, C# and Python behavior in comparisons, but I did not verify any host product.
• I would not conclude the SDK enforces the spec's host security rules. I read guides, not source.
• I would not conclude the 2025-11-25 support is settled. The pull request calls it a backport pending the extension working group.
• I would not treat digest verification as a safety check for the skill's content.

Frequently asked questions

What is the MCP Skills extension?

It is io.modelcontextprotocol/skills, defined by SEP-2640. It lets a server serve Agent Skills, a SKILL.md plus supporting files, as MCP resources, discovered through skills/list and skills/get.

Which SDK version added it to TypeScript?

v2.4.0, published October 23, 2026 per the GitHub release.

How do I serve skills?

Call loadSkills('./skills') from the server package's ext/skills/node subpath, create a server, and call skills.attach(server). The release notes call attach experimental.

How does a client check a skill?

SkillsClient.read checks the file's size and SHA-256 digest against the entry and compares the frontmatter. A failure throws SkillVerificationError.

Are skills safe to load from any server?

The spec says no. It requires hosts to treat skill content as untrusted input, label its origin, gate code execution and ignore allowed-tools unless the user approves.

What are the size limits?

Per the spec, 512 entries per skill and 16 MiB total file size.

Did you run it?

No. I read the release notes, the pull request, the SDK guides and the pinned spec text. I did not install or run the SDK.

Sources

All read on November 3, 2026.

• typescript-sdk v2.4.0 release notes
• Skills extension pull request #3047
• SDK server skills guide
• SDK client skills guide
• ext-skills specification at the pinned commit

Not read: the SDK source code, the Agent Skills specification, the SEP-2640 discussion thread, and any host or client product implementing the extension.