Troubleshooting

Each heading on this page is the verbatim error message. Match yours, then apply that entry's fix.

SyntaxError: Unexpected token ... is not valid JSON

On stdio, standard output is the wire: the host parses every line your server writes to stdout as JSON-RPC. One console.log — yours or a dependency's — puts a stray line on it, and the host reports that line with this error. Log to stderr instead; serveStdio owns stdout, and console.error is safe anywhere in the process.

import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';

serveStdio(() => {
    const server = new McpServer({ name: 'app', version: '1.0.0' });
    console.error('app server running on stdio'); // stderr — never console.log
    return server;
});

The host shows the stderr line in the server's log and keeps parsing stdout cleanly. Serve over stdio covers the entry point.

::: tip The quoted token is the first character of the stray line, which usually identifies the call that wrote it. :::

TS2589: Type instantiation is excessively deep and possibly infinite

Two copies of zod in the dependency tree. The SDK derives its tool, prompt and resource types from Zod v4 schemas; a second zod copy makes TypeScript instantiate cross-version types until it hits its recursion limit and fails at an unrelated-looking call site.

List every installed copy:

npm ls zod        # or: pnpm why zod / yarn why zod

Align everything on one Zod 4 version. When a transitive dependency pins another copy, force one with your package manager's override field (overrides for npm and pnpm, resolutions for Yarn):

{
    "overrides": {
        "zod": "^4.2.0"
    }
}

npm ls zod reporting a single version means the duplicate is gone and the error with it.

ReferenceError: crypto is not defined

The OAuth client helpers sign and verify through the Web Crypto API at globalThis.crypto. Every @modelcontextprotocol/* package requires Node.js 20, where that global is always defined — this error means the process is running on an older runtime (Node.js 18 and earlier).

Upgrade Node.js. Where you cannot, assign the polyfill from node:crypto before anything touches the SDK:

import { webcrypto } from 'node:crypto';

if (typeof globalThis.crypto === 'undefined') {
    globalThis.crypto = webcrypto;
}

With the global in place the client OAuth flows run unchanged.

SdkError: ERA_NEGOTIATION_FAILED

connect() found no protocol era both sides speak. Two shapes produce it: versionNegotiation: { mode: { pin: ... } } names a revision the server does not offer over server/discover, and pinning never falls back; or mode: 'auto' with a supportedProtocolVersions list that has no pre-2026 entry, which removes the legacy fallback.

The pinned shape — transport here reaches a server still on the 2025 revisions (Test a server shows the in-memory wiring these outputs come from):

const pinned = new Client({ name: 'app', version: '1.0.0' }, { versionNegotiation: { mode: { pin: '2026-07-28' } } });

try {
    await pinned.connect(transport);
} catch (error) {
    if (!(error instanceof SdkError)) throw error;
    console.log(`${error.code}: ${error.message}`);
}

The rejection names the pinned revision the server never offered:

ERA_NEGOTIATION_FAILED: Version negotiation failed: the server did not offer pinned protocol version 2026-07-28 via server/discover (no fallback in pin mode)

Change the mode to 'auto': the probe falls back to the 2025 initialize handshake on the same connection.

const negotiated = new Client({ name: 'app', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });

await negotiated.connect(transport);
console.log(negotiated.getProtocolEra());

connect() resolves and the client reports the era it landed on:

legacy

Keep { pin } where a legacy connection is unacceptable and a hard failure is the behavior you want. Protocol versions defines the eras and what each negotiation mode offers.

SdkError: METHOD_NOT_SUPPORTED_BY_PROTOCOL_VERSION

You sent a spec method the negotiated protocol era does not define. The SDK raises this locally — nothing reached the transport — and the message names the method, the negotiated revision, and the era-appropriate replacement.

subscriptions/listen exists only on a 2026-07-28 connection; this client negotiated a 2025 era, the default:

const client = new Client({ name: 'app', version: '1.0.0' });
await client.connect(transport);

try {
    await client.listen({ resourceSubscriptions: ['file:///logs/app.log'] });
} catch (error) {
    if (!(error instanceof SdkError)) throw error;
    console.log(`${error.code}: ${error.message}`);
}

The message carries the fix:

METHOD_NOT_SUPPORTED_BY_PROTOCOL_VERSION: subscriptions/listen requires a 2026-07-28-era connection (negotiated: 2025-11-25). On a 2025-era connection, change notifications are delivered unsolicited: use ClientOptions.listChanged and resources/subscribe instead.

Either negotiate the era that defines the method — versionNegotiation: { mode: 'auto' } against a server that serves 2026-07-28, as in the previous entry — or call the surface the negotiated era does define. Subscriptions covers both delivery models; Protocol versions lists which methods each era defines.

Module '"@modelcontextprotocol/server"' has no exported member 'SSEServerTransport'

@modelcontextprotocol/server no longer ships the server-side SSE transport, and the OAuth Authorization Server helpers (mcpAuthRouter, ProxyOAuthServerProvider) left with it. Both live on as a frozen v1 copy in @modelcontextprotocol/server-legacy.

Rewrite the imports:

- import { SSEServerTransport } from '@modelcontextprotocol/server';
+ import { SSEServerTransport } from '@modelcontextprotocol/server-legacy/sse';

- import { mcpAuthRouter, ProxyOAuthServerProvider } from '@modelcontextprotocol/server';
+ import { mcpAuthRouter, ProxyOAuthServerProvider } from '@modelcontextprotocol/server-legacy/auth';

The Resource Server helpers did not move there: requireBearerAuth, mcpAuthMetadataRouter and OAuthTokenVerifier are first-class in @modelcontextprotocol/express — see Authorization. @modelcontextprotocol/server-legacy is frozen and receives no new features; serve new code over Streamable HTTP, which still reaches 2025-era clients through legacy client support. A client limited to the HTTP+SSE transport is the one case that still needs the frozen @modelcontextprotocol/server-legacy/sse import above.

Recap

• Every heading on this page is the exact message you searched for.
• On stdio, stdout carries JSON-RPC; log with console.error.
• TS2589 means two zod copies in the dependency tree.
• The SDK raises ERA_NEGOTIATION_FAILED and METHOD_NOT_SUPPORTED_BY_PROTOCOL_VERSION locally — neither is a wire error.
• Server SSE and the Authorization Server helpers live in @modelcontextprotocol/server-legacy.

Source: docs/troubleshooting.md