Custom MCP requests + hooks

[cmrfrd]

Allow users to opt-in to defining custom message types for MCP and server/client side hooks for how to process them.

Motivation and Context

This change allows users to define their own opt-in sub-protocols extending MCP to fit their needs outside the specification. With custom messages, users don't need to fork the MCP sdk's in order to extend the protocol.

Our specific use case for is so we can define sub-protocols for sensitive data transfer (ex: payment information, PII, credentials, etc.) but there are other users that may want to implement their own systems.

How Has This Been Tested?

See examples/custom_requests or updated readme.

Breaking Changes

This feature is opt-in via experimental_capabilities and won't break existing code / configs.

Types of changes

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

Checklist

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

Additional context

This PR only applies to the python sdk, so in order to provide this to MCP as a whole, we would need similar PR's for the other MCP sdk's. Consider this implementation a POC, and we can replicate this approach across the other sdks's.

[jerome3o-anthropic]

Hey @cmrfrd, love the work here - I think extending the spec is going to be super valuable, and we should make it easy to do in the sdks. However - with the current implementation here it looks like all custom requests will have the jsonrpc method custom/request. Ideally they would be able to have their own method defined at that root level, as opposed to in the params.

For example, in the listed version over the wire we get:

{
    "method": "custom/request",
    "params": {
        "meta": null,
        "inner": {
            "method": "ttl",
            "params": {
                "ttl": 7
            }
        }
    },
    "jsonrpc": "2.0",
    "id": 0
}

But ideally we'd have:

{
     "method": "ttl",
     "params": {
          "ttl": 7
     }
    "jsonrpc": "2.0",
    "id": 0
}

I think we'd need some significant work on this sdk to make this easy to do :/

[merlinarer]

hello, any progress here? This feature is really important.

[dsp-ant]

I still think this is an important feature, but we should implement this with the ability to specify custom request method names and not go only via custom/request