Establish the supported MCP client and protocol compatibility policy

[aidanbruneel]

Question to answer

Which MCP protocol revisions, transports, authorization flows, tool/result features, file-transfer mechanisms, resources, and MCP Apps behaviours must the IMAGE MCP service support for the selected ChatGPT, Claude, and SDK/Inspector clients at initial release, and what isolated legacy strategy satisfies that matrix without making the core contract depend on one host's undocumented behaviour?

Decision or next step this enables

Select the production SDK/package versions, endpoint negotiation strategy, compatibility-adapter boundary, CI matrix, deprecation window, and minimum portable result behaviour for the gateway.

Current understanding and key unknowns

Confirmed:

• The prototype initially implemented the MCP 2026-07-28 SDK v2 and then reverted to @modelcontextprotocol/sdk v1.30 with protocol 2025-06-18 after observed ChatGPT incompatibilities.
• MCP 2026-07-28 is stateless and uses per-request metadata and required routing headers; the TypeScript SDK v2 supports it and a 2025-11-25 compatibility era.
• Host support for MCP Apps and binary/file transfer varies.
• Anthropic documents Streamable HTTP and OAuth support but does not claim support for every advanced capability.

Unknown:

• The exact revisions and Apps behaviours currently emitted by each release-target client.
• Whether one supported SDK can cover the matrix or a separate legacy process/package is required.
• How long legacy support must remain and how unsupported clients fail visibly.

Proposed approach

1. Name exact clients/plans/builds and representative agent SDKs in scope.
2. Create a minimal neutral test server exposing discovery, one tool, structured output, one resource, OAuth challenge, cancellation, and an App.
3. Capture sanitized wire behaviour and test each client. Do not infer support from marketing pages.
4. Evaluate official SDK v2 dual-era support and, if necessary, a separately packaged legacy adapter. Do not install conflicting SDK generations in one package without proof.
5. Define a portable baseline: text content, structured manifest, and artifact fallback that works without an App.
6. Publish a decision record with supported/rejected/degraded combinations and a protocol deprecation policy.

Completion criteria

• A dated client/protocol/capability matrix records exact tested versions and evidence.
• The production SDK and protocol strategy is recommended with dependency/security implications.
• Any legacy adapter has an explicit isolation boundary, owner, removal condition, and tests.
• Portable fallback behaviour and unsupported-client errors are defined.

Evidence and related work

• Prototype compatibility change: fd2f7e0
• MCP 2026 transport: https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
• TypeScript SDK reference server: https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/todos-server
• Official OpenAI MCP server guidance: https://developers.openai.com/plugins/build/mcp-server
• Official OpenAI plugin/MCP reference, including file inputs and UI metadata: https://developers.openai.com/plugins/reference

Checks

• I kept this Investigation focused on one bounded question with a clear stopping condition.
• I will track resulting production implementation as separate Bugs, Features, or Tasks.
• I removed secrets, credentials, personal information, and confidential data.