## Problem and motivation [MCP Apps](https://apps.extensions.modelcontextprotocol.io/api/) allow an MCP server to provide an interactive HTML interface that a supporting host renders inside the conversation. A tool declares a UI resource through `_meta.ui.resourceUri`, and the host retrieves that resource through `resources/read`. For tools authored through Tool API, this requires metadata to travel from the tool definition through MCP Server Tool Bridge into the MCP tool definition. Execution results can also contain presentation metadata alongside their normal outputs. For example, an interactive media picker may need image previews while returning Media IDs and other structured values as its typed outputs. The goal is to support this through a **generic metadata API**, keeping MCP-specific interpretation in the bridge. The official PHP MCP SDK already provides the `McpApps` extension and associated metadata classes. The proposed work connects those capabilities to Drupal’s native registration flow. See: https://php.sdk.modelcontextprotocol.io/advanced/extensions/#mcp-apps-iomodelcontextprotocolui ## Proof of concept A [demo module](https://github.com/ronaldtebrake/drupal_mcp_apps) built on Agent Access demonstrates a Drupal Media picker rendered inside an MCP Apps host showcasing what that could look like. (Full write-up in a blog post [here](https://www.ronaldtebrake.nl/blog/mcp-apps-drupal-tool-api/)) Its tools are native Tool API plugins. Definition metadata links the opening tool to its UI resource, and result metadata carries image previews separately from the tool’s typed outputs. ## Current limitations Investigating Tool API **1.0.0-beta8** identified these gaps: * The Tool attribute and ToolDefinition do not provide a dedicated generic metadata API. * Execution results do not provide metadata separately from output context values. * Formatted results do not expose a metadata channel that a transport integration can forward. Putting presentation metadata into ordinary outputs changes the tool’s output contract and requires consumers to distinguish business data from presentation data themselves. ## Proposed resolution Based on the above demo, this is the steps I took to get it done, all open for consideration but thought it might be a good starting point. ### Support definition metadata Add an optional `meta` array to the Tool attribute, defaulting to an empty array. For example, a module could declare: `meta: [ 'ui' => [ 'resourceUri' => 'ui://example/media-picker', ], ],` Expose this through ToolDefinition: \`public function getMeta(): array; public function setMeta(array $meta): static;\` Metadata declared on the attribute should survive conversion into the tool definition. Setting an empty array should clear it. Tool API would carry the metadata without interpreting its keys. MCP Server Tool Bridge would map the example above to MCP’s `_meta.ui.resourceUri`. ### Support execution-result metadata Allow `ExecutableResult` to carry optional metadata independently of its output context values. For example: `return ExecutableResult::success( new TranslatableMarkup('Found accessible images.'), ['media_ids' => [42, 43]], meta: [ 'example/media-picker' => [ 'thumbnails' => $thumbnails, ], ], );` The proposed contract exposes this through `getMeta(): array`. Existing constructor and factory calls would continue working because the new metadata argument is optional. The proof of concept adds `getMeta()` to `ToolResultInterface`. This requires a compatibility decision: third-party implementations of that interface would need to implement the new method. An optional companion interface could be considered if preserving those implementations is required. ### Preserve metadata through result formatting `FormattedExecutableResult` should expose the original result’s metadata while continuing to format its normal output context values. Metadata should remain separate from input/output definitions, context values, and their schemas. Tests should cover default empty metadata, explicit metadata, attribute-to-definition propagation, and preservation through formatted results. Transport integrations remain responsible for deciding how to expose metadata. Tool API itself would not guarantee that metadata is hidden from models or confidential. ## Relationship to the other contributions This is the Tool API part of three coordinated changes: | Project | Responsibility | Related issue | |---------|----------------|---------------| | **MCP Server** | SDK extension registration and native tool/resource metadata preservation | https://git.drupalcode.org/project/mcp_server/-/work_items/3585942 | | **Tool API — this issue** | Generic tool-definition and execution-result metadata, separate from typed outputs | https://git.drupalcode.org/project/tool/-/work_items/3583087 | | **MCP Server Tool Bridge** | Forward Tool API definition and result metadata into MCP definitions and results | https://git.drupalcode.org/project/mcp_server_tool_bridge/-/work_items/3618733 | Together, they would support this flow. ## Scope This issue covers the generic metadata contract in Tool API. MCP field mapping, extension registration, UI resources, and app rendering belong to the bridge, server, and host respectively. It does not change tool permissions or access checks. ## AI Disclosure **AI-Generated: Yes.** OpenAI Codex was used to investigate the implementation, draft this issue, and generate portions of the proof-of-concept patches and tests.