chore: renumber draft error codes per modelcontextprotocol#2907 (#353)

The error-code allocation policy in modelcontextprotocol#2907 renumbers
the draft-only codes: HeaderMismatch -32001 -> -32020,
MissingRequiredClientCapability -32003 -> -32021,
UnsupportedProtocolVersion -32004 -> -32022. This updates every
reference in the suite (mocks, scenarios, fixtures, tests, traceability
yaml) and re-syncs the vendored draft schema to that commit.

src/seps/traceability.json is generated and intentionally left for the
scheduled refresh workflow.

Author: felixweinberger

examples/clients/typescript/everything-client.ts

@@ -265,12 +265,8 @@ async function runRequestMetadataClient(serverUrl: string): Promise<void> {
       const clone = response.clone();
       try {
         const errorResult = await clone.json();
-        // -32004 is UnsupportedProtocolVersionError in the draft schema;
-        // -32001 is tolerated for servers that predate the dedicated code.
-        if (
-          errorResult.error?.code === -32004 ||
-          errorResult.error?.code === -32001
-        ) {
+        // UnsupportedProtocolVersionError is -32022 in the draft schema.
+        if (errorResult.error?.code === -32022) {
           logger.debug(
             'Received UnsupportedProtocolVersionError, starting negotiation...'
           );

examples/servers/typescript/everything-server.ts

@@ -1260,7 +1260,7 @@ app.post('/mcp', async (req, res) => {
       return res.status(400).json({
         jsonrpc: '2.0',
         id,
-        error: { code: -32001, message: 'Missing MCP-Protocol-Version header' }
+        error: { code: -32020, message: 'Missing MCP-Protocol-Version header' }
       });
     }
 
@@ -1283,25 +1283,25 @@ app.post('/mcp', async (req, res) => {
       });
     }
 
-    // Header Mismatch Verification (-32001, HTTP 400)
+    // Header Mismatch Verification (-32020, HTTP 400)
     if (reqVersion !== metaVersion) {
       return res.status(400).json({
         jsonrpc: '2.0',
         id,
         error: {
-          code: -32001,
+          code: -32020,
           message: 'Mismatched MCP-Protocol-Version header'
         }
       });
     }
 
-    // Protocol Version Negotiation Matrix (-32004, HTTP 400)
+    // Protocol Version Negotiation Matrix (-32022, HTTP 400)
     if (metaVersion !== '2026-07-28') {
       return res.status(400).json({
         jsonrpc: '2.0',
         id,
         error: {
-          code: -32004,
+          code: -32022,
           message: 'UnsupportedProtocolVersionError',
           data: {
             supported: ['2026-07-28'],
@@ -1655,13 +1655,13 @@ app.post('/mcp', async (req, res) => {
       if (name === 'test_missing_capability') {
         const clientCaps = meta['io.modelcontextprotocol/clientCapabilities'];
 
-        // Missing Required Client Capability Check (-32003, HTTP 400)
+        // Missing Required Client Capability Check (-32021, HTTP 400)
         if (!clientCaps?.sampling) {
           return res.status(400).json({
             jsonrpc: '2.0',
             id,
             error: {
-              code: -32003,
+              code: -32021,
               message: 'MissingRequiredClientCapabilityError',
               data: { requiredCapabilities: ['sampling'] }
             }

src/mock-server/mock-server.test.ts

@@ -100,7 +100,7 @@ describe('validateStatelessRequest', () => {
     });
   });
 
-  it('rejects versions outside the supported list with -32004 and echoes it', () => {
+  it('rejects versions outside the supported list with -32022 and echoes it', () => {
     const v = validateStatelessRequest(
       {
         headers: { 'mcp-protocol-version': '2099-01-01' },
@@ -124,7 +124,7 @@ describe('validateStatelessRequest', () => {
       status: 400,
       body: {
         error: {
-          code: -32004,
+          code: -32022,
           data: { supported: [DRAFT_PROTOCOL_VERSION], requested: '2099-01-01' }
         }
       }
@@ -216,7 +216,7 @@ describe('createServerStateless', () => {
         params: { _meta: meta }
       });
       expect(status).toBe(400);
-      expect(body.error.code).toBe(-32001);
+      expect(body.error.code).toBe(-32020);
     } finally {
       await srv.close();
     }
@@ -258,7 +258,7 @@ describe('createServerStateless', () => {
     }
   });
 
-  it('accepts the version it was created for and rejects others with -32004', async () => {
+  it('accepts the version it was created for and rejects others with -32022', async () => {
     const srv = await createServerStateless(
       { 'tools/list': () => ({ tools: [] }) },
       DRAFT_PROTOCOL_VERSION
@@ -292,7 +292,7 @@ describe('createServerStateless', () => {
         { 'mcp-protocol-version': '2099-01-01' }
       );
       expect(rejected.status).toBe(400);
-      expect(rejected.body.error.code).toBe(-32004);
+      expect(rejected.body.error.code).toBe(-32022);
       expect(rejected.body.error.data.supported).toEqual([
         DRAFT_PROTOCOL_VERSION
       ]);

src/mock-server/stateless.ts

@@ -84,7 +84,7 @@ export type StatelessValidation =
  * `auth/helpers/createServer.ts`) uses the same validation as this module.
  *
  * `supportedVersions` is the list of wire protocolVersion strings this
- * endpoint accepts; anything else is rejected with -32004 carrying
+ * endpoint accepts; anything else is rejected with -32022 carrying
  * `{ supported, requested }` in the error data, and the list is echoed in
  * the `server/discover` result.
  */
@@ -108,7 +108,7 @@ export function validateStatelessRequest(
 
   const headerVersion = req.headers['mcp-protocol-version'];
   if (!headerVersion) {
-    return reject(400, -32001, 'Missing MCP-Protocol-Version header');
+    return reject(400, -32020, 'Missing MCP-Protocol-Version header');
   }
   const missing = META_KEYS.filter((k) => meta?.[k] === undefined);
   if (missing.length > 0) {
@@ -121,7 +121,7 @@ export function validateStatelessRequest(
   if (meta?.[META_KEYS[0]] !== headerVersion) {
     return reject(
       400,
-      -32001,
+      -32020,
       'MCP-Protocol-Version header does not match _meta.protocolVersion'
     );
   }
@@ -136,7 +136,7 @@ export function validateStatelessRequest(
         jsonrpc: '2.0',
         id,
         error: {
-          code: -32004,
+          code: -32022,
           message: 'Unsupported protocol version',
           data: {
             supported: supportedVersions,

src/scenarios/client/draft-result-fields.test.ts

@@ -238,7 +238,7 @@ describe('request-metadata mock results (2026-07-28)', () => {
     );
     const headers = { 'MCP-Protocol-Version': DRAFT_PROTOCOL_VERSION };
     try {
-      // The first request is always answered with the simulated -32004
+      // The first request is always answered with the simulated -32022
       // rejection (retry probe); results are served from the second on.
       const first = await post(
         serverUrl,

src/scenarios/client/request-metadata.test.ts

@@ -105,7 +105,7 @@ async function incompatibleVersionClient(serverUrl: string) {
 
   if (response.status === 400) {
     const body = await response.json();
-    if (body.error?.code === -32004) {
+    if (body.error?.code === -32022) {
       return body; // Abort cleanly
     }
   }

src/scenarios/client/request-metadata.ts

@@ -282,7 +282,7 @@ export class RequestMetadataScenario implements Scenario {
             id: request.id ?? null,
             error: {
               // UnsupportedProtocolVersionError per the draft schema.
-              code: -32004,
+              code: -32022,
               message: 'Unsupported protocol version',
               data: {
                 supported: [DRAFT_PROTOCOL_VERSION],

src/scenarios/index.ts

@@ -120,7 +120,7 @@ const pendingClientScenariosList: ClientScenario[] = [
 
   // HTTP Standardization (SEP-2243)
   // Pending until the everything-server fully implements SEP-2243
-  // header validation (case-insensitive names, whitespace trimming, -32001 error code)
+  // header validation (case-insensitive names, whitespace trimming, -32020 error code)
   new HttpHeaderValidationScenario(),
   new HttpCustomHeaderServerValidationScenario()
 ];

src/scenarios/server/http-standard-headers.ts

@@ -8,7 +8,7 @@
  * - Reject case variations of header values (case-sensitive)
  * - Handle whitespace trimming per HTTP spec
  * - Validate Base64-encoded custom header values
- * - Return 400 Bad Request with error code -32001 (HeaderMismatch)
+ * - Return 400 Bad Request with error code -32020 (HeaderMismatch)
  *
  * This is a ClientScenario (connects to a server under test and validates
  * its behavior).
@@ -66,8 +66,8 @@ const REJECT_STATUS_CHECK_ID = 'sep-2243-server-reject-invalid-headers';
 const REJECT_ERROR_CODE_CHECK_ID = 'sep-2243-server-reject-error-code';
 
 // CUSTOM-header (Mcp-Param-*) rejections map to the param-validation
-// requirements instead. The -32001 error-code half of every custom-header
-// rejection is the "reject with 400 + JSON-RPC error code -32001 if any
+// requirements instead. The -32020 error-code half of every custom-header
+// rejection is the "reject with 400 + JSON-RPC error code -32020 if any
 // validation fails" requirement.
 const PARAM_REJECT_ERROR_CODE_CHECK_ID =
   'sep-2243-server-reject-param-mismatch';
@@ -148,8 +148,8 @@ async function sendRawRequest(
 
 /**
  * Builds two checks for a rejection case: one for the HTTP 400 status, one for
- * the -32001 JSON-RPC error code. Per SEP-2243 §Server Validation, 400 is MUST
- * but -32001 is SHOULD for *standard* headers (and MUST for *custom* headers,
+ * the -32020 JSON-RPC error code. Per SEP-2243 §Server Validation, 400 is MUST
+ * but -32020 is SHOULD for *standard* headers (and MUST for *custom* headers,
  * §Server Behavior for Custom Headers) — so a server returning 400 with a
  * different error code is compliant for standard headers and must not FAIL.
  *
@@ -196,7 +196,7 @@ function createRejectionChecks(
     {
       id: errorCodeId,
       name: `${name}ErrorCode`,
-      description: `${description} — uses JSON-RPC error code -32001 (HeaderMismatch)`,
+      description: `${description} — uses JSON-RPC error code -32020 (HeaderMismatch)`,
       status: codeOk ? 'SUCCESS' : opts.errorCodeSeverity,
       timestamp: ts,
       errorMessage: codeOk
@@ -265,7 +265,7 @@ export class HttpHeaderValidationScenario implements ClientScenario {
 - Server MUST reject case-mismatched header values (method values are case-sensitive)
 - Server MUST accept extra whitespace around header values (per HTTP spec)
 - Server MUST return HTTP 400 Bad Request for validation failures
-- Server MUST return JSON-RPC error with code -32001 (HeaderMismatch)`;
+- Server MUST return JSON-RPC error with code -32020 (HeaderMismatch)`;
 
   async run(ctx: RunContext): Promise<ConformanceCheck[]> {
     const { serverUrl } = ctx;
@@ -507,7 +507,7 @@ export class HttpHeaderValidationScenario implements ClientScenario {
         ...extraHeaders
       });
       if (expectation === 'reject') {
-        // Standard-header rejection: 400 is MUST, -32001 is SHOULD. All
+        // Standard-header rejection: 400 is MUST, -32020 is SHOULD. All
         // standard-header rejection cases collapse onto the coarse requirement
         // ids; checkId/checkName still distinguish the case via name/details.
         checks.push(
@@ -926,10 +926,10 @@ export class HttpCustomHeaderServerValidationScenario implements ClientScenario
           )
         );
       } else {
-        // Custom-header rejection: both 400 and -32001 are MUST per
+        // Custom-header rejection: both 400 and -32020 are MUST per
         // §Server Behavior for Custom Headers. The status half maps to the
         // param-validation requirement this case exercises (checkId); the
-        // error-code half is the "400 + -32001 if any validation fails"
+        // error-code half is the "400 + -32020 if any validation fails"
         // requirement.
         checks.push(
           ...createRejectionChecks(
@@ -992,7 +992,7 @@ export class HttpCustomHeaderServerValidationScenario implements ClientScenario
         }
       );
 
-      // Custom-header rejection: both 400 and -32001 are MUST. A header
+      // Custom-header rejection: both 400 and -32020 are MUST. A header
       // omitted while the body carries a value is a header/body mismatch, so
       // the status half maps to the validate-param-match requirement.
       checks.push(

src/scenarios/server/stateless.test.ts

@@ -180,7 +180,7 @@ describe('Stateless Server Scenario Negative Tests', () => {
             jsonrpc: '2.0',
             id: reqBody.id,
             error: {
-              code: -32004,
+              code: -32022,
               message: 'Unsupported protocol version',
               // Spec Violation: data.requested is a required member
               data: { supported: ['2026-07-28'] }