@ttoss/http-server-mcp 0.27.1 → 0.28.0

package/README.md

@@ -478,6 +478,78 @@ register({
 
 **`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool. It receives the full `ToolCallContext` so context can vary by identity or by call args.
 
+## MCP Apps (interactive UIs)
+
+The [`io.modelcontextprotocol/ui`](https://github.com/modelcontextprotocol/ext-apps) extension lets a tool result render as an interactive view instead of text. The view is a `ui://` resource holding an HTML document, which the host loads into a sandboxed iframe and talks to over `postMessage`; the tool points at it through its `_meta`.
+
+The extension asks nothing of the transport, so `createMcpRouter` serves it as-is on both protocol revisions. `registerAppResource` owns the parts that are easy to get wrong — the `ui://` scheme, the exact MIME type, `_meta.ui` on both the declaration and the read result, and the deprecated flat linkage key that is still legal until the extension reaches GA.
+
+```typescript
+import {
+  McpServer,
+  registerAppResource,
+  UI_EXTENSION_ID,
+  UI_RESOURCE_MIME_TYPE,
+  z,
+} from '@ttoss/http-server-mcp';
+
+const server = new McpServer(
+  { name: 'weather', version: '1.0.0' },
+  {
+    capabilities: {
+      extensions: { [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] } },
+    },
+  }
+);
+
+const dashboard = registerAppResource({
+  server,
+  name: 'weather_dashboard',
+  uri: 'ui://weather/dashboard',
+  description: 'Interactive weather dashboard',
+  html: dashboardHtml, // a string, or ({ uri }) => string built per read
+  ui: {
+    csp: { connectDomains: ['https://api.openweathermap.org'] },
+    prefersBorder: true,
+  },
+});
+
+server.registerTool(
+  'get-weather',
+  {
+    description: 'Get the weather for a location',
+    inputSchema: { location: z.string() },
+    _meta: dashboard.toolMeta(),
+  },
+  async ({ location }) => {
+    const forecast = await fetchForecast(location);
+    return {
+      // Text stays meaningful: it is what a host without Apps renders.
+      content: [{ type: 'text', text: summarise(forecast) }],
+      structuredContent: forecast,
+    };
+  }
+);
+```
+
+`toolMeta()` is the linkage for **every** registration path — `registerTool`, [`registerToolFromSchema`](#registertoolfromschemaserver-params), and a [`GatedToolDef`](#creategatedtoolregistraroptions) all take `_meta`:
+
+```typescript
+registerToolFromSchema(server, {
+  name: 'refresh-dashboard',
+  description: 'Refresh dashboard data',
+  // Callable by the view, hidden from the model.
+  _meta: dashboard.toolMeta({ visibility: ['app'] }),
+  handler: async () => ({ content: [{ type: 'text', text: 'refreshed' }] }),
+});
+```
+
+### Register the linkage unconditionally
+
+The spec suggests checking the client's declared capability before registering UI-enabled tools. Do not: that read is only reliable on the `2026-07-28` revision, where the capability arrives in each request's envelope. In this package's default [stateless mode](#stateless-vs-stateful-mode) there is no remembered `initialize` for a 2025-era client, so a capability-gated registration silently drops the view for every one of them.
+
+Declaring it always is also strictly more compatible — a host without Apps support ignores `_meta` and renders the tool's `content`, which is the extension's own graceful-degradation contract. Keep every tool's text result meaningful on its own and the fallback takes care of itself.
+
 ## Issuing tokens for MCP clients
 
 The `auth` option above covers the **resource-server** half of MCP authorization — it verifies tokens issued by an external authorization server (Cognito, Auth0, …). To make your own first-party server _issue_ the tokens an MCP client runs the full OAuth flow against, add the [`@ttoss/http-server-auth`](https://ttoss.dev/docs/modules/packages/http-server-auth) plugin's `oauthServer()` and pair it with `createMcpRouter({ auth: { verifyToken } })` so one deployment both issues and verifies tokens. See the [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) guideline.
@@ -582,6 +654,7 @@ The `GatedToolDef` passed to `register` has:
 - `requiredScope` — Single scope that must appear in `identity.scopes`.
 - `inputSchema` — Zod field map or `ZodObject`, forwarded to `server.registerTool`.
 - `gates` (`Array<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Per-tool guards appended after the global `gates`. Receive the full `ToolCallContext` enabling arg-conditional authorization.
+- `_meta` (`Record<string, unknown>`, optional) — Tool metadata forwarded verbatim on `tools/list`; how a gated tool links to an [MCP Apps](#mcp-apps-interactive-uis) view.
 - `method` — Async handler. Receives merged call args + `buildContext` output.
 
 **`ToolCallContext`** is the object passed to gates, `buildContext`, and `onError`:
@@ -590,6 +663,33 @@ The `GatedToolDef` passed to `register` has:
 - `args` (`Record<string, unknown>`) — The validated tool input (post SDK parse).
 - `handler` (`string`) — The tool name, for error attribution.
 
+### `registerAppResource(params)`
+
+Registers an [MCP Apps](#mcp-apps-interactive-uis) view: a `ui://` resource whose HTML a host renders for a linked tool's result.
+
+**Parameters (`params`):**
+
+- `server` (`McpServer`) — The MCP server to register the resource on.
+- `name` (`string`) — Resource name, as listed by `resources/list`.
+- `uri` (`string`) — Resource URI. Must use the `ui://` scheme, or the call throws.
+- `description` (`string`, optional) — What the view does and when a host should render it.
+- `html` (`string | ({ uri: URL }) => string | Promise<string>`) — The view's HTML5 document, or a builder invoked per `resources/read`.
+- `ui` (`UiResourceMeta`, optional) — Rendering and security configuration relayed to the host as `_meta.ui`:
+  - `csp` (`UiResourceCsp`) — Origins the view may reach, mapped onto the iframe's Content Security Policy: `connectDomains` (`connect-src`), `resourceDomains` (scripts/styles/images/fonts/media), `frameDomains` (`frame-src`), `baseUriDomains` (`base-uri`). An omitted list is the restrictive default, not "no restriction".
+  - `permissions` (`UiResourcePermissions`) — Browser capabilities requested for the view (`camera`, `microphone`, `geolocation`, `clipboardWrite`), each as `{}`. A host _may_ grant them, so feature-detect in the view rather than assuming.
+  - `domain` (`string`) — Dedicated sandbox origin, for views needing a stable one (OAuth callbacks, CORS, API key allowlists). The format is host-specific.
+  - `prefersBorder` (`boolean`) — Whether the host should draw a border and background around the view.
+
+**Returns:** `RegisteredAppResource`
+
+- `uri` (`string`) — The URI tools link to.
+- `resource` (`RegisteredResource`) — The SDK's registration handle, for `update`/`disable`/`remove`.
+- `toolMeta(params?)` — Builds the `_meta` bag linking a tool to this view, writing both `_meta.ui.resourceUri` and the deprecated flat `_meta['ui/resourceUri']`. Takes `visibility` (`Array<'model' | 'app'>`, optional — the spec's default is both) and `_meta` (`Record<string, unknown>`, optional) to merge further entries in.
+
+### `UI_EXTENSION_ID` / `UI_RESOURCE_MIME_TYPE`
+
+`'io.modelcontextprotocol/ui'` and `'text/html;profile=mcp-app'`. Use the first as the `capabilities.extensions` key when advertising Apps support on the `McpServer`, and the second as the MIME type a host negotiates.
+
 ### `registerToolFromSchema(server, params)`
 
 Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.
@@ -603,6 +703,7 @@ Use this when tool definitions are shared between the MCP server and an AI SDK a
 - `params.description` (`string`, optional) — Human-readable description
 - `params.inputSchema` (`JsonObjectSchema`, optional) — Plain JSON Schema object (defaults to `{ type: 'object', properties: {} }`)
 - `params.validateArguments` (`boolean`, optional) — Enforce `inputSchema` on `tools/call` (default: `false`); see [Argument validation](#argument-validation)
+- `params._meta` (`Record<string, unknown>`, optional) — Tool metadata forwarded verbatim on `tools/list`; how a tool links to an [MCP Apps](#mcp-apps-interactive-uis) view
 - `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) — Tool handler receiving the raw request arguments
 
 **Returns:** `void`
@@ -954,3 +1055,4 @@ newest first.
 - [MCP Documentation](https://modelcontextprotocol.io)
 - [MCP Specification](https://spec.modelcontextprotocol.io/)
 - [MCP SDK TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Apps extension (`io.modelcontextprotocol/ui`)](https://github.com/modelcontextprotocol/ext-apps)

package/dist/index.cjs

@@ -120,6 +120,160 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/registerAppResource.ts
+/**
+* Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
+* the key under `capabilities.extensions` on both sides of the handshake.
+*
+* A client declares Apps support with it; a server may advertise the same key
+* so a host can discover the support without inspecting tool metadata:
+*
+* ```typescript
+* new McpServer(
+*   { name: 'weather', version: '1.0.0' },
+*   {
+*     capabilities: {
+*       extensions: {
+*         [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] },
+*       },
+*     },
+*   }
+* );
+* ```
+*/
+var UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+var UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+* Deprecated flat tool metadata key for the linked resource URI. Written
+* alongside `_meta.ui.resourceUri` because both forms are legal until the
+* extension reaches GA, at which point this key is removed from the spec.
+*/
+var LEGACY_RESOURCE_URI_KEY = "ui/resourceUri";
+/**
+* Registers an MCP Apps view: a `ui://` resource a tool result is rendered
+* with, per the `io.modelcontextprotocol/ui` extension.
+*
+* The extension asks nothing of the transport — a view is an ordinary MCP
+* resource, and the tool linkage is ordinary tool `_meta` — so this is
+* registration sugar over `registerResource`, not new protocol surface. What
+* it owns is the part that is easy to get wrong: the `ui://` scheme, the exact
+* MIME type, `_meta.ui` on both the declaration and the read result, and
+* writing the deprecated flat linkage key alongside the current one.
+*
+* **Register the linkage unconditionally.** The extension's negotiation is
+* per-request and only reliably readable on the `2026-07-28` revision; in this
+* package's default stateless 2025-era mode there is no remembered
+* `initialize` to read a client capability from. Gating registration on that
+* capability would therefore silently drop the view for every 2025-era client.
+* A host without Apps support simply ignores `_meta`, so keep each tool's
+* `content` meaningful on its own and let the text result be the fallback.
+*
+* @example
+* ```typescript
+* import {
+*   McpServer,
+*   registerAppResource,
+*   UI_EXTENSION_ID,
+*   UI_RESOURCE_MIME_TYPE,
+*   z,
+* } from '@ttoss/http-server-mcp';
+*
+* const server = new McpServer(
+*   { name: 'weather', version: '1.0.0' },
+*   {
+*     capabilities: {
+*       extensions: { [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] } },
+*     },
+*   }
+* );
+*
+* const dashboard = registerAppResource({
+*   server,
+*   name: 'weather_dashboard',
+*   uri: 'ui://weather/dashboard',
+*   description: 'Interactive weather dashboard',
+*   html: dashboardHtml,
+*   ui: {
+*     csp: { connectDomains: ['https://api.openweathermap.org'] },
+*     prefersBorder: true,
+*   },
+* });
+*
+* server.registerTool(
+*   'get-weather',
+*   {
+*     description: 'Get the weather for a location',
+*     inputSchema: { location: z.string() },
+*     _meta: dashboard.toolMeta(),
+*   },
+*   async ({ location }) => {
+*     const forecast = await fetchForecast(location);
+*     return {
+*       // Text stays meaningful: it is what a host without Apps renders.
+*       content: [{ type: 'text', text: summarise(forecast) }],
+*       structuredContent: forecast,
+*     };
+*   }
+* );
+* ```
+*/
+var registerAppResource = ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}) => {
+  if (!uri.startsWith("ui://")) throw new Error(`An MCP Apps resource URI must use the ui:// scheme (received "${uri}").`);
+  const meta = ui === void 0 ? void 0 : {
+    ui
+  };
+  const resource = server.registerResource(name, uri, {
+    description,
+    mimeType: UI_RESOURCE_MIME_TYPE,
+    ...(meta === void 0 ? {} : {
+      _meta: meta
+    })
+  }, async requestedUri => {
+    const text = typeof html === "string" ? html : await html({
+      uri: requestedUri
+    });
+    return {
+      contents: [{
+        uri: requestedUri.href,
+        mimeType: UI_RESOURCE_MIME_TYPE,
+        text,
+        ...(meta === void 0 ? {} : {
+          _meta: meta
+        })
+      }]
+    };
+  });
+  const toolMeta = ({
+    visibility,
+    _meta
+  } = {}) => {
+    return {
+      ..._meta,
+      ui: {
+        resourceUri: uri,
+        ...(visibility === void 0 ? {} : {
+          visibility
+        })
+      },
+      [LEGACY_RESOURCE_URI_KEY]: uri
+    };
+  };
+  return {
+    uri,
+    resource,
+    toolMeta
+  };
+};
+
 //#endregion
 //#region src/registerToolFromSchema.ts
 /**
@@ -163,7 +317,7 @@ var toStandardSchema = ({
 *
 * @param server - The `McpServer` instance to register the tool on.
 * @param params - Tool configuration including name, description, inputSchema,
-*   validateArguments, and handler.
+*   validateArguments, `_meta`, and handler.
 *
 * @example
 * ```typescript
@@ -194,14 +348,16 @@ var registerToolFromSchema = (server, params) => {
       properties: {}
     },
     validateArguments = false,
-    handler
+    handler,
+    _meta
   } = params;
   server.registerTool(name, {
     description,
     inputSchema: toStandardSchema({
       inputSchema,
       validateArguments
-    })
+    }),
+    _meta
   }, async args => {
     return handler(args);
   });
@@ -316,7 +472,8 @@ var createGatedToolRegistrar = ({
     };
     server.registerTool(def.name, {
       description: def.description,
-      inputSchema: def.inputSchema
+      inputSchema: def.inputSchema,
+      _meta: def._meta
     }, handler);
   };
   return {
@@ -642,11 +799,14 @@ Object.defineProperty(exports, 'McpServer', {
     return _modelcontextprotocol_server.McpServer;
   }
 });
+exports.UI_EXTENSION_ID = UI_EXTENSION_ID;
+exports.UI_RESOURCE_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
 exports.createGatedToolRegistrar = createGatedToolRegistrar;
 exports.createMcpRouter = createMcpRouter;
 exports.getIdentity = getIdentity;
+exports.registerAppResource = registerAppResource;
 exports.registerToolFromSchema = registerToolFromSchema;
 Object.defineProperty(exports, 'z', {
   enumerable: true,

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
 /// <reference types="node" />
-import { CallToolResult, McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/server";
+import { CallToolResult, McpServer, McpServer as McpServer$1, RegisteredResource } from "@modelcontextprotocol/server";
 import { Router } from "@ttoss/http-server";
 import accepts from "accepts";
 import { AsyncLocalStorage } from "async_hooks";
@@ -675,6 +675,197 @@ declare namespace Application {
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
 //#endregion
+//#region src/registerAppResource.d.ts
+/**
+ * Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
+ * the key under `capabilities.extensions` on both sides of the handshake.
+ *
+ * A client declares Apps support with it; a server may advertise the same key
+ * so a host can discover the support without inspecting tool metadata:
+ *
+ * ```typescript
+ * new McpServer(
+ *   { name: 'weather', version: '1.0.0' },
+ *   {
+ *     capabilities: {
+ *       extensions: {
+ *         [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] },
+ *       },
+ *     },
+ *   }
+ * );
+ * ```
+ */
+declare const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+declare const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Origins an app's view is allowed to reach, mapped by the host onto the
+ * iframe's Content Security Policy. Anything not declared is blocked: an
+ * omitted list is the restrictive default, not "no restriction".
+ */
+interface UiResourceCsp {
+  /** Origins for network requests (`connect-src`). */
+  connectDomains?: string[];
+  /**
+   * Origins for scripts, styles, images, fonts and media (`script-src`,
+   * `style-src`, `img-src`, `font-src`, `media-src`).
+   */
+  resourceDomains?: string[];
+  /** Origins for nested iframes (`frame-src`). */
+  frameDomains?: string[];
+  /** Allowed document base URIs (`base-uri`). */
+  baseUriDomains?: string[];
+}
+/**
+ * Browser capabilities the view asks for. A host *may* grant them, so a view
+ * should feature-detect rather than assume: each key is a request, not a
+ * guarantee.
+ */
+interface UiResourcePermissions {
+  camera?: Record<string, never>;
+  microphone?: Record<string, never>;
+  geolocation?: Record<string, never>;
+  clipboardWrite?: Record<string, never>;
+}
+/** Rendering and security configuration for an app's view (`_meta.ui`). */
+interface UiResourceMeta {
+  /** Origins the view may reach; omitted means none. */
+  csp?: UiResourceCsp;
+  /** Browser capabilities requested for the view. */
+  permissions?: UiResourcePermissions;
+  /**
+   * Dedicated sandbox origin for the view, for cases needing a stable origin
+   * (OAuth callbacks, CORS, API key allowlists). The accepted format is
+   * host-specific; consult the host's documentation rather than deriving one.
+   */
+  domain?: string;
+  /** Whether the host should draw a border and background around the view. */
+  prefersBorder?: boolean;
+}
+/** Who may reach a tool. Defaults to both when left unset. */
+type UiToolVisibility = 'model' | 'app';
+/** Parameters for {@link registerAppResource}. */
+interface RegisterAppResourceParams {
+  /** The `McpServer` instance to register the app resource on. */
+  server: McpServer$1;
+  /** Resource name, as listed by `resources/list`. */
+  name: string;
+  /** Resource URI. Must use the `ui://` scheme. */
+  uri: string;
+  /** What the view does and when a host should render it. */
+  description?: string;
+  /**
+   * The view's HTML5 document, or a builder invoked per `resources/read`.
+   * A builder receives the requested URI so one registration can serve
+   * variants of a document.
+   */
+  html: string | ((args: {
+    uri: URL;
+  }) => string | Promise<string>);
+  /** Rendering and security configuration relayed to the host as `_meta.ui`. */
+  ui?: UiResourceMeta;
+}
+/** Parameters for {@link RegisteredAppResource.toolMeta}. */
+interface ToolMetaParams {
+  /**
+   * Who may reach the tool. Left unset, the spec's default applies — visible
+   * to the model *and* callable by the app.
+   */
+  visibility?: UiToolVisibility[];
+  /** Further `_meta` entries to merge in, e.g. vendor-namespaced keys. */
+  _meta?: Record<string, unknown>;
+}
+/** An app resource registered by {@link registerAppResource}. */
+interface RegisteredAppResource {
+  /** The URI tools link to. */
+  uri: string;
+  /** The SDK's registration handle, for `update`/`disable`/`remove`. */
+  resource: RegisteredResource;
+  /**
+   * Builds the `_meta` bag that links a tool to this view. Pass it to
+   * `registerTool`, {@link registerToolFromSchema}, or a `GatedToolDef` —
+   * whichever registration path the tool uses.
+   */
+  toolMeta: (params?: ToolMetaParams) => Record<string, unknown>;
+}
+/**
+ * Registers an MCP Apps view: a `ui://` resource a tool result is rendered
+ * with, per the `io.modelcontextprotocol/ui` extension.
+ *
+ * The extension asks nothing of the transport — a view is an ordinary MCP
+ * resource, and the tool linkage is ordinary tool `_meta` — so this is
+ * registration sugar over `registerResource`, not new protocol surface. What
+ * it owns is the part that is easy to get wrong: the `ui://` scheme, the exact
+ * MIME type, `_meta.ui` on both the declaration and the read result, and
+ * writing the deprecated flat linkage key alongside the current one.
+ *
+ * **Register the linkage unconditionally.** The extension's negotiation is
+ * per-request and only reliably readable on the `2026-07-28` revision; in this
+ * package's default stateless 2025-era mode there is no remembered
+ * `initialize` to read a client capability from. Gating registration on that
+ * capability would therefore silently drop the view for every 2025-era client.
+ * A host without Apps support simply ignores `_meta`, so keep each tool's
+ * `content` meaningful on its own and let the text result be the fallback.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   McpServer,
+ *   registerAppResource,
+ *   UI_EXTENSION_ID,
+ *   UI_RESOURCE_MIME_TYPE,
+ *   z,
+ * } from '@ttoss/http-server-mcp';
+ *
+ * const server = new McpServer(
+ *   { name: 'weather', version: '1.0.0' },
+ *   {
+ *     capabilities: {
+ *       extensions: { [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] } },
+ *     },
+ *   }
+ * );
+ *
+ * const dashboard = registerAppResource({
+ *   server,
+ *   name: 'weather_dashboard',
+ *   uri: 'ui://weather/dashboard',
+ *   description: 'Interactive weather dashboard',
+ *   html: dashboardHtml,
+ *   ui: {
+ *     csp: { connectDomains: ['https://api.openweathermap.org'] },
+ *     prefersBorder: true,
+ *   },
+ * });
+ *
+ * server.registerTool(
+ *   'get-weather',
+ *   {
+ *     description: 'Get the weather for a location',
+ *     inputSchema: { location: z.string() },
+ *     _meta: dashboard.toolMeta(),
+ *   },
+ *   async ({ location }) => {
+ *     const forecast = await fetchForecast(location);
+ *     return {
+ *       // Text stays meaningful: it is what a host without Apps renders.
+ *       content: [{ type: 'text', text: summarise(forecast) }],
+ *       structuredContent: forecast,
+ *     };
+ *   }
+ * );
+ * ```
+ */
+declare const registerAppResource: ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}: RegisterAppResourceParams) => RegisteredAppResource;
+//#endregion
 //#region src/registerToolFromSchema.d.ts
 /**
  * A plain JSON Schema object (draft-07 compatible) describing the shape of a
@@ -721,6 +912,19 @@ interface RegisterToolFromSchemaParams {
    * @default false
    */
   validateArguments?: boolean;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list`.
+   *
+   * The MCP Apps extension links a tool to the view its result is rendered
+   * with through this field; build the bag with `toolMeta()` from
+   * `registerAppResource` rather than writing the keys by hand.
+   *
+   * @example
+   * ```typescript
+   * _meta: dashboard.toolMeta({ visibility: ['app'] }),
+   * ```
+   */
+  _meta?: Record<string, unknown>;
   /**
    * Tool handler invoked when the AI client calls the tool.
    * Receives the request arguments, validated against `inputSchema` only when
@@ -744,7 +948,7 @@ interface RegisterToolFromSchemaParams {
  *
  * @param server - The `McpServer` instance to register the tool on.
  * @param params - Tool configuration including name, description, inputSchema,
- *   validateArguments, and handler.
+ *   validateArguments, `_meta`, and handler.
  *
  * @example
  * ```typescript
@@ -801,7 +1005,12 @@ type GatedToolDef = {
    * Each gate receives the full {@link ToolCallContext} (identity + args).
    * Throw to reject the call; return (or resolve) to continue.
    */
-  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** The tool handler. Receives merged call args + `buildContext` output. */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list` — how a gated tool links
+   * to an MCP Apps view (`registerAppResource(...).toolMeta()`).
+   */
+  _meta?: Record<string, unknown>; /** The tool handler. Receives merged call args + `buildContext` output. */
   method: (args: Record<string, unknown>) => Promise<unknown>;
 };
 /** Options for {@link createGatedToolRegistrar}. */
@@ -1210,4 +1419,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { CallToolResult, McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/server";
+import { CallToolResult, McpServer, McpServer as McpServer$1, RegisteredResource } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
@@ -676,6 +676,197 @@ declare namespace Application {
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
 //#endregion
+//#region src/registerAppResource.d.ts
+/**
+ * Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
+ * the key under `capabilities.extensions` on both sides of the handshake.
+ *
+ * A client declares Apps support with it; a server may advertise the same key
+ * so a host can discover the support without inspecting tool metadata:
+ *
+ * ```typescript
+ * new McpServer(
+ *   { name: 'weather', version: '1.0.0' },
+ *   {
+ *     capabilities: {
+ *       extensions: {
+ *         [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] },
+ *       },
+ *     },
+ *   }
+ * );
+ * ```
+ */
+declare const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+declare const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Origins an app's view is allowed to reach, mapped by the host onto the
+ * iframe's Content Security Policy. Anything not declared is blocked: an
+ * omitted list is the restrictive default, not "no restriction".
+ */
+interface UiResourceCsp {
+  /** Origins for network requests (`connect-src`). */
+  connectDomains?: string[];
+  /**
+   * Origins for scripts, styles, images, fonts and media (`script-src`,
+   * `style-src`, `img-src`, `font-src`, `media-src`).
+   */
+  resourceDomains?: string[];
+  /** Origins for nested iframes (`frame-src`). */
+  frameDomains?: string[];
+  /** Allowed document base URIs (`base-uri`). */
+  baseUriDomains?: string[];
+}
+/**
+ * Browser capabilities the view asks for. A host *may* grant them, so a view
+ * should feature-detect rather than assume: each key is a request, not a
+ * guarantee.
+ */
+interface UiResourcePermissions {
+  camera?: Record<string, never>;
+  microphone?: Record<string, never>;
+  geolocation?: Record<string, never>;
+  clipboardWrite?: Record<string, never>;
+}
+/** Rendering and security configuration for an app's view (`_meta.ui`). */
+interface UiResourceMeta {
+  /** Origins the view may reach; omitted means none. */
+  csp?: UiResourceCsp;
+  /** Browser capabilities requested for the view. */
+  permissions?: UiResourcePermissions;
+  /**
+   * Dedicated sandbox origin for the view, for cases needing a stable origin
+   * (OAuth callbacks, CORS, API key allowlists). The accepted format is
+   * host-specific; consult the host's documentation rather than deriving one.
+   */
+  domain?: string;
+  /** Whether the host should draw a border and background around the view. */
+  prefersBorder?: boolean;
+}
+/** Who may reach a tool. Defaults to both when left unset. */
+type UiToolVisibility = 'model' | 'app';
+/** Parameters for {@link registerAppResource}. */
+interface RegisterAppResourceParams {
+  /** The `McpServer` instance to register the app resource on. */
+  server: McpServer$1;
+  /** Resource name, as listed by `resources/list`. */
+  name: string;
+  /** Resource URI. Must use the `ui://` scheme. */
+  uri: string;
+  /** What the view does and when a host should render it. */
+  description?: string;
+  /**
+   * The view's HTML5 document, or a builder invoked per `resources/read`.
+   * A builder receives the requested URI so one registration can serve
+   * variants of a document.
+   */
+  html: string | ((args: {
+    uri: URL;
+  }) => string | Promise<string>);
+  /** Rendering and security configuration relayed to the host as `_meta.ui`. */
+  ui?: UiResourceMeta;
+}
+/** Parameters for {@link RegisteredAppResource.toolMeta}. */
+interface ToolMetaParams {
+  /**
+   * Who may reach the tool. Left unset, the spec's default applies — visible
+   * to the model *and* callable by the app.
+   */
+  visibility?: UiToolVisibility[];
+  /** Further `_meta` entries to merge in, e.g. vendor-namespaced keys. */
+  _meta?: Record<string, unknown>;
+}
+/** An app resource registered by {@link registerAppResource}. */
+interface RegisteredAppResource {
+  /** The URI tools link to. */
+  uri: string;
+  /** The SDK's registration handle, for `update`/`disable`/`remove`. */
+  resource: RegisteredResource;
+  /**
+   * Builds the `_meta` bag that links a tool to this view. Pass it to
+   * `registerTool`, {@link registerToolFromSchema}, or a `GatedToolDef` —
+   * whichever registration path the tool uses.
+   */
+  toolMeta: (params?: ToolMetaParams) => Record<string, unknown>;
+}
+/**
+ * Registers an MCP Apps view: a `ui://` resource a tool result is rendered
+ * with, per the `io.modelcontextprotocol/ui` extension.
+ *
+ * The extension asks nothing of the transport — a view is an ordinary MCP
+ * resource, and the tool linkage is ordinary tool `_meta` — so this is
+ * registration sugar over `registerResource`, not new protocol surface. What
+ * it owns is the part that is easy to get wrong: the `ui://` scheme, the exact
+ * MIME type, `_meta.ui` on both the declaration and the read result, and
+ * writing the deprecated flat linkage key alongside the current one.
+ *
+ * **Register the linkage unconditionally.** The extension's negotiation is
+ * per-request and only reliably readable on the `2026-07-28` revision; in this
+ * package's default stateless 2025-era mode there is no remembered
+ * `initialize` to read a client capability from. Gating registration on that
+ * capability would therefore silently drop the view for every 2025-era client.
+ * A host without Apps support simply ignores `_meta`, so keep each tool's
+ * `content` meaningful on its own and let the text result be the fallback.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   McpServer,
+ *   registerAppResource,
+ *   UI_EXTENSION_ID,
+ *   UI_RESOURCE_MIME_TYPE,
+ *   z,
+ * } from '@ttoss/http-server-mcp';
+ *
+ * const server = new McpServer(
+ *   { name: 'weather', version: '1.0.0' },
+ *   {
+ *     capabilities: {
+ *       extensions: { [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] } },
+ *     },
+ *   }
+ * );
+ *
+ * const dashboard = registerAppResource({
+ *   server,
+ *   name: 'weather_dashboard',
+ *   uri: 'ui://weather/dashboard',
+ *   description: 'Interactive weather dashboard',
+ *   html: dashboardHtml,
+ *   ui: {
+ *     csp: { connectDomains: ['https://api.openweathermap.org'] },
+ *     prefersBorder: true,
+ *   },
+ * });
+ *
+ * server.registerTool(
+ *   'get-weather',
+ *   {
+ *     description: 'Get the weather for a location',
+ *     inputSchema: { location: z.string() },
+ *     _meta: dashboard.toolMeta(),
+ *   },
+ *   async ({ location }) => {
+ *     const forecast = await fetchForecast(location);
+ *     return {
+ *       // Text stays meaningful: it is what a host without Apps renders.
+ *       content: [{ type: 'text', text: summarise(forecast) }],
+ *       structuredContent: forecast,
+ *     };
+ *   }
+ * );
+ * ```
+ */
+declare const registerAppResource: ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}: RegisterAppResourceParams) => RegisteredAppResource;
+//#endregion
 //#region src/registerToolFromSchema.d.ts
 /**
  * A plain JSON Schema object (draft-07 compatible) describing the shape of a
@@ -722,6 +913,19 @@ interface RegisterToolFromSchemaParams {
    * @default false
    */
   validateArguments?: boolean;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list`.
+   *
+   * The MCP Apps extension links a tool to the view its result is rendered
+   * with through this field; build the bag with `toolMeta()` from
+   * `registerAppResource` rather than writing the keys by hand.
+   *
+   * @example
+   * ```typescript
+   * _meta: dashboard.toolMeta({ visibility: ['app'] }),
+   * ```
+   */
+  _meta?: Record<string, unknown>;
   /**
    * Tool handler invoked when the AI client calls the tool.
    * Receives the request arguments, validated against `inputSchema` only when
@@ -745,7 +949,7 @@ interface RegisterToolFromSchemaParams {
  *
  * @param server - The `McpServer` instance to register the tool on.
  * @param params - Tool configuration including name, description, inputSchema,
- *   validateArguments, and handler.
+ *   validateArguments, `_meta`, and handler.
  *
  * @example
  * ```typescript
@@ -802,7 +1006,12 @@ type GatedToolDef = {
    * Each gate receives the full {@link ToolCallContext} (identity + args).
    * Throw to reject the call; return (or resolve) to continue.
    */
-  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** The tool handler. Receives merged call args + `buildContext` output. */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list` — how a gated tool links
+   * to an MCP Apps view (`registerAppResource(...).toolMeta()`).
+   */
+  _meta?: Record<string, unknown>; /** The tool handler. Receives merged call args + `buildContext` output. */
   method: (args: Record<string, unknown>) => Promise<unknown>;
 };
 /** Options for {@link createGatedToolRegistrar}. */
@@ -1211,4 +1420,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.mjs

@@ -117,6 +117,160 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/registerAppResource.ts
+/**
+* Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
+* the key under `capabilities.extensions` on both sides of the handshake.
+*
+* A client declares Apps support with it; a server may advertise the same key
+* so a host can discover the support without inspecting tool metadata:
+*
+* ```typescript
+* new McpServer(
+*   { name: 'weather', version: '1.0.0' },
+*   {
+*     capabilities: {
+*       extensions: {
+*         [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] },
+*       },
+*     },
+*   }
+* );
+* ```
+*/
+var UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+var UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+* Deprecated flat tool metadata key for the linked resource URI. Written
+* alongside `_meta.ui.resourceUri` because both forms are legal until the
+* extension reaches GA, at which point this key is removed from the spec.
+*/
+var LEGACY_RESOURCE_URI_KEY = "ui/resourceUri";
+/**
+* Registers an MCP Apps view: a `ui://` resource a tool result is rendered
+* with, per the `io.modelcontextprotocol/ui` extension.
+*
+* The extension asks nothing of the transport — a view is an ordinary MCP
+* resource, and the tool linkage is ordinary tool `_meta` — so this is
+* registration sugar over `registerResource`, not new protocol surface. What
+* it owns is the part that is easy to get wrong: the `ui://` scheme, the exact
+* MIME type, `_meta.ui` on both the declaration and the read result, and
+* writing the deprecated flat linkage key alongside the current one.
+*
+* **Register the linkage unconditionally.** The extension's negotiation is
+* per-request and only reliably readable on the `2026-07-28` revision; in this
+* package's default stateless 2025-era mode there is no remembered
+* `initialize` to read a client capability from. Gating registration on that
+* capability would therefore silently drop the view for every 2025-era client.
+* A host without Apps support simply ignores `_meta`, so keep each tool's
+* `content` meaningful on its own and let the text result be the fallback.
+*
+* @example
+* ```typescript
+* import {
+*   McpServer,
+*   registerAppResource,
+*   UI_EXTENSION_ID,
+*   UI_RESOURCE_MIME_TYPE,
+*   z,
+* } from '@ttoss/http-server-mcp';
+*
+* const server = new McpServer(
+*   { name: 'weather', version: '1.0.0' },
+*   {
+*     capabilities: {
+*       extensions: { [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] } },
+*     },
+*   }
+* );
+*
+* const dashboard = registerAppResource({
+*   server,
+*   name: 'weather_dashboard',
+*   uri: 'ui://weather/dashboard',
+*   description: 'Interactive weather dashboard',
+*   html: dashboardHtml,
+*   ui: {
+*     csp: { connectDomains: ['https://api.openweathermap.org'] },
+*     prefersBorder: true,
+*   },
+* });
+*
+* server.registerTool(
+*   'get-weather',
+*   {
+*     description: 'Get the weather for a location',
+*     inputSchema: { location: z.string() },
+*     _meta: dashboard.toolMeta(),
+*   },
+*   async ({ location }) => {
+*     const forecast = await fetchForecast(location);
+*     return {
+*       // Text stays meaningful: it is what a host without Apps renders.
+*       content: [{ type: 'text', text: summarise(forecast) }],
+*       structuredContent: forecast,
+*     };
+*   }
+* );
+* ```
+*/
+var registerAppResource = ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}) => {
+  if (!uri.startsWith("ui://")) throw new Error(`An MCP Apps resource URI must use the ui:// scheme (received "${uri}").`);
+  const meta = ui === void 0 ? void 0 : {
+    ui
+  };
+  const resource = server.registerResource(name, uri, {
+    description,
+    mimeType: UI_RESOURCE_MIME_TYPE,
+    ...(meta === void 0 ? {} : {
+      _meta: meta
+    })
+  }, async requestedUri => {
+    const text = typeof html === "string" ? html : await html({
+      uri: requestedUri
+    });
+    return {
+      contents: [{
+        uri: requestedUri.href,
+        mimeType: UI_RESOURCE_MIME_TYPE,
+        text,
+        ...(meta === void 0 ? {} : {
+          _meta: meta
+        })
+      }]
+    };
+  });
+  const toolMeta = ({
+    visibility,
+    _meta
+  } = {}) => {
+    return {
+      ..._meta,
+      ui: {
+        resourceUri: uri,
+        ...(visibility === void 0 ? {} : {
+          visibility
+        })
+      },
+      [LEGACY_RESOURCE_URI_KEY]: uri
+    };
+  };
+  return {
+    uri,
+    resource,
+    toolMeta
+  };
+};
+
 //#endregion
 //#region src/registerToolFromSchema.ts
 /**
@@ -160,7 +314,7 @@ var toStandardSchema = ({
 *
 * @param server - The `McpServer` instance to register the tool on.
 * @param params - Tool configuration including name, description, inputSchema,
-*   validateArguments, and handler.
+*   validateArguments, `_meta`, and handler.
 *
 * @example
 * ```typescript
@@ -191,14 +345,16 @@ var registerToolFromSchema = (server, params) => {
       properties: {}
     },
     validateArguments = false,
-    handler
+    handler,
+    _meta
   } = params;
   server.registerTool(name, {
     description,
     inputSchema: toStandardSchema({
       inputSchema,
       validateArguments
-    })
+    }),
+    _meta
   }, async args => {
     return handler(args);
   });
@@ -313,7 +469,8 @@ var createGatedToolRegistrar = ({
     };
     server.registerTool(def.name, {
       description: def.description,
-      inputSchema: def.inputSchema
+      inputSchema: def.inputSchema,
+      _meta: def._meta
     }, handler);
   };
   return {
@@ -633,4 +790,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { McpServer, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",