feat(mcp): preserve MCP tool annotations including readOnlyHint #10463
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Preserve all MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) when converting MCP tools to AI SDK tools. Previously, only the title annotation was extracted and preserved. Now the full annotations object is passed through to enable clients to make informed decisions about tool behavior based on these hints. Changes: - Add annotations field to Tool type definition - Update dynamicTool function to accept annotations parameter - Pass annotations from MCP listTools response to tool creation These annotations are informational hints per the MCP spec and should not be used for security-critical decisions.
dvoytenko
approved these changes
Nov 22, 2025
Collaborator
|
a) I am not sure how much we should tie MCP to our more abstract tools. This PR bleeds the MCP spec into our tool spec For your use case, is If that is potential path, then tools could have a |
Collaborator
|
Agree with @lgrammel and feel strongly that this would be best implemented in some kind of generic tool metadata. This might require some further thinking though |
Author
|
closing as this needs more thinking |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Preserve all MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) when converting MCP tools to AI SDK tools.
Changes
Previously, only the
titleannotation was extracted and preserved from MCP servers. This PR adds support for passing through all five annotation fields defined in the MCP specification (2025-03-26):title- Human-readable tool titlereadOnlyHint- Tool doesn't modify its environmentdestructiveHint- Tool may perform destructive updatesidempotentHint- Repeated calls with same args have no additional effectopenWorldHint- Tool interacts with external entitiesImplementation
annotationsfield toTooltype definition in@ai-sdk/provider-utilsdynamicTool()function signature to accept annotations parameterlistToolsresponse to tool creation in MCP clientUse Cases
These annotations enable clients to:
Security Note
Per the MCP specification, these annotations are informational hints only and should not be used for security-critical decisions. The documentation explicitly states this caveat.
Testing
Related
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]