fix(SEP-2663): specify -32003 error for missing client capability#2756
Conversation
kurtisvg
changed the title
LucaButBoring
changed the title
LucaButBoring
changed the title
|
Converted backwards-compatibility section into a matrix and moved the note about |
Co-authored-by: Peter Alexander <pja@anthropic.com>
There was a problem hiding this comment.
This looks good to me. Our current plan for the C# SDK is to not support the experimental 2025-11-25 task extension and the 2026-06-30 task version simultaneously in the same SDK package. The idea is that new versions of the SDK will continue to support the basic 2025-11-25 protocol for some time, but not the task part.
For SDKs/servers that want to attempt supporting both versions of the task extensions, making it clear that you should use protocol version negotiation to determine which task surface to expose makes sense.
|
|
||
| ## Backward Compatibility | ||
|
|
||
| The experimental tasks feature in the `2025-11-25` release is **not wire-compatible** with this extension. Specifically: |
There was a problem hiding this comment.
I would leave this section as I think it's a good call out of what's changed.
| Implementations that need to bridge legacy clients can shim at the SDK level: a server can implement both the experimental and extension surfaces in parallel, dispatching based on which capability and protocol version the client negotiated. | ||
| | Protocol Version | `tasks.*` (legacy) | `io.modelcontextprotocol/tasks` | | ||
| | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `2025-11-25` | Legacy experimental tasks per the `2025-11-25` specification. The client opts into task augmentation per request via the `task` parameter on `CallToolRequest`; the server uses `tasks/result`, `tasks/get`, `tasks/cancel`, and (where supported) `tasks/list` per that specification. This extension does not apply. | This extension is not defined under the `2025-11-25` protocol version. Servers **MUST NOT** treat this capability as enabling tasks under that protocol version; requests proceed as if the client had declared no task capability at all. | |
There was a problem hiding this comment.
This table is a little confusing, I was trying to get to something that would clearly state expected behavior and support for SDK maintainers something like..
| Client Supports | Server Supports | Negotiated Version | Expected Tasks Behavior |
|---|---|---|---|
| 2025-11-25 | 2025-11-25 | 2025-11-25 | Works, Experimental Tasks Feature as defined in 2025-11-25 |
| 2026-06-30 | 2026-06-30 | 2026-06-30 | Tasks Extension |
| Both | Both | 2026-06-30 | Highest common version wins. Full extension behavior. |
| Both | 2026-06-30 | 2026-06-30 | Tasks Extension |
| Both | 2025-11-25 | 2025-11-25 | Experimental Tasks Feature |
| 2026-06-30 | Both | 2026-06-30 | Tasks Extension |
| 2025-11-25 | 2026-06-30 | None | -32602 Unsupported protocol version |
| 2026-06-30 | 2025-11-25 | None | -32602 Unsupported protocol version |
Although after writing this out, it looks a lot more like protocol negotiation.
I think the thing we are missing is what is the expected error code if an 11-25-25 client or prior version includes the tasks extension when talking to servers that support old & new versions?
Should this be an unsupported protocol version error? Should the server just ignore it as a malformed request?
There was a problem hiding this comment.
For Servers that want to support both versions during the transition, there is an interesting question of what the Server/discover should look like.
I think they advertise both the extension and the capability, and then Clients which support both need to know that if they pick 11-25-25 they need to use capabilities and if they pick 06-30-26 they need to use the extension, and not mix them.
Although this is such an edge case that maybe we don't worry about it. I know C# SDK is just not going to support both. Not sure what Python, Typescript and Go the other Tier1 SDKs are doing
There was a problem hiding this comment.
server/discover only returns what is supported for the requested protocol version (or errors if that protocol is unsupported)
So for 2026-07-28 it returns the extension and for 2025-11-25 it returns the capability.
5 participants
Adds error-handling requirements to #2663 specify that
-32003is the correct error for servers to return when a server supports the Tasks extension and a client that does not declare the extension capability attempts to calltasks/get,tasks/update, ortasks/cancel- with an additional carveout for servers supporting both the extension and the2025-11-25version of tasks.The backwards-compatibility section has been converted into a matrix for readability.
Motivation and Context
Currently, the Tasks extension specification does not declare a specific error for servers to return if a client invokes a Task-related method without supporting the extension. It does declare that servers must return
-32003(Missing Required Client Capability) if they require a client to support receivingCreateTaskResult, but this does not imply any behavior regarding other task methods, liketasks/update.The current spec is ambiguous on this point, and both
-32601and-32003are reasonable errors to return in this scenario, but we will require-32003as it more accurately reflects the server's state.-32601would imply that it does not support Tasks at all, while-32003clarifies that the server does, but the client does not.How Has This Been Tested?
N/A
Breaking Changes
N/A
Types of changes
Checklist
Additional context
Identified in modelcontextprotocol/conformance#262 (comment)