docs: add tool visibility and restructure _meta.ui #131
+67
−11
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
- Restructure tool metadata: `_meta["ui/resourceUri"]` → `_meta.ui.resourceUri` - Add `visibility` array field: ["model"], ["apps"], or ["model", "apps"] - Default ["model"] preserves standard MCP behavior - ["apps"] enables widget-only tools hidden from agent - Add McpUiToolMeta interface for type safety - Add Design Decision #4 explaining approach vs OpenAI's two-field model 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
commit: |
ochafik
requested changes
Dec 11, 2025
| Tools are associated with UI resources through the `_meta.ui` field: | ||
|
|
||
| ```typescript | ||
| interface McpUiToolMeta { |
Collaborator
There was a problem hiding this comment.
could you add to spec.types.ts too?
| inputSchema: object; | ||
| _meta?: { | ||
| // Required: URI of the UI resource to use for rendering | ||
| "ui/resourceUri"?: string; |
Collaborator
There was a problem hiding this comment.
Can we keep this for now (don't need to break everyone) but deprecate it?
| - `visibility` defaults to `["model"]` if omitted (standard MCP behavior) | ||
| - `"model"`: Tool is visible to and callable by the agent | ||
| - `"apps"`: Tool is callable by apps from the same server connection only | ||
| - Host MUST NOT include tools with `visibility: ["apps"]` in the agent's tool list |
Collaborator
There was a problem hiding this comment.
Suggested change
| - Host MUST NOT include tools with `visibility: ["apps"]` in the agent's tool list | |
| - Host MUST NOT include tools in the agent's tool list when their visibility does not include `"model"` (e.g. `visibility: ["apps"]`) |
ochafik
reviewed
Dec 11, 2025
Collaborator
There was a problem hiding this comment.
Should also add a blurb about tools/list and tools/call, to say the former will skip tools that don't have "apps", and the latter will error when attempting to call such a tool anyway.
idosal
reviewed
Dec 11, 2025
| inputSchema: { /* ... */ }, | ||
| _meta: { | ||
| "ui/resourceUri": "ui://weather-server/dashboard" | ||
| ui: { resourceUri: "ui://weather-server/dashboard" } |
Collaborator
There was a problem hiding this comment.
This is a breaking change. Let's deprecate it and give consumers some time to adapt. We should remove it before GA.
idosal
reviewed
Dec 11, 2025
| /** URI of UI resource for rendering tool results */ | ||
| resourceUri?: string; | ||
| /** | ||
| * Who can access this tool. Default: ["model"] |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Who can access this tool. Default: ["model"] | |
| * Who can access this tool. Default: ["model", "app"] |
Collaborator
Author
|
thanks folks, will address all the comments! |
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
Adds tool visibility control and restructures tool metadata for cleaner API.
Changes
1. Restructured
_metaformat:2. Added
visibilityarray:["model"]["apps"]["model", "apps"]3. Key behaviors:
["apps"]scope is per-server (cross-server calls blocked)tools/callfor tools without"apps"visibilityWhy single
visibilityvs OpenAI's two fields?OpenAI uses
widgetAccessible+visibilityseparately. We use one array because:Discussion points for meeting
["model"]the right default? (preserves standard MCP behavior)🤖 Generated with Claude Code