fix(server-stateless): requiredCapabilities is a ClientCapabilities object, not an array

[felixweinberger]

sep-2575-server-rejects-undeclared-capability requires error.data.requiredCapabilities to be an array containing 'sampling'. The schema defines it as a ClientCapabilities object, so a spec-correct server cannot pass the check.

Motivation and Context

Spec — schema/draft/schema.ts#L482 (rendered):

export interface MissingRequiredClientCapabilityError extends Omit<JSONRPCErrorResponse, "error"> {
  error: Error & {
    code: typeof MISSING_REQUIRED_CLIENT_CAPABILITY;
    data: {
      requiredCapabilities: ClientCapabilities;
    };
  };
}

and the spec's own example, missing-elicitation-capability.json:

"data": { "requiredCapabilities": { "elicitation": {} } }

Both have carried the object shape since the commit that introduced SEP-2575 (8e192a22, May 11) — it was never an array at any point. The array assertion arrived a week later in the initial scenario scaffold (#271, May 19) without a spec citation, plausibly from the prose "whose data.requiredCapabilities lists the missing capabilities" (basic/index), which reads array-ish in isolation; the schema and example are unambiguous.

This repo already uses the object everywhere else — src/spec-types/draft.ts#L499 types it as ClientCapabilities, and tasks/required-task-error.ts#L192 asserts data.requiredCapabilities.extensions[...] as an object. The array assertion went unnoticed because it is only reachable once a server actually returns -32021, and that positive branch had no self-test.

Before / after, against a real server (typescript-sdk's conformance everythingServer) answering the probe with the spec shape:

HTTP/1.1 400 Bad Request
{"jsonrpc":"2.0","id":401,"error":{"code":-32021,
  "message":"Cannot request input 'llm_answer' (sampling/createMessage): the request's client capabilities do not declare the required capability",
  "data":{"requiredCapabilities":{"sampling":{}}}}}

before (0.2.0-alpha.8):

[sep-2575-server-rejects-undeclared-capability] FAILURE
  Server responded with error code -32021 but failed to provide an array containing
  the expected 'sampling' capability in error.data.requiredCapabilities

after (this branch, same server):

[sep-2575-server-rejects-undeclared-capability] SUCCESS
Passed: 30/30, 0 failed, 0 warnings

How Has This Been Tested?

• npx vitest run src/scenarios/server/stateless.test.ts — 18/18, including three new self-tests: object passes, array fails, { "sampling": null } fails (capability values must themselves be objects).
• From-source run of server-stateless against typescript-sdk's everythingServer (with its test_missing_capability fixture armed): 30/30 — the same server the shipped alpha.8 fails, as captured above.

Breaking Changes

For servers, no — the object shape is what the schema has always required. For fixture servers written against the old assertion: python-sdk's reference everything-server emits the array (and pins it in two tests), and server-stateless is in neither of its baselines, so its conformance CI will flag this scenario on its next referee bump. The fix there is the same one-line shape change — happy to send it.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

• The scenario's implementer-facing description now states the required shape, so the next fixture author doesn't have to discover it from the runtime error string.
• A one-word prose clarification upstream ("lists" → "names", or matching the schema's phrasing) would prevent a recurrence.

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@modelcontextprotocol/conformance@376

commit: 9ff797c