feat(core): custom-method overloads + deprecated v1 schema-arg shims + ProtocolSpec generic

Adds to Protocol (inherited by Client/Server):
- 3-arg setRequestHandler/setNotificationHandler(method: string, paramsSchema, handler) for custom (non-spec) methods
- @deprecated setRequestHandler/setNotificationHandler(ZodSchema, handler) v1-compat overloads
- @deprecated request(req, ResultSchema)/callTool(params, ResultSchema) v1-compat overloads
- Method-keyed request() return type: request({method:M}) returns ResultTypeMap[M]
- ProtocolSpec generic as 2nd param (Protocol<ContextT, S = McpSpec>) for typed custom vocabularies

Protocol stays abstract; Client/Server are the concrete implementations.
Also: migration docs + examples for custom-method overloads.

Author: felixweinberger

.changeset/deprecate-helper.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Add internal `deprecate()` warn-once helper for v1-compat shims.

.changeset/protocol-concrete.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+Make `Protocol` concrete and exported. `setRequestHandler`/`setNotificationHandler`/`request`/`notification` gain a 3-arg `(method: string, paramsSchema, handler)` overload for non-standard methods alongside the spec-typed form. Optional `Protocol<S extends ProtocolSpec>` generic
+for declaring a typed method vocabulary. The five `assert*Capability` abstracts are now no-op virtuals (`Client`/`Server` override to enforce).

docs/migration-SKILL.md

@@ -377,6 +377,21 @@ Schema to method string mapping:
 
 Request/notification params remain fully typed. Remove unused schema imports after migration.
 
+**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — use the three-arg overloads of `setRequestHandler`/`setNotificationHandler`/`request`. `Protocol` is now concrete and exported, so MCP-dialect protocols can subclass it directly:
+
+| v1                                                           | v2                                                                             |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `setRequestHandler(CustomReqSchema, (req, extra) => ...)`    | `setRequestHandler('vendor/method', ParamsSchema, (params, ctx) => ...)` |
+| `setNotificationHandler(CustomNotifSchema, n => ...)`        | `setNotificationHandler('vendor/method', ParamsSchema, params => ...)`   |
+| `this.request({ method: 'vendor/x', params }, ResultSchema)` | `this.request('vendor/x', params, ResultSchema)`                     |
+| `this.notification({ method: 'vendor/x', params })`          | unchanged                                                                      |
+| `class X extends Protocol<Req, Notif, Res>`                  | `class X extends Client` (or `Server`), or compose a `Client` instance         |
+
+`notification()` keeps a single object-form signature so tests can replace it with a mock without TS overload-intersection errors. To send a custom notification, use `notification({ method: 'vendor/x', params })` (unchanged from v1).
+
+The v1 schema's `.shape.params` becomes the `ParamsSchema` argument; the `method: z.literal('...')` value becomes the string argument.
+
+
 ## 10. Request Handler Context Types
 
 `RequestHandlerExtra` → structured context types with nested groups. Rename `extra` → `ctx` in all handler callbacks.

docs/migration.md

@@ -382,6 +382,52 @@ Common method string replacements:
 | `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
 | `PromptListChangedNotificationSchema`   | `'notifications/prompts/list_changed'`   |
 
+### Custom (non-standard) protocol methods
+
+In v1, vendor-specific methods were registered the same way as spec methods (`setRequestHandler(zodSchemaWithMethodLiteral, handler)`), and `Protocol<SendRequestT, SendNotificationT, SendResultT>` widened the send-side type unions.
+
+In v2, `Protocol` is concrete and exported. Its `setRequestHandler`, `setNotificationHandler`, `request` and `notification` each have a string-method overload that accepts any method name with a caller-supplied params/result schema:
+
+**Before (v1):**
+
+```typescript
+import { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+class App extends Protocol<AppRequest, AppNotification, AppResult> {
+    constructor() {
+        super();
+        this.setRequestHandler(SearchRequestSchema, req => ({ hits: [req.params.query] }));
+    }
+    search(query: string) {
+        return this.request({ method: 'acme/search', params: { query } }, SearchResultSchema);
+    }
+}
+```
+
+**After (v2):**
+
+```typescript
+import { Protocol, type ProtocolSpec } from '@modelcontextprotocol/client';
+
+type AppSpec = {
+    requests: { 'acme/search': { params: { query: string }; result: { hits: string[] } } };
+} satisfies ProtocolSpec;
+
+class App extends Protocol<AppSpec> {
+    constructor() {
+        super();
+        this.setRequestHandler('acme/search', SearchParams, params => ({ hits: [params.query] }));
+    }
+    search(query: string) {
+        return this.request('acme/search', { query }, SearchResult);
+    }
+}
+```
+
+The `ProtocolSpec` type argument is optional — omit it for ad-hoc method strings without autocomplete. For a single vendor method on a stock `Client` or `Server`, call the three-arg overload directly: `server.setRequestHandler('acme/search', SearchParams, handler)`.
+
+The five `assert*Capability` abstract methods are now no-op virtuals on `Protocol`, so subclasses no longer need to stub them.
+
 ### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
 
 The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer accept a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas

examples/client/README.md

@@ -36,6 +36,7 @@ Most clients expect a server to be running. Start one from [`../server/README.md
 | Client credentials (M2M)                            | Machine-to-machine OAuth client credentials example.                                      | [`src/simpleClientCredentials.ts`](src/simpleClientCredentials.ts)                         |
 | URL elicitation client                              | Drives URL-mode elicitation flows (sensitive input in a browser).                         | [`src/elicitationUrlExample.ts`](src/elicitationUrlExample.ts)                             |
 | Task interactive client                             | Demonstrates task-based execution + interactive server→client requests.                   | [`src/simpleTaskInteractiveClient.ts`](src/simpleTaskInteractiveClient.ts)                 |
+| Custom (non-standard) methods client                | Sends `acme/*` custom requests and handles custom server notifications.                   | [`src/customMethodExample.ts`](src/customMethodExample.ts)                                 |
 
 ## URL elicitation example (server + client)
 

examples/client/src/customMethodExample.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Calling vendor-specific (non-spec) JSON-RPC methods from a `Client`.
+ *
+ * - Send a custom request: 3-arg `client.request(method, params, resultSchema)`
+ * - Send a custom notification: `client.notification({ method, params })` (unchanged from v1)
+ * - Receive a custom notification: 3-arg `client.setNotificationHandler(method, paramsSchema, handler)`
+ *
+ * These overloads are on `Client` and `Server` directly — you do NOT need a raw
+ * `Protocol` instance for custom methods.
+ *
+ * Pair with the server in examples/server/src/customMethodExample.ts.
+ */
+
+import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
+import { z } from 'zod';
+
+const SearchResult = z.object({ hits: z.array(z.string()) });
+const ProgressParams = z.object({ stage: z.string(), pct: z.number() });
+
+const client = new Client({ name: 'custom-method-client', version: '1.0.0' }, { capabilities: {} });
+
+client.setNotificationHandler('acme/searchProgress', ProgressParams, p => {
+    console.log(`[client] progress: ${p.stage} ${p.pct}%`);
+});
+
+await client.connect(new StdioClientTransport({ command: 'node', args: ['../server/dist/customMethodExample.js'] }));
+
+const r = await client.request('acme/search', { query: 'widgets' }, SearchResult);
+console.log('[client] hits=' + JSON.stringify(r.hits));
+
+await client.notification({ method: 'acme/tick', params: { n: 1 } });
+await client.notification({ method: 'acme/tick', params: { n: 2 } });
+
+await client.close();

examples/server/README.md

@@ -38,6 +38,7 @@ pnpm tsx src/simpleStreamableHttp.ts
 | Task interactive server                   | Task-based execution with interactive server→client requests.                                   | [`src/simpleTaskInteractive.ts`](src/simpleTaskInteractive.ts)                           |
 | Hono Streamable HTTP server               | Streamable HTTP server built with Hono instead of Express.                                      | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
 | SSE polling demo server                   | Legacy SSE server intended for polling demos.                                                   | [`src/ssePollingExample.ts`](src/ssePollingExample.ts)                                   |
+| Custom (non-standard) methods server      | Registers `acme/*` custom request handlers and sends custom notifications.                      | [`src/customMethodExample.ts`](src/customMethodExample.ts)                               |
 
 ## OAuth demo flags (Streamable HTTP server)
 

examples/server/src/customMethodExample.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Registering vendor-specific (non-spec) JSON-RPC methods on a `Server`.
+ *
+ * Custom methods use the 3-arg form of `setRequestHandler` / `setNotificationHandler`:
+ * pass the method string, a params schema, and the handler. The same overload is
+ * available on `Client` (for server→client custom methods) — you do NOT need a raw
+ * `Protocol` instance for this.
+ *
+ * To call these from the client side, use:
+ *   await client.request('acme/search', { query: 'widgets' }, SearchResult)
+ *   await client.notification({ method: 'acme/tick', params: { n: 1 } })
+ * See examples/client/src/customMethodExample.ts.
+ */
+
+import { Server, StdioServerTransport } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+
+const SearchParams = z.object({ query: z.string() });
+const TickParams = z.object({ n: z.number() });
+
+const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
+
+server.setRequestHandler('acme/search', SearchParams, params => {
+    console.log('[server] acme/search query=' + params.query);
+    return { hits: [params.query, params.query + '-result'] };
+});
+
+server.setNotificationHandler('acme/tick', TickParams, p => {
+    console.log('[server] acme/tick n=' + p.n);
+});
+
+await server.connect(new StdioServerTransport());