shape	reference

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, or the negotiation probe was cut short. Match the message tail:

• the server did not offer pinned protocol version ... via server/discover (no fallback in pin mode) — the pin names a revision the server does not offer, and pinning never falls back: drop the pin or use 'auto'.
• the connection closed during the server/discover probe before the server offered pinned protocol version ... — same pin, but the server exited on the probe (an exit-on-probe legacy server): use 'auto'.
• the server gave no modern evidence and this client supports no pre-2026-07-28 protocol version to fall back to — or its the connection closed during the server/discover probe and this client supports no ... variant — mode: 'auto' with a modern-only supportedProtocolVersions list removes the legacy fallback: restore a pre-2026 entry.
• the connection closed during the server/discover probe (this transport probed in place — the disposable sibling probe requires the SDK's base StdioClientTransport) — a subclass of StdioClientTransport, or a custom stdio-shaped transport, probed in place and met a server that exits on any pre-initialize request: use the base StdioClientTransport (which probes on a disposable sibling), or mode: 'legacy'.
• the transport was closed during the server/discover probe — the caller closed the transport while the probe was in flight; the connect aborted deliberately and the session child was never spawned.
• Version negotiation probe failed: ... — the probe hit a transport failure (network outage, HTTP connection drop): fix connectivity and retry.
• the server answered the probe with HTTP 5xx — the server or a proxy in front of it failed (mid-deploy, crashed backend); not era evidence, so no legacy fallback is attempted: retry once the deployment is healthy.

A 401/403 probe rejection is not this code — see the next section.

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.

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.

Version negotiation failed: the server requires authorization (HTTP 401)

SdkHttpError with code CLIENT_HTTP_AUTHENTICATION (error.status === 401): the negotiation probe hit an auth wall and no authProvider is configured. Auth status is never protocol-era evidence, so connect() fails typed instead of guessing an era. Pass an authProvider — { token: async () => myApiKey } for bearer tokens, or an OAuthClientProvider for OAuth flows (the connect-time UnauthorizedError → finishAuth() → reconnect cycle then works in every negotiation mode).

The 403 sibling — Version negotiation failed: the server denied access (HTTP 403), code CLIENT_HTTP_FORBIDDEN — means the server refused the request outright (IP allowlist, org policy, revoked key). Fix access; this is not a protocol mismatch. (A 403 whose WWW-Authenticate challenge carries error="insufficient_scope" instead rejects with InsufficientScopeError — request the challenged scope.)

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.

SSE stream disconnected: TypeError: terminated

HTTP SSE streams emit a : keepalive comment every 15 seconds by default so client body-idle timeouts and intermediaries do not terminate an otherwise idle connection. Configure the interval with keepAliveMs on the transport or createMcpHandler; set it to 0 to disable heartbeats.

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.