@nuxtjs/mcp-toolkit 0.7.0 → 0.10.0

package/dist/module.d.mts

@@ -35,6 +35,23 @@ interface ModuleOptions {
      * @default 'mcp'
      */
     dir?: string;
+    /**
+     * Enable MCP session management (stateful transport).
+     * When enabled, the server assigns session IDs and maintains state across requests,
+     * enabling SSE streaming, server-to-client notifications, and resumability.
+     *
+     * Pass `true` for defaults or an object to configure session behavior.
+     * @default false
+     * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+     */
+    sessions?: boolean | {
+        enabled?: boolean;
+        /**
+         * Maximum session duration in milliseconds. Sessions inactive longer than this are cleaned up.
+         * @default 1800000 (30 minutes)
+         */
+        maxDuration?: number;
+    };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "configKey": "mcp",
   "docs": "https://mcp-toolkit.nuxt.dev/getting-started/installation",
   "mcp": "https://mcp-toolkit.nuxt.dev/mcp",

package/dist/module.mjs

@@ -2,7 +2,6 @@ import { logger, createResolver, defineNuxtModule, addComponent, addServerTempla
 import { loadAllDefinitions } from '../dist/runtime/server/mcp/loaders/index.js';
 import { defaultMcpConfig, getMcpConfig } from '../dist/runtime/server/mcp/config.js';
 import { ROUTES } from '../dist/runtime/server/mcp/constants.js';
-import { addDevToolsCustomTabs } from '../dist/runtime/server/mcp/devtools/index.js';
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -72,7 +71,7 @@ function generateDeeplinkUrl(baseUrl, route, ide, serverName) {
 }
 
 const name = "@nuxtjs/mcp-toolkit";
-const version = "0.7.0";
+const version = "0.10.0";
 
 const log = logger.withTag("@nuxtjs/mcp-toolkit");
 const { resolve } = createResolver(import.meta.url);
@@ -86,15 +85,23 @@ const module$1 = defineNuxtModule({
   },
   defaults: defaultMcpConfig,
   async setup(options, nuxt) {
-    if (nuxt.options.nitro.static || nuxt.options._generate) {
+    const nitroOptions = nuxt.options.nitro;
+    if (nitroOptions?.static || nuxt.options._generate) {
       log.warn("@nuxtjs/mcp-toolkit is not compatible with `nuxt generate` as it needs a server to run.");
       return;
     }
     const resolver = createResolver(import.meta.url);
+    if (typeof options.sessions === "boolean") {
+      options.sessions = { enabled: options.sessions };
+    }
     const mcpConfig = getMcpConfig(options);
     if (!options.enabled) {
       return;
     }
+    if (mcpConfig.sessions.enabled && nitroOptions) {
+      nitroOptions.storage ??= {};
+      nitroOptions.storage["mcp:sessions"] ??= { driver: "memory" };
+    }
     addComponent({
       name: "InstallButton",
       filePath: resolver.resolve("runtime/components/InstallButton.vue")
@@ -163,10 +170,12 @@ const module$1 = defineNuxtModule({
         path: resolver.resolve("runtime/server/types.server.d.ts")
       });
     });
-    nuxt.options.nitro.typescript ??= {};
-    nuxt.options.nitro.typescript.tsConfig ??= {};
-    nuxt.options.nitro.typescript.tsConfig.include ??= [];
-    nuxt.options.nitro.typescript.tsConfig.include.push(resolver.resolve("runtime/server/types.server.d.ts"));
+    if (nitroOptions) {
+      nitroOptions.typescript ??= {};
+      nitroOptions.typescript.tsConfig ??= {};
+      nitroOptions.typescript.tsConfig.include ??= [];
+      nitroOptions.typescript.tsConfig.include.push(resolver.resolve("runtime/server/types.server.d.ts"));
+    }
     let isCloudflare = false;
     if (!nuxt.options.dev) {
       nuxt.hook("nitro:config", (nitroConfig) => {
@@ -182,6 +191,8 @@ const module$1 = defineNuxtModule({
       }
     });
     const mcpDefinitionsPath = resolver.resolve("runtime/server/mcp/definitions");
+    const mcpSessionPath = resolver.resolve("runtime/server/mcp/session");
+    const mcpServerPath = resolver.resolve("runtime/server/mcp/server");
     addServerImports([
       "defineMcpTool",
       "defineMcpResource",
@@ -192,6 +203,10 @@ const module$1 = defineNuxtModule({
       "errorResult",
       "imageResult"
     ].map((name2) => ({ name: name2, from: mcpDefinitionsPath })));
+    addServerImports([
+      { name: "useMcpSession", from: mcpSessionPath },
+      { name: "useMcpServer", from: mcpServerPath }
+    ]);
     addServerHandler({
       route: options.route,
       handler: resolver.resolve("runtime/server/mcp/handler")
@@ -204,7 +219,11 @@ const module$1 = defineNuxtModule({
       route: `${options.route}/badge.svg`,
       handler: resolver.resolve("runtime/server/mcp/badge-image")
     });
-    addDevToolsCustomTabs(nuxt, options);
+    if (nuxt.options.dev) {
+      import('../dist/runtime/server/mcp/devtools/index.js').then(({ addDevToolsCustomTabs }) => {
+        addDevToolsCustomTabs(nuxt, options);
+      });
+    }
   }
 });
 

package/dist/runtime/server/mcp/badge-image.d.ts

@@ -1,3 +1,3 @@
 export type SupportedIDE = 'cursor' | 'vscode';
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<string>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, string>;
 export default _default;

package/dist/runtime/server/mcp/badge-image.js

@@ -1,5 +1,4 @@
 import { defineEventHandler, getQuery, setHeader } from "h3";
-import satori from "satori";
 const IDE_CONFIG = {
   cursor: {
     defaultLabel: "Install MCP in Cursor"
@@ -8,125 +7,51 @@ const IDE_CONFIG = {
     defaultLabel: "Install MCP in VS Code"
   }
 };
-function CursorIcon() {
-  return {
-    type: "svg",
-    props: {
-      width: 18,
-      height: 18,
-      viewBox: "0 0 24 24",
-      style: { filter: "invert(1)" },
-      children: [
-        {
-          type: "path",
-          props: {
-            fill: "#666",
-            d: "M11.925 24l10.425-6-10.425-6L1.5 18l10.425 6z"
-          }
-        },
-        {
-          type: "path",
-          props: {
-            fill: "#888",
-            d: "M22.35 18V6L11.925 0v12l10.425 6z"
-          }
-        },
-        {
-          type: "path",
-          props: {
-            fill: "#777",
-            d: "M11.925 0L1.5 6v12l10.425-6V0z"
-          }
-        },
-        {
-          type: "path",
-          props: {
-            fill: "#555",
-            d: "M22.35 6L11.925 24V12L22.35 6z"
-          }
-        },
-        {
-          type: "path",
-          props: {
-            fill: "#333",
-            d: "M22.35 6l-10.425 6L1.5 6h20.85z"
-          }
-        }
-      ]
-    }
-  };
+function cursorIconSvg() {
+  return `<g transform="translate(8,7) scale(0.75)">
+    <path fill="#999" d="M11.925 24l10.425-6-10.425-6L1.5 18l10.425 6z"/>
+    <path fill="#bbb" d="M22.35 18V6L11.925 0v12l10.425 6z"/>
+    <path fill="#aaa" d="M11.925 0L1.5 6v12l10.425-6V0z"/>
+    <path fill="#888" d="M22.35 6L11.925 24V12L22.35 6z"/>
+    <path fill="#fff" d="M22.35 6l-10.425 6L1.5 6h20.85z"/>
+  </g>`;
 }
-function VSCodeIconSimple() {
-  return {
-    type: "svg",
-    props: {
-      width: 18,
-      height: 18,
-      viewBox: "0 0 24 24",
-      children: [
-        {
-          type: "path",
-          props: {
-            fill: "#007ACC",
-            d: "M23.15 2.587L18.21.21a1.494 1.494 0 0 0-1.705.29l-9.46 8.63l-4.12-3.128a.999.999 0 0 0-1.276.057L.327 7.261A1 1 0 0 0 .326 8.74L3.899 12L.326 15.26a1 1 0 0 0 .001 1.479L1.65 17.94a.999.999 0 0 0 1.276.057l4.12-3.128l9.46 8.63a1.492 1.492 0 0 0 1.704.29l4.942-2.377A1.5 1.5 0 0 0 24 20.06V3.939a1.5 1.5 0 0 0-.85-1.352zm-5.146 14.861L10.826 12l7.178-5.448v10.896z"
-          }
-        }
-      ]
-    }
-  };
+function vscodeIconSvg() {
+  return `<g transform="translate(8,7) scale(0.75)">
+    <path fill="#007ACC" d="M23.15 2.587L18.21.21a1.494 1.494 0 0 0-1.705.29l-9.46 8.63l-4.12-3.128a.999.999 0 0 0-1.276.057L.327 7.261A1 1 0 0 0 .326 8.74L3.899 12L.326 15.26a1 1 0 0 0 .001 1.479L1.65 17.94a.999.999 0 0 0 1.276.057l4.12-3.128l9.46 8.63a1.492 1.492 0 0 0 1.704.29l4.942-2.377A1.5 1.5 0 0 0 24 20.06V3.939a1.5 1.5 0 0 0-.85-1.352zm-5.146 14.861L10.826 12l7.178-5.448v10.896z"/>
+  </g>`;
 }
-function getIcon(ide) {
-  return ide === "vscode" ? VSCodeIconSimple() : CursorIcon();
+function estimateTextWidth(text, fontSize) {
+  const ratio = fontSize / 13;
+  let width = 0;
+  for (const ch of text) {
+    if (ch === " ") width += 3.6;
+    else if ("iIl|1!:;.,".includes(ch)) width += 4.2;
+    else if (`fjrt()[]{}'"/`.includes(ch)) width += 5.2;
+    else if ("mwMW".includes(ch)) width += 10;
+    else if (ch >= "A" && ch <= "Z") width += 8.5;
+    else width += 7;
+  }
+  return width * ratio;
 }
-async function generateBadgeSVG(options) {
+function generateBadgeSVG(options) {
   const { label, color, textColor, borderColor, showIcon, ide } = options;
-  const icon = getIcon(ide);
-  const element = {
-    type: "div",
-    props: {
-      style: {
-        display: "flex",
-        alignItems: "center",
-        gap: "8px",
-        padding: "6px 8px",
-        fontSize: "14px",
-        fontWeight: 500,
-        color: `#${textColor}`,
-        backgroundColor: `#${color}`,
-        border: `1px solid #${borderColor}`
-      },
-      children: showIcon ? [icon, { type: "span", props: { children: label } }] : [{ type: "span", props: { children: label } }]
-    }
-  };
   const iconWidth = showIcon ? 26 : 0;
-  const textWidth = label.length * 8;
-  const padding = 20;
-  const width = Math.max(Math.ceil(iconWidth + textWidth + padding), 140);
+  const textWidth = estimateTextWidth(label, 13);
+  const padding = showIcon ? 24 : 22;
+  const width = Math.ceil(iconWidth + textWidth + padding);
   const height = 32;
-  const svg = await satori(element, {
-    width,
-    height,
-    fonts: [
-      {
-        name: "Inter",
-        data: await loadFont(),
-        weight: 500,
-        style: "normal"
-      }
-    ]
-  });
-  return svg;
+  const textX = showIcon ? 34 : width / 2;
+  const textAnchor = showIcon ? "start" : "middle";
+  const icon = showIcon ? ide === "vscode" ? vscodeIconSvg() : cursorIconSvg() : "";
+  const escapedLabel = label.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+  <rect x="0.5" y="0.5" width="${width - 1}" height="${height - 1}" rx="4" fill="#${color}" stroke="#${borderColor}"/>
+  ${icon}
+  <text x="${textX}" y="21" fill="#${textColor}" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500" text-anchor="${textAnchor}">${escapedLabel}</text>
+</svg>`;
 }
-async function loadFont() {
-  const response = await fetch(
-    "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fAZ9hjp-Ek-_EeA.woff"
-  );
-  if (!response.ok) {
-    throw new Error(`Failed to load font: ${response.status} ${response.statusText}`);
-  }
-  return response.arrayBuffer();
-}
-export default defineEventHandler(async (event) => {
+export default defineEventHandler((event) => {
   const query = getQuery(event);
   const ide = query.ide || "cursor";
   const ideConfig = IDE_CONFIG[ide] || IDE_CONFIG.cursor;
@@ -138,17 +63,8 @@ export default defineEventHandler(async (event) => {
     borderColor: query.borderColor || "404040",
     showIcon: query.icon !== "false"
   };
-  try {
-    const svg = await generateBadgeSVG(options);
-    setHeader(event, "Content-Type", "image/svg+xml");
-    setHeader(event, "Cache-Control", "public, max-age=86400");
-    return svg;
-  } catch {
-    setHeader(event, "Content-Type", "image/svg+xml");
-    setHeader(event, "Cache-Control", "no-cache");
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="140" height="32">
-      <rect width="140" height="32" fill="#171717" stroke="#404040"/>
-      <text x="70" y="20" fill="#fff" font-size="12" text-anchor="middle">${options.label}</text>
-    </svg>`;
-  }
+  const svg = generateBadgeSVG(options);
+  setHeader(event, "Content-Type", "image/svg+xml");
+  setHeader(event, "Cache-Control", "public, max-age=86400");
+  return svg;
 });

package/dist/runtime/server/mcp/config.d.ts

@@ -1,3 +1,7 @@
+export interface McpSessionsConfig {
+    enabled: boolean;
+    maxDuration: number;
+}
 export interface McpConfig {
     enabled: boolean;
     route: string;
@@ -5,6 +9,7 @@ export interface McpConfig {
     name: string;
     version: string;
     dir: string;
+    sessions: McpSessionsConfig;
 }
 export declare const defaultMcpConfig: McpConfig;
 export declare function getMcpConfig(partial?: Partial<McpConfig>): McpConfig;

package/dist/runtime/server/mcp/config.js

@@ -1,12 +1,26 @@
-import { defu } from "defu";
 export const defaultMcpConfig = {
   enabled: true,
   route: "/mcp",
   browserRedirect: "/",
   name: "",
   version: "1.0.0",
-  dir: "mcp"
+  dir: "mcp",
+  sessions: {
+    enabled: false,
+    maxDuration: 30 * 60 * 1e3
+    // 30 minutes
+  }
 };
 export function getMcpConfig(partial) {
-  return defu(partial, defaultMcpConfig);
+  if (!partial) return { ...defaultMcpConfig };
+  const sessions = partial.sessions ? { ...defaultMcpConfig.sessions, ...partial.sessions } : defaultMcpConfig.sessions;
+  return {
+    enabled: partial.enabled ?? defaultMcpConfig.enabled,
+    route: partial.route ?? defaultMcpConfig.route,
+    browserRedirect: partial.browserRedirect ?? defaultMcpConfig.browserRedirect,
+    name: partial.name ?? defaultMcpConfig.name,
+    version: partial.version ?? defaultMcpConfig.version,
+    dir: partial.dir ?? defaultMcpConfig.dir,
+    sessions
+  };
 }

package/dist/runtime/server/mcp/definitions/cache.d.ts

@@ -1,5 +1,5 @@
 /**
- * Cache duration strings supported by the `ms` package
+ * Cache duration strings (e.g. '1h', '30m', '2 days')
  */
 export type MsCacheDuration = '1s' | '5s' | '10s' | '15s' | '30s' | '45s' | '1m' | '2m' | '5m' | '10m' | '15m' | '30m' | '45m' | '1h' | '2h' | '3h' | '4h' | '6h' | '8h' | '12h' | '24h' | '1d' | '2d' | '3d' | '7d' | '14d' | '30d' | '1w' | '2w' | '4w' | '1 second' | '1 minute' | '1 hour' | '1 day' | '1 week' | '2 seconds' | '5 seconds' | '10 seconds' | '30 seconds' | '2 minutes' | '5 minutes' | '10 minutes' | '15 minutes' | '30 minutes' | '2 hours' | '3 hours' | '6 hours' | '12 hours' | '24 hours' | '2 days' | '3 days' | '7 days' | '14 days' | '30 days' | '2 weeks' | '4 weeks' | (string & Record<never, never>);
 /**

package/dist/runtime/server/mcp/definitions/cache.js

@@ -1,10 +1,41 @@
 import { defineCachedFunction } from "nitropack/runtime";
-import ms from "ms";
+const DURATION_UNITS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1e3,
+  sec: 1e3,
+  second: 1e3,
+  seconds: 1e3,
+  m: 6e4,
+  min: 6e4,
+  minute: 6e4,
+  minutes: 6e4,
+  h: 36e5,
+  hr: 36e5,
+  hour: 36e5,
+  hours: 36e5,
+  d: 864e5,
+  day: 864e5,
+  days: 864e5,
+  w: 6048e5,
+  week: 6048e5,
+  weeks: 6048e5
+};
+function parseDurationToMs(str) {
+  const match = str.trim().match(/^(\d+)\s*([a-z]+)$/i);
+  if (!match) return void 0;
+  const value = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const multiplier = DURATION_UNITS[unit];
+  if (multiplier === void 0) return void 0;
+  return value * multiplier;
+}
 export function parseCacheDuration(duration) {
   if (typeof duration === "number") {
     return duration;
   }
-  const parsed = ms(duration);
+  const parsed = parseDurationToMs(duration);
   if (parsed === void 0) {
     throw new Error(`Invalid cache duration: ${duration}`);
   }

package/dist/runtime/server/mcp/definitions/handlers.d.ts

@@ -29,7 +29,7 @@ import type { McpPromptDefinition } from './prompts.js';
  * }
  * ```
  */
-export type McpMiddleware = (event: H3Event, next: () => Promise<Response | undefined>) => Promise<Response | undefined | void> | Response | undefined | void;
+export type McpMiddleware = (event: H3Event, next: () => Promise<Response>) => Promise<Response | void> | Response | void;
 /**
  * Options for defining a custom MCP handler
  * @see https://mcp-toolkit.nuxt.dev/core-concepts/handlers
@@ -70,9 +70,9 @@ export interface McpHandlerOptions {
      * ```
      */
     middleware?: McpMiddleware;
-    tools?: Array<McpToolDefinition<any, any>>;
-    resources?: McpResourceDefinition[];
-    prompts?: McpPromptDefinition[];
+    tools?: Array<McpToolDefinition<any, any>> | ((event: H3Event) => Array<McpToolDefinition<any, any>> | Promise<Array<McpToolDefinition<any, any>>>);
+    resources?: McpResourceDefinition[] | ((event: H3Event) => McpResourceDefinition[] | Promise<McpResourceDefinition[]>);
+    prompts?: McpPromptDefinition[] | ((event: H3Event) => McpPromptDefinition[] | Promise<McpPromptDefinition[]>);
 }
 export interface McpHandlerDefinition extends Required<Omit<McpHandlerOptions, 'tools' | 'resources' | 'prompts' | 'middleware'>> {
     tools: Array<McpToolDefinition<any, any>>;

package/dist/runtime/server/mcp/definitions/prompts.d.ts

@@ -1,3 +1,4 @@
+import type { H3Event } from 'h3';
 import type { ZodRawShape } from 'zod';
 import type { GetPromptResult, ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
@@ -18,6 +19,12 @@ export interface McpPromptDefinition<Args extends ZodRawShape | undefined = unde
     inputSchema?: Args;
     _meta?: Record<string, unknown>;
     handler: McpPromptCallback<Args>;
+    /**
+     * Guard that controls whether this prompt is registered for a given request.
+     * Receives the H3 event (with `event.context` populated by middleware) and
+     * returns `true` to include the prompt or `false` to hide it.
+     */
+    enabled?: (event: H3Event) => boolean | Promise<boolean>;
 }
 /**
  * Register a prompt from a McpPromptDefinition

package/dist/runtime/server/mcp/definitions/resources.d.ts

@@ -1,3 +1,4 @@
+import type { H3Event } from 'h3';
 import type { McpServer, ResourceTemplate, ReadResourceCallback, ReadResourceTemplateCallback, ResourceMetadata } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpCacheOptions, type McpCache } from './cache.js';
 export type McpResourceCacheOptions = McpCacheOptions<URL>;
@@ -34,6 +35,12 @@ export interface StandardMcpResourceDefinition {
      * @see https://nitro.build/guide/cache#options
      */
     cache?: McpResourceCache;
+    /**
+     * Guard that controls whether this resource is registered for a given request.
+     * Receives the H3 event (with `event.context` populated by middleware) and
+     * returns `true` to include the resource or `false` to hide it.
+     */
+    enabled?: (event: H3Event) => boolean | Promise<boolean>;
 }
 /**
  * Definition of a file-based MCP resource
@@ -61,6 +68,12 @@ export interface FileMcpResourceDefinition {
      * @see https://nitro.build/guide/cache#options
      */
     cache?: McpResourceCache;
+    /**
+     * Guard that controls whether this resource is registered for a given request.
+     * Receives the H3 event (with `event.context` populated by middleware) and
+     * returns `true` to include the resource or `false` to hide it.
+     */
+    enabled?: (event: H3Event) => boolean | Promise<boolean>;
 }
 /**
  * Definition of an MCP resource matching the SDK's registerResource signature

package/dist/runtime/server/mcp/definitions/tools.d.ts

@@ -1,3 +1,4 @@
+import type { H3Event } from 'h3';
 import type { ZodRawShape } from 'zod';
 import type { CallToolResult, ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
@@ -51,6 +52,14 @@ export interface McpToolDefinition<InputSchema extends ZodRawShape | undefined =
      * @see https://nitro.build/guide/cache#options
      */
     cache?: McpToolCache<InputSchema extends ZodRawShape ? ShapeOutput<InputSchema> : undefined>;
+    /**
+     * Guard that controls whether this tool is registered for a given request.
+     * Receives the H3 event (with `event.context` populated by middleware) and
+     * returns `true` to include the tool or `false` to hide it.
+     *
+     * Evaluated after middleware runs, so authentication context is available.
+     */
+    enabled?: (event: H3Event) => boolean | Promise<boolean>;
 }
 /**
  * Register a tool from a McpToolDefinition

package/dist/runtime/server/mcp/definitions/utils.js

@@ -1,4 +1,9 @@
-import { kebabCase, titleCase } from "scule";
+function kebabCase(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+}
+function titleCase(str) {
+  return str.replace(/[-_]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\b\w/g, (c) => c.toUpperCase());
+}
 export function enrichNameTitle(options) {
   const { name, title, _meta, type } = options;
   const filename = _meta?.filename;

package/dist/runtime/server/mcp/handler.js

@@ -27,14 +27,16 @@ export default createMcpHandler((event) => {
   }
   const defaultHandlerDef = defaultHandler;
   if (defaultHandlerDef) {
+    const globalTools = tools;
+    const globalResources = resources;
+    const globalPrompts = prompts;
     return {
       name: defaultHandlerDef.name ?? config.name ?? "MCP Server",
       version: defaultHandlerDef.version ?? config.version,
       browserRedirect: defaultHandlerDef.browserRedirect ?? config.browserRedirect,
-      // Use handler's definitions if specified, otherwise use global definitions
-      tools: defaultHandlerDef.tools ?? tools,
-      resources: defaultHandlerDef.resources ?? resources,
-      prompts: defaultHandlerDef.prompts ?? prompts,
+      tools: defaultHandlerDef.tools ?? globalTools,
+      resources: defaultHandlerDef.resources ?? globalResources,
+      prompts: defaultHandlerDef.prompts ?? globalPrompts,
       middleware: defaultHandlerDef.middleware
     };
   }

package/dist/runtime/server/mcp/loaders/utils.js

@@ -1,5 +1,5 @@
+import { resolve as resolvePath } from "node:path";
 import { getLayerDirectories } from "@nuxt/kit";
-import { resolve as resolvePath } from "pathe";
 import { glob } from "tinyglobby";
 const RESERVED_KEYWORDS = /* @__PURE__ */ new Set([
   "break",

package/dist/runtime/server/mcp/providers/cloudflare.js

@@ -6,7 +6,9 @@ const fallbackCtx = {
   passThroughOnException: () => {
   }
 };
-export default createMcpTransportHandler(async (server, event) => {
+export default createMcpTransportHandler(async (createServer, event) => {
+  const server = createServer();
+  event.context._mcpServer = server;
   const { createMcpHandler } = await import("agents/mcp");
   const handler = createMcpHandler(server, {
     route: ""

package/dist/runtime/server/mcp/providers/node.js

@@ -1,13 +1,87 @@
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { readBody } from "h3";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { toWebRequest, getHeader } from "h3";
+import { useStorage } from "nitropack/runtime";
+import config from "#nuxt-mcp-toolkit/config.mjs";
 import { createMcpTransportHandler } from "./types.js";
-export default createMcpTransportHandler(async (server, event) => {
-  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
-  event.node.res.on("close", () => {
-    transport.close();
-    server.close();
+const sessions = /* @__PURE__ */ new Map();
+let cleanupInterval = null;
+function ensureCleanup(maxDuration) {
+  if (cleanupInterval) return;
+  cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      if (now - session.lastAccessed > maxDuration) {
+        session.transport.close();
+        session.server.close();
+        sessions.delete(id);
+        useStorage(`mcp:sessions:${id}`).clear();
+      }
+    }
+    if (sessions.size === 0 && cleanupInterval) {
+      clearInterval(cleanupInterval);
+      cleanupInterval = null;
+    }
+  }, 6e4);
+}
+export default createMcpTransportHandler(async (createServer, event) => {
+  const sessionsConfig = config.sessions;
+  const sessionsEnabled = sessionsConfig?.enabled ?? false;
+  const request = toWebRequest(event);
+  if (!sessionsEnabled) {
+    const server2 = createServer();
+    event.context._mcpServer = server2;
+    const transport2 = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+    event.node.res.on("close", () => {
+      transport2.close();
+      server2.close();
+    });
+    await server2.connect(transport2);
+    return transport2.handleRequest(request);
+  }
+  const maxDuration = sessionsConfig?.maxDuration ?? 30 * 60 * 1e3;
+  const sessionId = getHeader(event, "mcp-session-id");
+  if (sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return new Response(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32001, message: "Session not found" },
+        id: null
+      }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    session.lastAccessed = Date.now();
+    event.context._mcpServer = session.server;
+    return session.transport.handleRequest(request);
+  }
+  const server = createServer();
+  event.context._mcpServer = server;
+  let sessionStored = false;
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: () => globalThis.crypto.randomUUID(),
+    onsessioninitialized: (id) => {
+      sessionStored = true;
+      sessions.set(id, { server, transport, lastAccessed: Date.now() });
+      ensureCleanup(maxDuration);
+    }
   });
+  transport.onclose = () => {
+    const sid = transport.sessionId;
+    if (sid && sessions.has(sid)) {
+      sessions.delete(sid);
+      useStorage(`mcp:sessions:${sid}`).clear();
+    }
+    server.close();
+  };
   await server.connect(transport);
-  const body = await readBody(event);
-  await transport.handleRequest(event.node.req, event.node.res, body);
+  const response = await transport.handleRequest(request);
+  if (!sessionStored) {
+    event.node.res.on("close", () => {
+      transport.close();
+      server.close();
+    });
+  }
+  return response;
 });

package/dist/runtime/server/mcp/providers/types.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { H3Event } from 'h3';
-export type McpTransportHandler = (server: McpServer, event: H3Event) => Promise<Response | void> | Response | void;
+export type McpTransportHandler = (createServer: () => McpServer, event: H3Event) => Promise<Response>;
 export declare const createMcpTransportHandler: (handler: McpTransportHandler) => McpTransportHandler;

package/dist/runtime/server/mcp/server.d.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface McpServerHelper {
+    /** Register a new tool mid-session. The client is notified automatically. */
+    registerTool: McpServer['registerTool'];
+    /** Register a new prompt mid-session. The client is notified automatically. */
+    registerPrompt: McpServer['registerPrompt'];
+    /** Register a new resource mid-session. The client is notified automatically. */
+    registerResource: McpServer['registerResource'];
+    /** Remove a dynamically registered tool by name. Returns `true` if found. */
+    removeTool(name: string): boolean;
+    /** Remove a dynamically registered prompt by name. Returns `true` if found. */
+    removePrompt(name: string): boolean;
+    /** Remove a dynamically registered resource by name. Returns `true` if found. */
+    removeResource(name: string): boolean;
+    /** The underlying `McpServer` instance for advanced SDK operations. */
+    server: McpServer;
+}
+/**
+ * Returns a helper to mutate the MCP server mid-session.
+ *
+ * Use inside tool, resource, or prompt handlers to register, remove,
+ * or update definitions while a session is active. The SDK automatically
+ * sends `list_changed` notifications to the client.
+ *
+ * Requires `nitro.experimental.asyncContext: true` in your Nuxt config.
+ */
+export declare function useMcpServer(): McpServerHelper;

package/dist/runtime/server/mcp/server.js

@@ -0,0 +1,44 @@
+import { useEvent } from "nitropack/runtime";
+const registrations = /* @__PURE__ */ new WeakMap();
+function getRegistrations(server) {
+  let reg = registrations.get(server);
+  if (!reg) {
+    reg = { tools: /* @__PURE__ */ new Map(), prompts: /* @__PURE__ */ new Map(), resources: /* @__PURE__ */ new Map() };
+    registrations.set(server, reg);
+  }
+  return reg;
+}
+function removeByName(map, name) {
+  const handle = map.get(name);
+  if (!handle) return false;
+  handle.remove();
+  map.delete(name);
+  return true;
+}
+function wrapRegister(server, method, map) {
+  const fn = server[method].bind(server);
+  return (...args) => {
+    const handle = fn(...args);
+    map.set(args[0], handle);
+    return handle;
+  };
+}
+export function useMcpServer() {
+  const event = useEvent();
+  const server = event.context._mcpServer;
+  if (!server) {
+    throw new Error(
+      "No MCP server instance available. Ensure this is called within an MCP tool/resource/prompt handler and `nitro.experimental.asyncContext` is true."
+    );
+  }
+  const reg = getRegistrations(server);
+  return {
+    registerTool: wrapRegister(server, "registerTool", reg.tools),
+    registerPrompt: wrapRegister(server, "registerPrompt", reg.prompts),
+    registerResource: wrapRegister(server, "registerResource", reg.resources),
+    removeTool: (name) => removeByName(reg.tools, name),
+    removePrompt: (name) => removeByName(reg.prompts, name),
+    removeResource: (name) => removeByName(reg.resources, name),
+    server
+  };
+}

package/dist/runtime/server/mcp/session.d.ts

@@ -0,0 +1,12 @@
+import type { Storage } from 'unstorage';
+export interface McpSessionStore<T = Record<string, unknown>> {
+    get<K extends keyof T & string>(key: K): Promise<T[K] | null>;
+    set<K extends keyof T & string>(key: K, value: T[K]): Promise<void>;
+    remove<K extends keyof T & string>(key: K): Promise<void>;
+    has<K extends keyof T & string>(key: K): Promise<boolean>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+    /** Access the underlying unstorage instance */
+    storage: Storage;
+}
+export declare function useMcpSession<T = Record<string, unknown>>(): McpSessionStore<T>;

package/dist/runtime/server/mcp/session.js

@@ -0,0 +1,21 @@
+import { useStorage, useEvent } from "nitropack/runtime";
+import { getHeader } from "h3";
+export function useMcpSession() {
+  const event = useEvent();
+  const sessionId = getHeader(event, "mcp-session-id");
+  if (!sessionId) {
+    throw new Error(
+      "No active MCP session. Ensure `mcp.sessions` is enabled and `nitro.experimental.asyncContext` is true."
+    );
+  }
+  const storage = useStorage(`mcp:sessions:${sessionId}`);
+  return {
+    get: (key) => storage.getItem(key),
+    set: (key, value) => storage.setItem(key, value),
+    remove: (key) => storage.removeItem(key),
+    has: (key) => storage.hasItem(key),
+    keys: () => storage.getKeys(),
+    clear: () => storage.clear(),
+    storage
+  };
+}

package/dist/runtime/server/mcp/utils.d.ts

@@ -1,17 +1,29 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { H3Event } from 'h3';
-import type { McpToolDefinition, McpResourceDefinition, McpPromptDefinition, McpMiddleware } from './definitions/index.js';
+import type { McpMiddleware } from './definitions/handlers.js';
+import type { McpPromptDefinition } from './definitions/prompts.js';
+import type { McpResourceDefinition } from './definitions/resources.js';
+import type { McpToolDefinition } from './definitions/tools.js';
 export type { McpTransportHandler } from './providers/types.js';
 export { createMcpTransportHandler } from './providers/types.js';
+type MaybeDynamic<T> = T | ((event: H3Event) => T | Promise<T>);
+type MaybeDynamicTools = MaybeDynamic<Array<McpToolDefinition<any, any>>>;
 export interface ResolvedMcpConfig {
     name: string;
     version: string;
     browserRedirect: string;
-    tools?: McpToolDefinition[];
-    resources?: McpResourceDefinition[];
-    prompts?: McpPromptDefinition[];
+    tools?: MaybeDynamicTools;
+    resources?: MaybeDynamic<McpResourceDefinition[]>;
+    prompts?: MaybeDynamic<McpPromptDefinition[]>;
     middleware?: McpMiddleware;
 }
+interface StaticMcpConfig {
+    name: string;
+    version: string;
+    tools: McpToolDefinition[];
+    resources: McpResourceDefinition[];
+    prompts: McpPromptDefinition[];
+}
 export type CreateMcpHandlerConfig = ResolvedMcpConfig | ((event: H3Event) => ResolvedMcpConfig);
-export declare function createMcpServer(config: ResolvedMcpConfig): McpServer;
+export declare function createMcpServer(config: StaticMcpConfig): McpServer;
 export declare function createMcpHandler(config: CreateMcpHandlerConfig): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;

package/dist/runtime/server/mcp/utils.js

@@ -1,25 +1,60 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { sendRedirect, getHeader, defineEventHandler } from "h3";
-import { registerToolFromDefinition, registerResourceFromDefinition, registerPromptFromDefinition } from "./definitions/index.js";
+import { registerPromptFromDefinition } from "./definitions/prompts.js";
+import { registerResourceFromDefinition } from "./definitions/resources.js";
+import { registerToolFromDefinition } from "./definitions/tools.js";
 import handleMcpRequest from "#nuxt-mcp-toolkit/transport.mjs";
 export { createMcpTransportHandler } from "./providers/types.js";
 function resolveConfig(config, event) {
   return typeof config === "function" ? config(event) : config;
 }
+async function filterByEnabled(definitions, event) {
+  const results = await Promise.all(
+    definitions.map(async (def) => {
+      if (!def.enabled) return true;
+      return def.enabled(event);
+    })
+  );
+  return definitions.filter((_, i) => results[i]);
+}
+async function resolveDynamicDefinitions(config, event) {
+  const tools = typeof config.tools === "function" ? await config.tools(event) : config.tools || [];
+  const resources = typeof config.resources === "function" ? await config.resources(event) : config.resources || [];
+  const prompts = typeof config.prompts === "function" ? await config.prompts(event) : config.prompts || [];
+  return {
+    name: config.name,
+    version: config.version,
+    tools: await filterByEnabled(tools, event),
+    resources: await filterByEnabled(resources, event),
+    prompts: await filterByEnabled(prompts, event)
+  };
+}
+function registerEmptyDefinitionFallbacks(server, config) {
+  if (!config.tools.length) {
+    server.registerTool("__init__", {}, async () => ({ content: [] })).remove();
+  }
+  if (!config.resources.length) {
+    server.registerResource("__init__", "noop://init", {}, async () => ({ contents: [] })).remove();
+  }
+  if (!config.prompts.length) {
+    server.registerPrompt("__init__", {}, async () => ({ messages: [] })).remove();
+  }
+}
 export function createMcpServer(config) {
   const server = new McpServer({
     name: config.name,
     version: config.version
   });
-  for (const tool of config.tools || []) {
+  for (const tool of config.tools) {
     registerToolFromDefinition(server, tool);
   }
-  for (const resource of config.resources || []) {
+  for (const resource of config.resources) {
     registerResourceFromDefinition(server, resource);
   }
-  for (const prompt of config.prompts || []) {
+  for (const prompt of config.prompts) {
     registerPromptFromDefinition(server, prompt);
   }
+  registerEmptyDefinitionFallbacks(server, config);
   return server;
 }
 export function createMcpHandler(config) {
@@ -29,8 +64,8 @@ export function createMcpHandler(config) {
       return sendRedirect(event, resolvedConfig.browserRedirect);
     }
     const handler = async () => {
-      const server = createMcpServer(resolvedConfig);
-      return handleMcpRequest(server, event);
+      const staticConfig = await resolveDynamicDefinitions(resolvedConfig, event);
+      return handleMcpRequest(() => createMcpServer(staticConfig), event);
     };
     if (resolvedConfig.middleware) {
       let nextCalled = false;

package/dist/runtime/server/types/hooks.d.ts

@@ -3,6 +3,10 @@ declare module '@nuxt/schema' {
         /**
          * Add additional directories to scan for MCP definition files (tools, resources, prompts, handlers).
          * @param paths - Object containing arrays of directory paths for each definition type.
+         * @param paths.tools - Array of directory paths to scan for tool definitions.
+         * @param paths.resources - Array of directory paths to scan for resource definitions.
+         * @param paths.prompts - Array of directory paths to scan for prompt definitions.
+         * @param paths.handlers - Array of directory paths to scan for handler definitions.
          * @returns void | Promise<void>
          */
         'mcp:definitions:paths': (paths: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Create MCP servers directly in your Nuxt application. Define tools, resources, and prompts with a simple and intuitive API.",
   "repository": {
     "type": "git",
@@ -39,20 +39,19 @@
     "dist"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@nuxt/kit": "^4.3.1",
-    "defu": "^6.1.4",
-    "ms": "^2.1.3",
-    "pathe": "^2.0.3",
-    "satori": "^0.19.2",
-    "scule": "^1.3.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@nuxt/kit": "^4.4.2",
     "tinyglobby": "^0.2.15"
   },
   "peerDependencies": {
+    "h3": "^1.15.6",
     "zod": "^4.1.13",
-    "agents": ">=0.4.1"
+    "agents": ">=0.7.6"
   },
   "peerDependenciesMeta": {
+    "h3": {
+      "optional": false
+    },
     "zod": {
       "optional": false
     },
@@ -61,18 +60,18 @@
     }
   },
   "devDependencies": {
-    "@nuxt/devtools": "^3.2.1",
-    "@nuxt/eslint-config": "^1.15.1",
+    "@nuxt/devtools": "^3.2.3",
+    "@nuxt/eslint-config": "^1.15.2",
     "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/schema": "^4.3.1",
+    "@nuxt/schema": "^4.4.2",
     "@nuxt/test-utils": "^4.0.0",
     "@types/node": "latest",
     "changelogen": "^0.6.2",
-    "eslint": "^9.39.2",
-    "nuxt": "^4.3.1",
+    "eslint": "^9.39.4",
+    "nuxt": "^4.4.2",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.18",
-    "vue-tsc": "^3.2.4"
+    "vitest": "^4.1.0",
+    "vue-tsc": "^3.2.5"
   },
   "publishConfig": {
     "access": "public"