## 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, MCP Server Tool Bridge needs to preserve this metadata when creating the corresponding MCP tool definitions. Execution results can also carry presentation metadata separately from their typed outputs. A media picker, for example, can return Media IDs as structured outputs and provide image previews through result metadata. The goal is for contrib and custom modules to use the existing Tool API → MCP Server Tool Bridge flow for MCP Apps, without maintaining their own MCP registration or result-conversion 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. The module provides native Tool API plugins. Its opening tool declares a UI resource in definition metadata, and its results carry image previews separately from typed outputs. MCP Server serves the HTML through a native ResourceProvider. ## Current limitations Investigating MCP Server Tool Bridge **1.0.0-beta3** identified these gaps: * The tool-config deriver does not forward Tool API definition metadata into the generated MCP tool definition. * Successful execution-result conversion does not forward presentation metadata into `CallToolResult`. The bridge already handles input/output schemas, tool execution, access checks, formatted outputs, and textual results. The proposed work extends that flow rather than introducing a separate integration. This depends on the related Tool API and MCP Server contributions adding the metadata contracts described below. ## 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. ### Forward tool-definition metadata When `McpToolConfigDeriver` creates an MCP tool derivative, pass the Tool API definition’s metadata into the MCP Server definition. For example, Tool API metadata: `[ 'ui' => [ 'resourceUri' => 'ui://example/media-picker', ], ]` Should produce the following metadata on the corresponding `tools/list` entry: `{ "_meta": { "ui": { "resourceUri": "ui://example/media-picker" } } }` Forward generic metadata without limiting it to the `ui` key. Interpretation of MCP Apps metadata belongs to the SDK and supporting host. Tools without metadata should retain their existing behavior. ### Forward execution-result metadata When converting a successful formatted Tool API result into `CallToolResult`, forward its metadata into the SDK result’s `meta` argument, which serializes as `_meta`. Preserve the existing separation: * Formatted output context values become `structuredContent` and the existing JSON text fallback. * Messages and formatting hints remain textual content. * Result metadata becomes `_meta`, without being merged into structured outputs or their text fallback. The proof of concept forwards metadata on successful results. Whether failed results should also retain metadata should be decided explicitly; the current patch does not implement that path. ## Relationship to the other contributions This is the MCP Server Tool Bridge 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** | Generic tool-definition and execution-result metadata, separate from typed outputs | https://git.drupalcode.org/project/tool/-/work_items/3583087 | | **MCP Server Tool Bridge — this issue** | 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 metadata forwarding through the existing bridge. SDK extension registration and resource handling belong to MCP Server. The generic metadata contract belongs to Tool API. App rendering and iframe isolation remain the host’s responsibility. ## 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.