Skip to content

SYSTEM Cited by 1 source

modelcontextprotocol/sdk (TypeScript)

Definition

@modelcontextprotocol/sdk is the official TypeScript / JavaScript SDK for building Model Context Protocol servers and clients. It exports high-level constructors (McpServer, ResourceTemplate) plus lower-level primitives that let server authors register tools, resources, and prompts without writing the wire-level JSON-RPC themselves. Canonical package name on npm: @modelcontextprotocol/sdk. Published by the modelcontextprotocol project maintainers (Source: sources/2026-01-08-wix-mcp-resources-all-you-need-to-know).

Version disclosed on this wiki

  • ^1.8.0 — the version exercised in the Wix Engineering 2026-01-08 tutorial. All production caveats documented below are against this version.

Primary exports

import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
  • McpServer — constructor for an MCP server. Takes an identity block ({ name, version }) and a capabilities block ({ capabilities: { tools: {}, resources: { subscribe: true } } }).
  • ResourceTemplate — wrapper for a parameterised resource URI per RFC 6570 URI templates. Constructor takes the template URI and an optional { list } callback for exposing individual resource instances.
  • server.tool(name, description, paramsSchema, handler) — registers an MCP tool.
  • server.registerResource(name, uriOrTemplate, metadata, handler) — registers an MCP resource.
  • server.server.sendResourceUpdated({ uri }) — emits notifications/resources/updated for a given resource URI.

Three documented production caveats

All from the Wix 2026-01-08 tutorial, all against v1.8.0:

1. The JavaScript URL constructor breaks file:// resource URIs

Verbatim: "the JavaScript URL constructor (which is used under the hood in @modelcontextprotocol/sdk) has custom handling for known schemes, which can cause unpredictable behavior. For example, for file:// it adds trailing slash, which causes URI change from file://example.txt to file://example.txt/, so your client always receives 'Resource not found' error."

Fix: use a custom URI scheme (doc://, log://, git://, resource://) that the JavaScript URL constructor treats as opaque rather than applying built-in handlers.

2. The subscribe method is not implemented

Verbatim: "The @modelcontextprotocol/sdk server doesn't implement the subscribe method (at least in version ^1.8.0), so you might want to implement it yourself. However, even without subscribe implementation, updates will work but with some limitations: Clients calling subscribe will get 'method not found' error; Clients will receive notifications/resources/updated if you set capabilities.resources.subscribe: true."

Server authors needing per-subscriber targeting must implement the subscribe method themselves on top of the SDK.

3. No subscriber targeting — fan-out to all clients

Verbatim: "Server doesn't track subscribers, so it sends ALL resource updates to ALL clients."

Production implication: for a server with N connected clients each interested in a disjoint subset of resources, every client still receives every resources/updated notification. Scale authors must implement filtering themselves.

Variable handling in template resources

When a ResourceTemplate handler receives variables extracted from the URI, each variable may be either a string or a string[] per the RFC 6570 specification. Defensive handler code from the Wix tutorial:

async (uri, variables) => {
  const rawUserId: undefined | string | string[] = variables.userId;
  const userId = Array.isArray(rawUserId) ? rawUserId[0] : rawUserId;
  if (!userId) throw new Error('userId parameter is required');
  // ...
}

Ecosystem position

@modelcontextprotocol/sdk is the reference TypeScript implementation of MCP. Other language SDKs exist with different trade-offs:

The SDK-specific caveats above (URL constructor, subscribe method) are TypeScript-SDK implementation artefacts, not MCP-protocol constraints. Implementers on other language SDKs may hit different or no gotchas.

Seen in

Last updated · 476 distilled / 1,218 read