wip: support tool retry on timeout via idempotencyKey param in CallToolRequestParams

[MarlzRana]

Motivation and Context

Issue:

• Tools can hint that they are idempotent via setting the idempotencyHint to true
• No standard way to provide an idempotency key to a tool that hints they are idempotent
• We want to be able to retry tool calls upon non-logical timeouts, like a timeout, with the same idempotency key

Solution:

• Introduce a new idempotencyKey attribute to the CallToolRequestParams DTO that is populated when calling a tool
• If the client wishes to, they can set max_timeout_retries to a value greater than 0, which triggers tool retry on timeout with the same idempotency key

How Has This Been Tested?

Unit tests and demo code (temporarily committed)

Breaking Changes

Not breaking, by default, retry is not enabled (hence not breaking existing behaviour)

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

WIP

Additional context

This is a rough implementation of what an idempotencyKey attribute could look like in the spec. This is not a PR ready to be merged, but just to demo what it could look like, to "add some color to the picture". This is part of an ongoing discussion in the #financial-services-wg to support idempotent tools.

• Original "scrap doc" on issue
• Example repo demonstrating problem
• Video summary of the above

[maxisbey]

Thanks for the PR. This adds idempotencyKey to CallToolRequestParams, which doesn't exist in the MCP spec schema — the SDK can't ship protocol fields ahead of the spec.

Idempotency keys were deferred to a future SEP during SEP-1686 and assigned to the Transports WG (Nov 18 meeting notes). That SEP hasn't been filed yet.

If you'd like to push this forward, the right place to start is a SEP in the spec repo. Happy to revisit here once there's a schema change to implement.

If there's a SEP or discussion I've missed that covers this, feel free to link it and reopen.

_{AI Disclaimer}