[pull] main from modelcontextprotocol:main

.changeset/fix-abort-listener-leak.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Consolidate per-request cleanup in `_requestWithSchema` into a single `.finally()` block. This fixes an abort signal listener leak (listeners accumulated when a caller reused one `AbortSignal` across requests) and two cases where `_responseHandlers` entries leaked on send-failure paths.

.changeset/fix-oauth-5xx-discovery.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Continue OAuth metadata discovery on 502 (Bad Gateway) responses, matching the existing behavior for 4xx. This fixes MCP servers behind reverse proxies that return 502 for path-aware metadata URLs. Other 5xx errors still throw to avoid retrying against overloaded servers.

.changeset/fix-session-status-codes.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/examples-server': patch
+---
+
+Example servers now return HTTP 404 (not 400) when a request includes an unknown session ID, so clients can correctly detect they need to start a new session. Requests missing a session ID entirely still return 400.

.changeset/remove-websocket-transport.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': major
+---
+
+Remove `WebSocketClientTransport`. WebSocket is not a spec-defined transport; use stdio or Streamable HTTP. The `Transport` interface remains exported for custom implementations. See #142.

.changeset/schema-object-type-for-unions.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Ensure `standardSchemaToJsonSchema` emits `type: "object"` at the root, fixing discriminated-union tool/prompt schemas that previously produced `{oneOf: [...]}` without the MCP-required top-level type. Also throws a clear error when given an explicitly non-object schema (e.g. `z.string()`). Fixes #1643.

docs/migration-SKILL.md

@@ -43,7 +43,7 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
 | `@modelcontextprotocol/sdk/client/streamableHttp.js` | `@modelcontextprotocol/client` |
 | `@modelcontextprotocol/sdk/client/sse.js`            | `@modelcontextprotocol/client` |
 | `@modelcontextprotocol/sdk/client/stdio.js`          | `@modelcontextprotocol/client` |
-| `@modelcontextprotocol/sdk/client/websocket.js`      | `@modelcontextprotocol/client` |
+| `@modelcontextprotocol/sdk/client/websocket.js`      | REMOVED (use Streamable HTTP or stdio; implement `Transport` for custom needs) |
 
 ### Server imports
 
@@ -96,6 +96,7 @@ Notes:
 | `ErrorCode.RequestTimeout`               | `SdkErrorCode.RequestTimeout`                            |
 | `ErrorCode.ConnectionClosed`             | `SdkErrorCode.ConnectionClosed`                          |
 | `StreamableHTTPError`                    | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
+| `WebSocketClientTransport`               | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`) |
 
 All other symbols from `@modelcontextprotocol/sdk/types.js` retain their original names (e.g., `CallToolResultSchema`, `ListToolsResultSchema`, etc.).
 

docs/migration.md

@@ -110,6 +110,26 @@ const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: ()
 
 The SSE transport has been removed from the server. Servers should migrate to Streamable HTTP. The client-side SSE transport remains available for connecting to legacy SSE servers.
 
+### `WebSocketClientTransport` removed
+
+`WebSocketClientTransport` has been removed. WebSocket is not a spec-defined MCP transport, and keeping it in the SDK encouraged transport proliferation without a conformance baseline.
+
+Use `StdioClientTransport` for local servers or `StreamableHTTPClientTransport` for remote servers. If you need WebSocket for a custom deployment, implement the `Transport` interface directly — it remains exported from `@modelcontextprotocol/client`.
+
+**Before (v1):**
+
+```typescript
+import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
+const transport = new WebSocketClientTransport(new URL('ws://localhost:3000'));
+```
+
+**After (v2):**
+
+```typescript
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'));
+```
+
 ### Server auth removed
 
 Server-side OAuth/auth has been removed entirely from the SDK. This includes `mcpAuthRouter`, `OAuthServerProvider`, `OAuthTokenVerifier`, `requireBearerAuth`, `authenticateClient`, `ProxyOAuthServerProvider`, `allowedMethods`, and all associated types.

examples/server/src/elicitationFormExample.ts

@@ -364,14 +364,17 @@ async function main() {
 
                 await transport.handleRequest(req, res, req.body);
                 return;
+            } else if (sessionId) {
+                res.status(404).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32_001, message: 'Session not found' },
+                    id: null
+                });
+                return;
             } else {
-                // Invalid request - no session ID or not initialization request
                 res.status(400).json({
                     jsonrpc: '2.0',
-                    error: {
-                        code: -32_000,
-                        message: 'Bad Request: No valid session ID provided'
-                    },
+                    error: { code: -32_000, message: 'Bad Request: Session ID required' },
                     id: null
                 });
                 return;
@@ -399,8 +402,12 @@ async function main() {
     // Handle GET requests for SSE streams
     const mcpGetHandler = async (req: Request, res: Response) => {
         const sessionId = req.headers['mcp-session-id'] as string | undefined;
-        if (!sessionId || !transports[sessionId]) {
-            res.status(400).send('Invalid or missing session ID');
+        if (!sessionId) {
+            res.status(400).send('Missing session ID');
+            return;
+        }
+        if (!transports[sessionId]) {
+            res.status(404).send('Session not found');
             return;
         }
 
@@ -414,8 +421,12 @@ async function main() {
     // Handle DELETE requests for session termination
     const mcpDeleteHandler = async (req: Request, res: Response) => {
         const sessionId = req.headers['mcp-session-id'] as string | undefined;
-        if (!sessionId || !transports[sessionId]) {
-            res.status(400).send('Invalid or missing session ID');
+        if (!sessionId) {
+            res.status(400).send('Missing session ID');
+            return;
+        }
+        if (!transports[sessionId]) {
+            res.status(404).send('Session not found');
             return;
         }
 

examples/server/src/elicitationUrlExample.ts

@@ -606,14 +606,17 @@ const mcpPostHandler = async (req: Request, res: Response) => {
 
             await transport.handleRequest(req, res, req.body);
             return; // Already handled
+        } else if (sessionId) {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32_001, message: 'Session not found' },
+                id: null
+            });
+            return;
         } else {
-            // Invalid request - no session ID or not initialization request
             res.status(400).json({
                 jsonrpc: '2.0',
-                error: {
-                    code: -32_000,
-                    message: 'Bad Request: No valid session ID provided'
-                },
+                error: { code: -32_000, message: 'Bad Request: Session ID required' },
                 id: null
             });
             return;
@@ -643,8 +646,12 @@ app.post('/mcp', authMiddleware, mcpPostHandler);
 // Handle GET requests for SSE streams (using built-in support from StreamableHTTP)
 const mcpGetHandler = async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 
@@ -682,8 +689,12 @@ app.get('/mcp', authMiddleware, mcpGetHandler);
 // Handle DELETE requests for session termination (according to MCP spec)
 const mcpDeleteHandler = async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 

examples/server/src/jsonResponseStreamableHttp.ts

@@ -110,14 +110,17 @@ app.post('/mcp', async (req: Request, res: Response) => {
             await server.connect(transport);
             await transport.handleRequest(req, res, req.body);
             return; // Already handled
+        } else if (sessionId) {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32_001, message: 'Session not found' },
+                id: null
+            });
+            return;
         } else {
-            // Invalid request - no session ID or not initialization request
             res.status(400).json({
                 jsonrpc: '2.0',
-                error: {
-                    code: -32_000,
-                    message: 'Bad Request: No valid session ID provided'
-                },
+                error: { code: -32_000, message: 'Bad Request: Session ID required' },
                 id: null
             });
             return;

examples/server/src/simpleStreamableHttp.ts

@@ -689,14 +689,17 @@ const mcpPostHandler = async (req: Request, res: Response) => {
 
             await transport.handleRequest(req, res, req.body);
             return; // Already handled
+        } else if (sessionId) {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32_001, message: 'Session not found' },
+                id: null
+            });
+            return;
         } else {
-            // Invalid request - no session ID or not initialization request
             res.status(400).json({
                 jsonrpc: '2.0',
-                error: {
-                    code: -32_000,
-                    message: 'Bad Request: No valid session ID provided'
-                },
+                error: { code: -32_000, message: 'Bad Request: Session ID required' },
                 id: null
             });
             return;
@@ -730,8 +733,12 @@ if (useOAuth && authMiddleware) {
 // Handle GET requests for SSE streams (using built-in support from StreamableHTTP)
 const mcpGetHandler = async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 
@@ -761,8 +768,12 @@ if (useOAuth && authMiddleware) {
 // Handle DELETE requests for session termination (according to MCP spec)
 const mcpDeleteHandler = async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 

examples/server/src/simpleTaskInteractive.ts

@@ -670,10 +670,17 @@ app.post('/mcp', async (req: Request, res: Response) => {
             await server.connect(transport);
             await transport.handleRequest(req, res, req.body);
             return;
+        } else if (sessionId) {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32_001, message: 'Session not found' },
+                id: null
+            });
+            return;
         } else {
             res.status(400).json({
                 jsonrpc: '2.0',
-                error: { code: -32_000, message: 'Bad Request: No valid session ID' },
+                error: { code: -32_000, message: 'Bad Request: Session ID required' },
                 id: null
             });
             return;
@@ -695,8 +702,12 @@ app.post('/mcp', async (req: Request, res: Response) => {
 // Handle GET requests for SSE streams
 app.get('/mcp', async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 
@@ -707,8 +718,12 @@ app.get('/mcp', async (req: Request, res: Response) => {
 // Handle DELETE requests for session termination
 app.delete('/mcp', async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 

examples/server/src/standaloneSseWithGetStreamableHttp.ts

@@ -86,14 +86,17 @@ app.post('/mcp', async (req: Request, res: Response) => {
             // Handle the request - the onsessioninitialized callback will store the transport
             await transport.handleRequest(req, res, req.body);
             return; // Already handled
+        } else if (sessionId) {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32_001, message: 'Session not found' },
+                id: null
+            });
+            return;
         } else {
-            // Invalid request - no session ID or not initialization request
             res.status(400).json({
                 jsonrpc: '2.0',
-                error: {
-                    code: -32_000,
-                    message: 'Bad Request: No valid session ID provided'
-                },
+                error: { code: -32_000, message: 'Bad Request: Session ID required' },
                 id: null
             });
             return;
@@ -119,8 +122,12 @@ app.post('/mcp', async (req: Request, res: Response) => {
 // Handle GET requests for SSE streams (now using built-in support from StreamableHTTP)
 app.get('/mcp', async (req: Request, res: Response) => {
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
+    if (!sessionId) {
+        res.status(400).send('Missing session ID');
+        return;
+    }
+    if (!transports[sessionId]) {
+        res.status(404).send('Session not found');
         return;
     }
 

package.json

@@ -60,7 +60,6 @@
         "@types/express-serve-static-core": "catalog:devTools",
         "@types/node": "^24.10.1",
         "@types/supertest": "catalog:devTools",
-        "@types/ws": "catalog:devTools",
         "@typescript/native-preview": "catalog:devTools",
         "eslint": "catalog:devTools",
         "eslint-config-prettier": "catalog:devTools",
@@ -75,7 +74,6 @@
         "typescript": "catalog:devTools",
         "typescript-eslint": "catalog:devTools",
         "vitest": "catalog:devTools",
-        "ws": "catalog:devTools",
         "zod": "catalog:runtimeShared"
     },
     "resolutions": {

packages/client/src/client/auth.ts

@@ -1035,7 +1035,9 @@ async function tryMetadataDiscovery(url: URL, protocolVersion: string, fetchFn:
  * Determines if fallback to root discovery should be attempted
  */
 function shouldAttemptFallback(response: Response | undefined, pathname: string): boolean {
-    return !response || (response.status >= 400 && response.status < 500 && pathname !== '/');
+    if (!response) return true; // CORS error — always try fallback
+    if (pathname === '/') return false; // Already at root
+    return (response.status >= 400 && response.status < 500) || response.status === 502;
 }
 
 /**
@@ -1062,7 +1064,7 @@ async function discoverMetadataWithFallback(
 
     let response = await tryMetadataDiscovery(url, protocolVersion, fetchFn);
 
-    // If path-aware discovery fails with 404 and we're not already at root, try fallback to root discovery
+    // If path-aware discovery fails (4xx or 502 Bad Gateway) and we're not already at root, try fallback to root discovery
     if (!opts?.metadataUrl && shouldAttemptFallback(response, issuer.pathname)) {
         const rootUrl = new URL(`/.well-known/${wellKnownType}`, issuer);
         response = await tryMetadataDiscovery(rootUrl, protocolVersion, fetchFn);
@@ -1230,9 +1232,8 @@ export async function discoverAuthorizationServerMetadata(
 
         if (!response.ok) {
             await response.text?.().catch(() => {});
-            // Continue looking for any 4xx response code.
-            if (response.status >= 400 && response.status < 500) {
-                continue; // Try next URL
+            if ((response.status >= 400 && response.status < 500) || response.status === 502) {
+                continue; // Try next URL for 4xx or 502 (Bad Gateway)
             }
             throw new Error(
                 `HTTP ${response.status} trying to load ${type === 'oauth' ? 'OAuth' : 'OpenID provider'} metadata from ${endpointUrl}`