Fix and enhance cancellation operations across MCP Sessions.

[Tyler-R-Kendrick]

• made requests notify cancellation when cancellation tokens are used.
• added extension methods to make sending these custom cancellation notifications simpler.

Motivation and Context

This helps adherence to the spec, specifically for requests - since notifications aren't cancellable according to the spec.

How Has This Been Tested?

Tests were added to cover the usage.

Breaking Changes

NA

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

NA

[halter73]

Can we move this into MpcSession? That's currently handling the lifetime of the TCS, so it seems natural for it to handle the token registration as well.

I know NotifyCancelAsync requires IMcpEndpoint, but we could easily make MpcSession implement that by simply adding AddNotificationHandler(...) => _notificationHandlers.Add(method, handler);

Or better yet, we rename IMcpEndpoint to IMcpSesssion, and remove AddNotificationHandler from the interface. I don't think anything currently targeting IMcpEndpoint (i.e NotifyProgressAsync) actually uses AddNotificationHandler, and I don't see how AddNotificationHandler ties together with SendRequestAsync/SendRequestAsync on the same interface. There's certainly one method that's not like the other, and it's generally a good idea to keep interfaces segregated if you can.

@PederHP @stephentoub @eiriktsarpalis do you agree that AddNotificationHandler doesn't belong on IMcpEndpoint?

[stephentoub]

do you agree that AddNotificationHandler doesn't belong on IMcpEndpoint?

As I mentioned at #142 (comment), I don't think it belongs on any of the interfaces. I don't see a good reason for why notification handlers should be provided post-construction of the client/server; just like request handlers, they should be provided into the factory / constructor. (And separate from the lack of symmetry, there's currently a concurrency bug if the implementation receives a notification concurrently with a handler being added for it... that goes away by design if it's not possible for a handler to be added post construction.)

[Tyler-R-Kendrick]

I generally agree. I was looking at consolidating the IMcpEndpoint with a newly introduced IMcpSession that is public (since McpSession is internal). I like the idea here.

[PederHP]

do you agree that AddNotificationHandler doesn't belong on IMcpEndpoint?

As I mentioned at #142 (comment), I don't think it belongs on any of the interfaces. I don't see a good reason for why notification handlers should be provided post-construction of the client/server; just like request handlers, they should be provided into the factory / constructor. (And separate from the lack of symmetry, there's currently a concurrency bug if the implementation receives a notification concurrently with a handler being added for it... that goes away by design if it's not possible for a handler to be added post construction.)

The standard is open-ended so it should be allowed for client and server authors to handle arbitrary notifications. This is especially useful when developing both the client(s) and the server(s). I believe the other SDKs also allow this, but I'll verify this.

I can see the point about post-construction registration not being valid. Not having that can easily be worked around anyway, if one has a weird use case that needs run-time changing of handlers by just adding an extra layer.

Edit: TypeScript SDK allows custom notifications. Python SDK seems allows it, but it's not quite as easily configured (requires inheritance from what I can see). The same for custom requests.

[stephentoub]

The title and description of this PR are wrong, right?

[halter73]

Given that the recommended way to send a cancellation notification will probably be to trip the CancellationToken you pass to SendRequestAsync, does it eve make sense to add this as an extension method to IMcpEndpoint (or IMcpSession)?

That would make this API very visible to anyone with an IMcpClient or IMcpServer, but I don't think it's that usefu. Also, given the simplicity of the implementation now that we have NotifyAsync, I think we should just remove NotifyCancelAsync from the public API.

[Tyler-R-Kendrick]

I generally agree that it isn't very useful and is just exposing it for the sake of adherence to the spec.
The rare use-case I could see would be to either submit your own cancellation reason, or to submit a cancellation for a non-terminal failure condition (like a 200 response, but a data state that is considered invalid) without throwing a normal exception.

[stephentoub]

just exposing it for the sake of adherence to the spec

Nothing in the specification dictates how it shows up in the .NET APIs. The APIs already support it via SendNotificationAsync. Anything higher-level we do is about ease of use.

[Tyler-R-Kendrick]

Would you rather I inline this into McpSession? Or just mark it as internal?

[halter73]

I'd just inline it for now. Having a subset of extension methods be internal can be a little confusing.

[PederHP]

Did you remove the low level arbitrary notification handler registration option? If so I don't think that's a good idea. It's not something many will use but it should be possible, as MCP is an open standard and being to create servers and clients with arbitrary notifications should be possible. I also think it's important that the option to forego abstractions built on top of the protocol is always present.

I might have misunderstood your last commit. In that case, disregard this.

[Tyler-R-Kendrick]

Did you remove the low level arbitrary notification handler registration option? If so I don't think that's a good idea. It's not something many will use but it should be possible, as MCP is an open standard and being to create servers and clients with arbitrary notifications should be possible. I also think it's important that the option to forego abstractions built on top of the protocol is always present.

I might have misunderstood your last commit. In that case, disregard this.

I just moved it to construction-time instead of runtime registration of arbitrary handlers. This avoids a race condition Stephen mentioned above..

[PederHP]

Did you remove the low level arbitrary notification handler registration option? If so I don't think that's a good idea. It's not something many will use but it should be possible, as MCP is an open standard and being to create servers and clients with arbitrary notifications should be possible. I also think it's important that the option to forego abstractions built on top of the protocol is always present.
I might have misunderstood your last commit. In that case, disregard this.

I just moved it to construction-time instead of runtime registration of arbitrary handlers. This avoids a race condition Stephen mentioned above..

So how would a server author register an arbitrary (ie custom notification) handler after this change?

Also if this means removing the option to register arbitrary handlers at run-time that is a loss of low-level functionality, which I think is a shame - but on the other hand it's such a niche use-case that it's hard to justify keeping it if removing it avoids a race condition.

[stephentoub]

Also if this means removing the option to register arbitrary handlers at run-time that is a loss of low-level functionality, which I think is a shame

What is the use case where, after you already have an established connection, you want to add a handler that you can then never remove? And why is that relevant to notifications but not to requests?

It's also not a loss of functionality. If you really want to do that, you can register a handler that then consults whatever list it wants, and that list can be modified whenever to your heart's content :)

[PederHP]

Also if this means removing the option to register arbitrary handlers at run-time that is a loss of low-level functionality, which I think is a shame

What is the use case where, after you already have an established connection, you want to add a handler that you can then never remove? And why is that relevant to notifications but not to requests?

It's also not a loss of functionality. If you really want to do that, you can register a handler that then consults whatever list it wants, and that list can be modified whenever to your heart's content :)

Yeah, as I wrote above in the other comment it's weird and it's easy to work around (if one had a hypothetical need to use it). And I agree that the same would go for requests. Probably shouldn't have mentioned it.

But the custom notification handler registration is important, I think, but maybe I misunderstood about that. It looks to have been removed from what I can see (the helper class is internal)?

Maybe I should clarify that I'm talking about custom handlers for user-defined method notifications, not custom handlers for the "built-in" notifications.

[stephentoub]

I'd told Tyler I would be doing the work to add handlers at construction time today. I think he was just prototyping it here.

[Tyler-R-Kendrick]

Also if this means removing the option to register arbitrary handlers at run-time that is a loss of low-level functionality, which I think is a shame

What is the use case where, after you already have an established connection, you want to add a handler that you can then never remove? And why is that relevant to notifications but not to requests?
It's also not a loss of functionality. If you really want to do that, you can register a handler that then consults whatever list it wants, and that list can be modified whenever to your heart's content :)

Yeah, as I wrote above in the other comment it's weird and it's easy to work around (if one had a hypothetical need to use it). And I agree that the same would go for requests. Probably shouldn't have mentioned it.

But the custom notification handler registration is important, I think, but maybe I misunderstood about that. It looks to have been removed from what I can see (the helper class is internal)?

Maybe I should clarify that I'm talking about custom handlers for user-defined method notifications, not custom handlers for the "built-in" notifications.

I was POC-ing for Stephen so he could have a jumping off point.
Custom registration still exists because the of the dictionaries I introduced to the options. If you want a custom message handler as a server author, you would just do something like:

new McpServerOptions()
{
    RequestHandlers = {
        ["customRequest"] = [CustomRequestHandler, ...otherCustomRequestHandlers],
    },
    NotificationHandlers = {
        ["customNotification"] = [CustomNotificationHandler, ...otherCustomNotificationHandlers],
    },
}

You would either do this in your DI configuration, or wherever you construct an MCP server. Same goes for an MCP client for handlers to things like sampling.

[Tyler-R-Kendrick]

I'd told Tyler I would be doing the work to add handlers at construction time today. I think he was just prototyping it here.

I'll likely roll back the last 3 commits when you're finished. Don't worry about trying to merge in my attempt to your work if it makes it more difficult for you :)

[stephentoub]

@Tyler-R-Kendrick, now that the handler registration has been fixed up, can you rebase this on main? Thanks.