ClientCapabilities.experimental fails to decode object-valued capabilities

[djwhelan]

Description

Swift MCP SDK 0.12.1 models the experimental client capabilities field as:

public var experimental: [String: String]?

This causes MCP initialization to fail when a client sends an object-valued experimental capability.

For example, current OpenAI Codex sends:

"experimental": {
  "codex/auth-change": {}
}

The {} value cannot be decoded as a String, so decoding of the initialize parameters fails and the server returns:

-32603 Internal error:
The data couldn’t be read because it isn’t in the correct format.

The MCP specification defines ClientCapabilities.experimental as a map of capability names to objects, rather than strings.

Minimal reproduction

Using the same unchanged Swift MCP server:

Fails

"experimental": {
  "codex/auth-change": {}
}

Result:

-32603 Internal error:
The data couldn’t be read because it isn’t in the correct format.

Succeeds

"experimental": {}

Initialization succeeds and the server advertises its tool capability.

An unrelated object-valued experimental capability produces the same failure, so this is not specific to codex/auth-change.

Expected behavior

ClientCapabilities.experimental should accept arbitrary MCP capability objects, including an empty object:

"experimental": {
  "example/capability": {}
}

Unknown experimental capabilities should not prevent initialization.

A possible Swift representation might use the SDK's arbitrary JSON value/object type rather than String, for example conceptually:

[String: JSONValue]?

or the appropriate existing SDK-native equivalent.

Regression test

A regression test should decode an initialize request containing:

"experimental": {
  "example/capability": {}
}

and verify that initialization succeeds.

It would also be useful to preserve compatibility with any previously accepted experimental values where appropriate.

Environment

• Swift MCP SDK: 0.12.1
• Swift MCP SDK HEAD tested: a0ae212ebf6eab5f754c3129608bc5557637e605
• OpenAI Codex CLI: 0.154.0-alpha.6.2
• macOS: 27.0 (26A428)
• Downstream server used for my reproduction: eneko-codes/apple-reminders-mcp
• Downstream server commit: aa5730b3cea147343528eb9f55bfd6dcaa9e3712

The problem appears SDK-level rather than specific to that downstream server.

Related issue

OpenAI Codex issue #44458 independently reproduces the same failure with other Swift-based MCP helpers:

openai/codex#44458

That report shows the same A/B result:

• object-valued experimental capability → initialization failure
• empty experimental object / omitted field → successful initialization

[ASTion24]

Hi @djwhelan, I reproduced this on current main. Client.Capabilities.experimental is [String: String]?, so object-valued capabilities fail while decoding Request<Initialize>.

I can submit a focused fix using the SDK's existing [String: Value]? representation, with a regression test covering empty object values while preserving previously accepted string values. May I work on this?