# Introduction

## What is Model Context Protocol?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io){rel=""nofollow""} is an open protocol that enables AI assistants to securely access external data sources and tools. It provides a standardized way for AI applications to:

- **Access Tools**: Execute functions and operations
- **Read Resources**: Access files, databases, APIs, and other data sources
- **Use Prompts**: Leverage predefined prompt templates

MCP servers act as bridges between AI assistants and external systems, enabling them to interact with your application's data and functionality in a secure, controlled manner.

## What is Nuxt MCP Toolkit?

The Nuxt MCP Toolkit makes it incredibly easy to create MCP servers directly in your Nuxt application. Instead of building a separate MCP server, you can define tools, resources, and prompts right alongside your Nuxt application code.

### Key Benefits

::card-group
  :::card{icon="i-lucide-zap" title="Zero Configuration"}
  Automatic discovery of definitions. Just create files in the right directories and they're automatically registered.
  :::

  :::card{icon="i-lucide-type" title="TypeScript First"}
  Full TypeScript support with auto-imports and complete type safety. All helpers are available globally in your server files.
  :::

  :::card{icon="i-lucide-code" title="Simple API"}
  Intuitive API that matches the MCP SDK structure, making it easy to migrate existing code or learn from examples.
  :::

  :::card{icon="i-lucide-layers" title="Flexible Architecture"}
  Support for multiple MCP handlers in a single application, custom paths, and hooks for advanced use cases.
  :::
::

## How It Works

The module automatically:

1. **Scans** your `server/mcp/` directory (or custom path) for definitions
2. **Discovers** tools, resources, and prompts from your files
3. **Registers** them with the MCP server
4. **Exposes** an HTTP endpoint for MCP clients to connect

```text
server/
└── mcp/
    ├── tools/
    │   ├── echo.ts
    │   └── calculator.ts
    ├── resources/
    │   ├── readme.ts
    │   └── files.ts
    └── prompts/
        ├── greeting.ts
        └── summarize.ts
```

## Core Concepts

### Tools

Tools are functions that AI assistants can call. They accept input parameters (validated with Zod) and return results.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'calculate-bmi',
  inputSchema: {
    weightKg: z.number(),
    heightM: z.number(),
  },
  handler: async ({ weightKg, heightM }) => {
    const bmi = weightKg / (heightM * heightM)
    return `BMI: ${bmi}`
  },
})
```

### Resources

Resources provide access to data via URIs. They can be static files or dynamic data sources.

```typescript
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'readme',
  uri: 'file:///README.md',
  handler: async (uri: URL) => {
    const content = await readFile(uri.pathname, 'utf-8')
    return {
      contents: [{ uri: uri.toString(), text: content }],
    }
  },
})
```

### Prompts

Prompts are reusable message templates that can include dynamic arguments.

```typescript
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'greeting',
  inputSchema: {
    name: z.string(),
  },
  handler: async ({ name }) => {
    return {
      messages: [{
        role: 'user',
        content: { type: 'text', text: `Hello, ${name}!` },
      }],
    }
  },
})
```

### Apps

MCP Apps are interactive UI widgets that hosts like Cursor and ChatGPT render inline. Author them as Vue Single-File Components in `app/mcp/` — the toolkit bundles them and serves them as MCP UI resources.

```vue [app/mcp/color-picker.vue]
<script setup lang="ts">
import { z } from 'zod'

defineMcpApp({
  description: 'Pick a colour and preview a palette.',
  inputSchema: { base: z.string().describe('Hex colour, e.g. #2563eb') },
  handler: async ({ base }) => ({ structuredContent: await $fetch('/api/palette', { query: { base } }) }),
})

const { data } = useMcpApp()
</script>

<template>
  <ul v-if="data" class="swatches">
    <li v-for="s in data.swatches" :key="s.hex" :style="{ background: s.hex }">{{ s.name }}</li>
  </ul>
</template>
```

## Next Steps

Ready to get started? Check out:

- [Installation Guide](https://mcp-toolkit.nuxt.dev/getting-started/installation) - Set up the module in your project
- [Configuration](https://mcp-toolkit.nuxt.dev/getting-started/configuration) - Configure the module
- [Tools Guide](https://mcp-toolkit.nuxt.dev/tools/overview) - Create your first MCP tool
- [Apps Guide](https://mcp-toolkit.nuxt.dev/apps/overview) - Build interactive UI widgets for AI hosts


# Install Nuxt MCP Toolkit

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Set up an MCP server in a Nuxt app
icon: i-lucide-download
---
Set up an MCP server in my Nuxt app using @nuxtjs/mcp-toolkit.

- Auto install the module using `npx nuxt add mcp`
- Create the server/mcp/ directory with tools/, resources/, and prompts/ subdirectories
- defineMcpTool, defineMcpResource, defineMcpPrompt, and defineMcpHandler are auto-imported
- Create a test tool in server/mcp/tools/test.ts using defineMcpTool with a Zod inputSchema
- Start the dev server and verify the MCP endpoint at <http://localhost:3000/mcp>{rel=""nofollow""}
- Connect your IDE (Cursor or VS Code) to <http://localhost:3000/mcp>{rel=""nofollow""}

Docs: <https://mcp-toolkit.nuxt.dev/getting-started/installation>{rel=""nofollow""}
::

## Try the Documentation MCP Server

Before installing the module, you can try connecting to this documentation's MCP server to explore the available tools and prompts:

:install-button{name="nuxt-mcp-toolkit-docs" url="https://mcp-toolkit.nuxt.dev/mcp"}

This will give you access to prompts like `setup-mcp-server`, `create-tool`, `create-resource`, and `troubleshoot` to help you get started.

## Prerequisites

- Nuxt 3.x or 4.x
- Node.js 18.x or higher
- A package manager (npm, pnpm, yarn, or bun)

If you enable Code Mode, that feature specifically requires Node.js `>=18.16.0`.

## Installation

::steps
### Install the module

You can install the module automatically or manually.

#### Automatic Installation

Use the `nuxt` command to install the module and add it to your configuration automatically:

```bash
npx nuxt add mcp
```

#### Manual Installation

Install `@nuxtjs/mcp-toolkit` and its peer dependency `zod`:

  :::code-group
  ```bash [pnpm]
  pnpm add @nuxtjs/mcp-toolkit zod
  ```

  ```bash [npm]
  npm install @nuxtjs/mcp-toolkit zod
  ```

  ```bash [yarn]
  yarn add @nuxtjs/mcp-toolkit zod
  ```

  ```bash [bun]
  bun add @nuxtjs/mcp-toolkit zod
  ```
  :::

### Add to Nuxt config

Add the module to your `nuxt.config.ts`:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
})
```

### Configure the module (optional)

The module works with sensible defaults, but you can customize it:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'My MCP Server',
    route: '/mcp', // Default route for the MCP server
    dir: 'mcp', // Base directory for MCP definitions (relative to server/)
  },
})
```
::

## Verify Installation

After installation, you can verify everything is working by:

1. **Checking the server route**: Start your Nuxt dev server and visit `http://localhost:3000/mcp` (or your custom route). You should be redirected to your configured `browserRedirect` URL.
2. **Creating a test tool**: Create a simple tool to test:

```typescript [server/mcp/tools/test.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'test',
  description: 'A simple test tool',
  inputSchema: {
    message: z.string(),
  },
  handler: async ({ message }) => `Test successful: ${message}`,
})
```

3. **Checking auto-imports**: The `defineMcpTool`, `defineMcpResource`, `defineMcpPrompt`, and `defineMcpHandler` functions should be auto-imported in your server files.

## Project Structure

After installation, your project structure should look like this:

```text
your-project/
├── server/
│   └── mcp/
│       ├── tools/
│       │   └── echo.ts          # Your tool definitions
│       ├── resources/
│       │   └── readme.ts       # Your resource definitions
│       └── prompts/
│           └── greeting.ts     # Your prompt definitions
├── nuxt.config.ts
└── package.json
```

## Connect Your IDE

Once your Nuxt app is running, connect your AI assistant to the MCP server:

:install-button{ide="cursor" name="local-mcp" url="http://localhost:3000/mcp"}

:install-button{ide="vscode" name="local-mcp" url="http://localhost:3000/mcp"}

For manual configuration, the [add-mcp](https://npmx.dev/package/add-mcp){rel="&#x22;nofollow&#x22;"} CLI, and install buttons for your own documentation, see the [Connection](https://mcp-toolkit.nuxt.dev/getting-started/connection) guide.

## Next Steps

Now that you have the module installed:

- [Configuration](https://mcp-toolkit.nuxt.dev/getting-started/configuration) - Learn about all configuration options
- [Connection](https://mcp-toolkit.nuxt.dev/getting-started/connection) - Connect AI assistants to your MCP server and add install buttons to your documentation
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Create your first tool


# Configure the module

## Basic Configuration

Add the module to your `nuxt.config.ts`:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'My MCP Server',
  },
})
```

The module works with sensible defaults, so minimal configuration is required.

## Configuration Options

All available configuration options:

::field-group
  :::field{name="enabled" type="boolean"}
  Default: `true`

  Enable or disable the MCP server.
  :::

  :::field{name="route" type="string"}
  Default: `'/mcp'`

  The HTTP route where the MCP server will be accessible.
  :::

  :::field{name="browserRedirect" type="string"}
  Default: `'/'`

  URL to redirect browsers when they access the MCP endpoint.
  :::

  :::field{name="name" type="string"}
  Default: `''`

  The name of your MCP server (used in the MCP protocol handshake).
  :::

  :::field{name="version" type="string"}
  Default: `'1.0.0'`

  The version of your MCP server (semantic versioning).
  :::

  :::field{name="description" type="string"}
  Optional. A human-readable description of the server, sent as part of 

  `serverInfo`

   during initialization. Clients display it in their UI (server lists, tooltips, install prompts).
  :::

  :::field{name="instructions" type="string"}
  Optional. Operational instructions injected by clients into the model's system prompt. Use this to guide LLMs on workflows, tool relationships, or constraints — not to identify the server (use `description` for that).

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    mcp: {
      description: 'Read and update todos for the current user.',
      instructions: 'Always call list-todos before create-todo. Group results by status.',
    },
  })
  ```

  See the [MCP lifecycle spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization){rel=""nofollow""}.
  :::

  :::field{name="icons" type="McpIcon[]"}
  Optional. Icons for the server, displayed by clients in their UI. Each entry needs `src` and `mimeType`, with optional `sizes` and `theme`:

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    mcp: {
      icons: [
        { src: 'https://example.com/icon-light.png', mimeType: 'image/png', sizes: ['64x64'], theme: 'light' },
        { src: 'https://example.com/icon-dark.png', mimeType: 'image/png', sizes: ['64x64'], theme: 'dark' },
      ],
    },
  })
  ```
  :::

  :::field{name="dir" type="string"}
  Default: `'mcp'`

  Base directory for MCP definitions (relative to `server/`). The module expects:

  - `{dir}/tools/` - Tool definitions
  - `{dir}/resources/` - Resource definitions
  - `{dir}/prompts/` - Prompt definitions
  - `{dir}/handlers/<name>/` - Optional named handler folders ([organization](https://mcp-toolkit.nuxt.dev/handlers/organization))
  :::

  :::field{name="appsDir" type="string"}
  Default: `'mcp'`

  Base directory for [MCP Apps](https://mcp-toolkit.nuxt.dev/apps/overview) `.vue` files (relative to Nuxt's `app/` directory). Scanned across layers. Defaults to `app/mcp/`. The MCP Apps pipeline only runs when this directory exists.
  :::

  :::field{name="defaultHandlerStrategy" type="'orphans' | 'all'"}
  Default: `'orphans'`

  Controls which auto-discovered definitions land on the default `/mcp` route when [named handlers](https://mcp-toolkit.nuxt.dev/handlers/organization) exist:

  - `'orphans'` — only definitions not attached to any named handler (no folder attribution). When no folder handler exists, every definition is an orphan, so this naturally falls back to "expose everything" — zero-effort back-compat.
  - `'all'` — every discovered definition, including those attributed to named handlers. Useful when you want a "kitchen sink" route in addition to specialized ones.
  :::

  :::field{name="autoImports" type="boolean"}
  Default: `true`

  Auto-import MCP helpers (`defineMcpTool`, `defineMcpResource`, `defineMcpHandler`, `defineMcpApp`, …), types (`McpRequestExtra`, …), composables (`useMcpSession`, `useMcpServer`, `useMcpLogger`, `useMcpElicitation`), and the `InstallButton` component. Set to `false` to disable all auto-imports and require explicit imports from `@nuxtjs/mcp-toolkit/server`.
  :::

  :::field{name="logging" type="boolean"}
  Optional. Server-side observability for every MCP request via [evlog](https://evlog.dev){rel=""nofollow""}, an **optional peer dependency**.

  - `undefined` (default) — auto-detect: on if the `evlog/nuxt` module is registered, off otherwise.
  - `true` — assert `evlog/nuxt` is registered; throw at build otherwise.
  - `false` — opt out entirely.

  When active, every MCP request emits a wide event tagged with `mcp.transport`, `mcp.method`, `mcp.tool`, `mcp.session_id`, `mcp.request_id`, etc. Use [`useMcpLogger()`](https://mcp-toolkit.nuxt.dev/advanced/logging) to push extra fields and discrete events.
  :::

  :::field{name="sessions" type="boolean | object"}
  Default: `false`

  Enable [MCP session management](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management){rel=""nofollow""} (stateful transport). When enabled, the server assigns session IDs via the `MCP-Session-Id` header and maintains state across requests, enabling SSE streaming, server-to-client notifications, and session continuity.

  Pass `true` for defaults or an object with:

  - `enabled` - Enable or disable sessions
  - `maxDuration` - Session timeout in milliseconds (default: `1800000` / 30 minutes)
  - `maxSessions` - Maximum concurrent sessions before new session creation returns `503` (default: `1000`). Enforced on the **Node** Nitro server only; Cloudflare Workers use the `agents/mcp` path in this module, which does not apply this cap.
  :::

  :::field{name="security" type="object"}
  Optional. Hardens [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#security){rel=""nofollow""} requests.

  - `allowedOrigins` — `undefined` (default): allow requests with no `Origin` header (typical for same-origin and CLI); otherwise require `Origin` to match the server origin (scheme + host + port). Use the literal `'*'` in config to disable Origin checks (explicit opt-out). `string[]` — allow only listed origins (each entry is normalized to an origin URL).

  Cross-site browser clients must send an allowed `Origin` or receive **403**.
  :::
::

## Common Configuration Scenarios

### Custom Route

Change the MCP endpoint route:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    route: '/api/mcp', // Custom route
  },
})
```

### Custom Directory

Use a different directory for MCP definitions:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    dir: 'my-mcp', // Look in server/my-mcp/ instead of server/mcp/
  },
})
```

This will look for definitions in:

- `server/my-mcp/tools/`
- `server/my-mcp/resources/`
- `server/my-mcp/prompts/`

### Browser Redirect

Redirect browsers to a custom URL:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    browserRedirect: '/docs/mcp', // Redirect browsers to documentation
  },
})
```

### Streamable HTTP security (`allowedOrigins`)

When browsers call your MCP endpoint from another site, they send an `Origin` header. By default the module requires that origin to match your app. Allow a SPA on another host (or disable checks only in controlled environments):

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    security: {
      allowedOrigins: ['https://my-app.vercel.app'],
      // allowedOrigins: '*' // explicit opt-out — use with care
    },
  },
})
```

### Session Management

Enable stateful sessions to support SSE streaming, server-to-client notifications, and per-session state:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    sessions: true,
  },
})
```

With sessions enabled, the server assigns an `MCP-Session-Id` during initialization. Clients include this ID in subsequent requests, allowing the server to maintain state across the session lifecycle.

::callout{color="info" icon="i-lucide-info"}
See the 

[Sessions guide](https://mcp-toolkit.nuxt.dev/advanced/sessions)

 for the full 

`useMcpSession()`

 API, use cases, and examples.
::

### Disable Auto-Imports

If you prefer explicit imports over auto-imports:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    autoImports: false,
  },
})
```

With auto-imports disabled, import helpers and types explicitly:

```typescript [server/mcp/tools/echo.ts]
import { z } from 'zod'
import { defineMcpTool, type McpRequestExtra } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Echo back a message',
  inputSchema: { message: z.string() },
  handler: async ({ message }, extra: McpRequestExtra) => {
    return `Echo: ${message}`
  },
})
```

### Disable the Module

Temporarily disable the MCP server:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    enabled: false, // Disable the MCP server
  },
})
```

## Runtime Configuration

Access configuration at runtime:

```typescript [server/api/config.ts]
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event).mcp

  return {
    name: config.name,
    version: config.version,
    route: config.route,
  }
})
```

## Next Steps

- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Learn how to create tools
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Create resources
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Create prompts
- [Sessions](https://mcp-toolkit.nuxt.dev/advanced/sessions) - Per-session state with `useMcpSession()`
- [Custom Paths](https://mcp-toolkit.nuxt.dev/advanced/custom-paths) - Advanced path configuration


# Debug with the MCP Inspector

The module includes a built-in integration with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector){rel="&#x22;nofollow&#x22;"}, a visual debugging tool that allows you to interactively test and debug your MCP server directly from Nuxt DevTools.

::u-color-mode-image
---
alt: MCP Inspector preview
class: w-full rounded-lg my-6 grayscale
dark: /mcp-devtools-dark.png
light: /mcp-devtools-light.png
---
::

## How to use it

1. **Enable DevTools** - Make sure DevTools are enabled in your `nuxt.config.ts`:
   ```typescript \[nuxt.config.ts]
   export default defineNuxtConfig({
     modules: ['@nuxtjs/mcp-toolkit'],
     devtools: { enabled: true },
   })
   ```
2. **Launch** - Open Nuxt DevTools and navigate to the **MCP Inspector** tab in the **Server** section, then click **Launch Inspector**.
3. **Test** - Use the inspector to browse tools, resources, and prompts, test them with custom parameters, and view request/response history.

The inspector automatically connects to your MCP server endpoint with the correct configuration - no setup needed.

## Why use it?

The inspector provides a visual interface to:

- Browse all available tools, resources, and prompts
- Test tools with custom parameters and see responses
- View request/response history for debugging
- Debug connection issues and errors

It's the easiest way to test and validate your MCP server during development.

## Configuration

By default, the inspector uses ports `6274` (UI) and `6277` (proxy). To customize them:

::code-group
```bash [pnpm]
CLIENT_PORT=8080 SERVER_PORT=9000 pnpm dev
```

```bash [npm]
CLIENT_PORT=8080 SERVER_PORT=9000 npm run dev
```

```bash [yarn]
CLIENT_PORT=8080 SERVER_PORT=9000 yarn dev
```

```bash [bun]
CLIENT_PORT=8080 SERVER_PORT=9000 bun dev
```
::

For advanced configuration options, see the [MCP Inspector documentation](https://github.com/modelcontextprotocol/inspector){rel="&#x22;nofollow&#x22;"}.


# Connect MCP clients

## Overview

Once your MCP server is running, you can connect AI assistants like Cursor, VS Code, and ChatGPT to use your tools, resources, and prompts.

The module also provides components and routes to help your users install your MCP server in one click.

## add-mcp

The [add-mcp](https://npmx.dev/package/add-mcp){rel="&#x22;nofollow&#x22;"} CLI can register a **remote** (streamable HTTP) MCP server with Cursor, Claude Code, VS Code, Codex, and [several other coding agents](https://npmx.dev/package/add-mcp){rel="&#x22;nofollow&#x22;"} in one step.

Use the URL that matches where the app runs: **`http://…` for local dev*&#x2A;, **`https://…` in production** (public MCP endpoints should use HTTPS). If you changed `mcp.route` in `nuxt.config`, append that path instead of `/mcp`.

::code-group
```bash [Local dev]
npx add-mcp http://localhost:3000/mcp
```

```bash [Production]
npx add-mcp https://your-app.example.com/mcp
```
::

Run the command from any directory; it updates agent config files (e.g. project `.cursor/mcp.json`). Options such as `-a cursor`, `-y`, or `--header` for authenticated endpoints are described in the [add-mcp package docs](https://npmx.dev/package/add-mcp){rel="&#x22;nofollow&#x22;"}.

## Share your MCP with users (production)

When your Nuxt app is deployed, you give **your users** a stable MCP URL. They will plug the same shape of URL into their assistant as for localhost—only the host and scheme change.

### What to publish

| You share           | Example                                                         |
| ------------------- | --------------------------------------------------------------- |
| Public MCP endpoint | `https://your-product.com/mcp`                                  |
| Custom route        | `https://your-product.com/api/mcp` if `mcp.route` is `/api/mcp` |

Prefer **HTTPS** on the public internet. Your hosting provider’s assigned URL (e.g. `https://my-app.vercel.app/mcp`) is fine until you add a custom domain.

### One-liner for users ([add-mcp](https://npmx.dev/package/add-mcp){rel="&#x22;nofollow&#x22;"})

Document this in your README or docs so people can register your server quickly:

```bash
npx add-mcp https://your-product.com/mcp
```

If your MCP is behind auth, document the required headers and point people to `add-mcp --header 'Authorization: Bearer …'` (or your provider’s pattern).

### Buttons and badges for docs / README

Give non-CLI users a single click:

- **[`InstallButton`](https://mcp-toolkit.nuxt.dev/#installbutton-component)** in Vue or MDC — set `url` to your **production** MCP URL (see examples with `https://my-app.com/mcp` below).
- **[README badges](https://mcp-toolkit.nuxt.dev/#readme-badge)** — Markdown badges that open the IDE installer and work in GitHub or any site.

Example for your landing or documentation:

:install-button{name="your-product-mcp" url="https://your-product.com/mcp"}

:install-button{ide="vscode" name="your-product-mcp" url="https://your-product.com/mcp"}

### Manual config you can copy for users

Same JSON as in the [IDE sections below](https://mcp-toolkit.nuxt.dev/#connect-your-ide), but with your live URL:

```json
{
  "url": "https://your-product.com/mcp"
}
```

Cursor and VS Code expect this inside their respective `mcpServers` / `servers` shapes — mirror the full examples under [Cursor](https://mcp-toolkit.nuxt.dev/#cursor) and [VS Code](https://mcp-toolkit.nuxt.dev/#vs-code) and replace the localhost URL.

## Connect Your IDE

The steps below use **localhost** while you develop. To publish instructions for your audience, reuse the same patterns with your **production** `https://…` URL — see [Share your MCP with users (production)](https://mcp-toolkit.nuxt.dev/#share-your-mcp-with-users-production).

### Cursor

Click the button below to add your local MCP server to Cursor:

:install-button{ide="cursor" name="local-mcp" url="http://localhost:3000/mcp"}

Or manually add it to your Cursor settings (`~/.cursor/mcp.json`):

```json [~/.cursor/mcp.json]
{
  "mcpServers": {
    "my-nuxt-app": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

### VS Code

Click the button below to add your local MCP server to VS Code:

:install-button{ide="vscode" name="local-mcp" url="http://localhost:3000/mcp"}

Or manually add the server to your VS Code MCP configuration (`.vscode/mcp.json`):

```json [.vscode/mcp.json]
{
  "servers": {
    "my-nuxt-app": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

::callout{color="info" icon="i-lucide-info"}
Replace 

`my-nuxt-app`

 with your project name and update the URL if you're using a custom route or port.
::

## InstallButton Component

The module provides an `InstallButton` component that you can use in your documentation to let users install your MCP server in one click.

### Supported IDEs

| IDE     | Value    | Status    |
| ------- | -------- | --------- |
| Cursor  | `cursor` | Supported |
| VS Code | `vscode` | Supported |

### In Vue Templates

```vue
<template>
  <!-- Cursor (default) -->
  <InstallButton url="https://my-app.com/mcp" />

  <!-- VS Code -->
  <InstallButton url="https://my-app.com/mcp" ide="vscode" />

  <!-- Custom label -->
  <InstallButton url="https://my-app.com/mcp" label="Add to Cursor" />
</template>
```

### In Markdown (MDC Syntax)

If you're using [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, use the MDC syntax:

```md
<!-- Cursor (default) -->
::install-button
---
url: "https://my-app.com/mcp"
---
::

<!-- VS Code -->
::install-button
---
url: "https://my-app.com/mcp"
ide: "vscode"
---
::

<!-- With custom label -->
::install-button
---
url: "https://my-app.com/mcp"
label: "Add to Cursor"
---
::
```

### Props Reference

| Prop       | Type                  | Default        | Description                    |
| ---------- | --------------------- | -------------- | ------------------------------ |
| `url`      | `string`              | required       | URL of the MCP server endpoint |
| `ide`      | `'cursor' | 'vscode'` | `'cursor'`     | Target IDE                     |
| `label`    | `string`              | Auto-generated | Button label                   |
| `showIcon` | `boolean`             | `true`         | Show the IDE icon              |

### Customization

The component uses CSS classes that you can override:

```css
/* Override default styles */
.mcp-install-button {
  background-color: #your-brand-color;
  border-radius: 9999px;
}
```

Or use the slot for completely custom content:

```vue
<InstallButton url="https://my-app.com/mcp">
  Add to Cursor
</InstallButton>
```

## README Badge

For README files and documentation outside of Vue/Nuxt, the module provides server routes to generate badges.

### Badge Routes

The module exposes two routes:

| Route            | Description                            |
| ---------------- | -------------------------------------- |
| `/mcp/deeplink`  | Redirects to the IDE deeplink          |
| `/mcp/badge.svg` | Returns a customizable SVG badge image |

### Basic Usage

Add this to your README:

```md
[![Install in Cursor](https://your-app.com/mcp/badge.svg)](https://your-app.com/mcp/deeplink)
```

This will display a badge that, when clicked, opens the IDE and installs your MCP server.

### VS Code Badge

```md
[![Install in VS Code](https://your-app.com/mcp/badge.svg?ide=vscode)](https://your-app.com/mcp/deeplink?ide=vscode)
```

### Both IDEs

```md
[![Install in Cursor](https://your-app.com/mcp/badge.svg)](https://your-app.com/mcp/deeplink)
[![Install in VS Code](https://your-app.com/mcp/badge.svg?ide=vscode)](https://your-app.com/mcp/deeplink?ide=vscode)
```

### Customization Options

| Parameter     | Default        | Description                       |
| ------------- | -------------- | --------------------------------- |
| `ide`         | `cursor`       | Target IDE (`cursor` or `vscode`) |
| `label`       | Auto-generated | Badge text                        |
| `color`       | `171717`       | Background color (hex without #)  |
| `textColor`   | `ffffff`       | Text color (hex without #)        |
| `borderColor` | `404040`       | Border color (hex without #)      |
| `icon`        | `true`         | Show IDE icon (`true` or `false`) |

### Custom Badge Examples

**Custom label:**

```md
[![Add to Cursor](https://your-app.com/mcp/badge.svg?label=Add%20to%20Cursor)](https://your-app.com/mcp/deeplink)
```

**Custom colors:**

```md
[![Install](https://your-app.com/mcp/badge.svg?color=0ea5e9&borderColor=0284c7)](https://your-app.com/mcp/deeplink)
```

**Without icon:**

```md
[![Install](https://your-app.com/mcp/badge.svg?icon=false)](https://your-app.com/mcp/deeplink)
```

::callout{color="info" icon="i-lucide-info"}
Replace 

`https://your-app.com`

 with your actual domain. The badge route uses the server name from your 

`mcp.name`

 config.
::

## Deeplink Formats

For reference, here are the deeplink formats used by each IDE:

### Cursor

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=SERVER_NAME&config=BASE64_CONFIG
```

The config is Base64-encoded JSON containing `{ type: 'http', url: 'MCP_URL' }`.

### VS Code

```text
vscode:mcp/install?URL_ENCODED_JSON
```

The config is URL-encoded JSON containing `{ name: 'SERVER_NAME', type: 'http', url: 'MCP_URL' }`.

## Next Steps

- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Create your first tool
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Expose data to AI assistants
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Create reusable message templates


# Agent Skills

Nuxt MCP Toolkit includes agent skills that help AI assistants build, review, and troubleshoot MCP servers in your Nuxt application.

This documentation site is built with [Docus](https://docus.dev){rel="&#x22;nofollow&#x22;"}, which publishes skills under [`/.well-known/skills/`](https://mcp-toolkit.nuxt.dev/.well-known/skills/index.json){rel="&#x22;nofollow&#x22;"} following the [Agent Skills discovery](https://docus.dev/en/ai/skills){rel="&#x22;nofollow&#x22;"} convention. That lets the [`skills` CLI](https://agentskills.io){rel="&#x22;nofollow&#x22;"} install them from the production URL below.

## What are Agent Skills?

[Agent Skills](https://agentskills.io/){rel="&#x22;nofollow&#x22;"} is an open specification for packaging AI assistant capabilities. Skills provide:

- **Domain knowledge**: Best practices for MCP tools, resources, and prompts
- **Guided development**: Step-by-step help creating and configuring MCP servers
- **Code review**: Identify anti-patterns and suggest improvements
- **Troubleshooting**: Diagnose common issues with auto-imports, endpoints, and validation

## Available Skills

| Skill               | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `skills/manage-mcp` | Setup, create, review, troubleshoot, and test MCP servers in Nuxt |

## Installing the Skill

Compatible agents (Cursor, Claude Code, etc.) can discover and use skills automatically.

Install from this site’s production URL (recommended):

```bash [Terminal]
npx skills add https://mcp-toolkit.nuxt.dev
```

The CLI fetches the catalog from [`/.well-known/skills/index.json`](https://mcp-toolkit.nuxt.dev/.well-known/skills/index.json){rel="&#x22;nofollow&#x22;"} and installs the `manage-mcp` skill and its reference files. For pull request previews, use the same command with your preview deployment URL ([Docus: preview and versioning](https://docus.dev/en/ai/skills){rel="&#x22;nofollow&#x22;"}).

## What the Skill Does

### Setup & Configure

The skill guides you through:

- **Installing** `@nuxtjs/mcp-toolkit` in your Nuxt app
- **Configuring** `nuxt.config.ts` with MCP options
- **Creating** the `server/mcp/` directory structure
- **Verifying** the MCP endpoint is accessible

### Create Definitions

The skill helps you build:

- **Tools**: Functions AI assistants can call, with Zod validation and error handling
- **Resources**: Read-only data exposed via URIs (static or dynamic with templates)
- **Prompts**: Reusable message templates with dynamic arguments
- **Middleware**: Authentication, rate limiting, logging, and CORS handlers

### Review & Audit

The skill analyzes your codebase for:

- **Missing descriptions**: Tools or resources without clear descriptions
- **Weak validation**: Missing `.describe()` on Zod fields
- **Error handling gaps**: Missing `isError: true` on error responses
- **Security issues**: Exposed sensitive data in resources or tools
- **Performance**: Missing caching on expensive operations

### Troubleshoot

The skill diagnoses:

- **Auto-imports not working**: Module configuration and file placement issues
- **Endpoint not accessible**: Server configuration and routing problems
- **Validation errors**: Schema mismatches and type issues
- **Tool not discovered**: File naming, exports, and directory structure problems

### Test with Evals

The skill helps you:

- Set up Evalite for MCP tool selection testing
- Write eval scenarios to validate tool selection
- Configure CI/CD integration for automated testing

### Example Prompts

Ask your AI assistant:

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Example — set up an MCP server
icon: i-lucide-sparkles
---
Setup an MCP server in my Nuxt app
::

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Example — database tool
icon: i-lucide-sparkles
---
Create a tool to fetch user data from my database
::

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Example — review MCP code
icon: i-lucide-sparkles
---
Review my MCP implementation for best practices
::

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Example — troubleshoot auto-imports
icon: i-lucide-sparkles
---
My auto-imports aren't working, help me troubleshoot
::

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Example — MCP eval tests
icon: i-lucide-sparkles
---
Create eval tests for my MCP tools
::

## Skill Structure

In the [mcp-toolkit repository](https://github.com/nuxt-modules/mcp-toolkit){rel="&#x22;nofollow&#x22;"}, skill sources live under the docs app:

```text
apps/docs/skills/
└── manage-mcp/
    ├── SKILL.md              # Main skill instructions
    └── references/
        ├── middleware.md     # Middleware patterns & examples
        ├── tools.md          # Tool examples
        ├── resources.md      # Resource examples
        ├── prompts.md        # Prompt examples
        ├── testing.md        # Testing guide with Evalite
        └── troubleshooting.md # Troubleshooting guide
```

Deployed files are served as `/.well-known/skills/manage-mcp/...` on [mcp-toolkit.nuxt.dev](https://mcp-toolkit.nuxt.dev){rel="&#x22;nofollow&#x22;"}.

## Reference Documents

The skill includes reference documents that provide:

### middleware.md

- Authentication patterns (API keys, JWT)
- Rate limiting and CORS configuration
- Logging and request tracking
- Security best practices

### tools.md

- Tool definition patterns with various input types
- Error handling and caching examples
- Real-world tool implementations

### resources.md

- Static and dynamic resource patterns
- File, API, and database resource examples
- URI template usage

### prompts.md

- Static and dynamic prompt patterns
- Multi-message conversation templates
- Code review and documentation generator examples

### testing.md

- Evalite setup and configuration
- Test scenario patterns
- CI/CD integration

### troubleshooting.md

- Auto-import resolution steps
- Endpoint debugging guide
- Validation error fixes
- Performance optimization tips

## Next Steps

- [Installation](https://mcp-toolkit.nuxt.dev/getting-started/installation) - Get started with Nuxt MCP Toolkit
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Learn how to create MCP tools
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Expose data via MCP resources
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Create reusable prompt templates
- [Apps](https://mcp-toolkit.nuxt.dev/apps/overview) - Ship interactive UI widgets to AI hosts


# Tools

## What are Tools?

Tools are functions that AI assistants can call to perform actions or retrieve information. They accept validated input parameters and return structured results.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Scaffold a new MCP tool
icon: i-lucide-wrench
---
Create a new MCP tool in my Nuxt app using @nuxtjs/mcp-toolkit.

- Create a file in server/mcp/tools/ (e.g. server/mcp/tools/my-tool.ts)
- Use defineMcpTool (auto-imported) with a description and handler
- Import Zod with `import { z } from 'zod'` and define input parameters in inputSchema (e.g. z.string().describe('...'))
- The handler receives validated input and returns a string, number, boolean, object, or full CallToolResult
- Throw errors with createError({ statusCode, message }) from h3 for error cases
- Name and title are auto-generated from the filename (e.g. my-tool.ts → name: 'my-tool', title: 'My Tool')
- Add annotations for behavioral hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
- Use subdirectories to auto-infer groups (e.g. tools/admin/delete-user.ts → group: 'admin')

Docs: <https://mcp-toolkit.nuxt.dev/tools/overview>{rel=""nofollow""}
::

## Basic Tool Definition

Here's a simple tool that echoes back a message:

```typescript [server/mcp/tools/echo.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'echo',
  description: 'Echo back a message',
  inputSchema: {
    message: z.string().describe('The message to echo back'),
  },
  handler: async ({ message }) => `Echo: ${message}`,
})
```

## Auto-Generated Name and Title

You can omit `name` and `title` - they will be automatically generated from the filename:

```typescript [server/mcp/tools/list-documentation.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  // name and title are auto-generated from filename:
  // name: 'list-documentation'
  // title: 'List Documentation'
  description: 'List all documentation files',
  handler: async () => {
    // ...
  },
})
```

The filename `list-documentation.ts` automatically becomes:

- `name`: `list-documentation` (kebab-case)
- `title`: `List Documentation` (title case)

You can still provide `name` or `title` explicitly to override the auto-generated values.

## Tool Structure

A tool definition consists of:

::code-group
```typescript [Required Fields]
export default defineMcpTool({
  name: 'tool-name',        // Unique identifier (optional - auto-generated from filename)
  inputSchema: { ... },      // Zod schema for input validation
  handler: async (args) => {
    return 'result'          // string, number, boolean, object, or CallToolResult
  },
})
```

```typescript [Optional Fields]
export default defineMcpTool({
  name: 'tool-name',              // Optional - auto-generated from filename
  title: 'Tool Title',            // Optional - auto-generated from filename
  description: 'Tool description',  // What the tool does
  inputSchema: { ... },            // Optional - Zod schema for input validation
  outputSchema: { ... },            // Zod schema for structured output
  annotations: { ... },             // Behavioral hints for clients
  inputExamples: [{ ... }],         // Concrete usage examples
  handler: async (args) => { ... },
})
```
::

## Going further

Once you've authored a few tools, branch out:

::card-group
  :::card
  ---
  color: neutral
  icon: i-lucide-globe
  title: Integrate external APIs
  to: https://mcp-toolkit.nuxt.dev/examples/api-integration
  ---
  Call third-party services, use 

  `useEvent()`

  , and cache responses with Nitro.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-shield-check
  title: Authenticate clients
  to: https://mcp-toolkit.nuxt.dev/examples/authentication
  ---
  Bearer tokens, Better Auth API keys, and per-tool 

  `enabled`

   guards.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-terminal
  title: Use Code Mode
  to: https://mcp-toolkit.nuxt.dev/advanced/code-mode
  ---
  Let the LLM orchestrate multiple tool calls in a single sandboxed JS execution.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-network
  title: Multi-handler organization
  to: https://mcp-toolkit.nuxt.dev/handlers/organization
  ---
  Attribute tools to dedicated MCP routes via the 

  `handlers/<name>/`

   folder convention.
  :::
::


# Schema, handler & returns

## Input Schema

The `inputSchema` is optional and uses Zod to define and validate input parameters. When provided, each field must be a Zod schema. Tools without parameters can omit `inputSchema` entirely:

```typescript [server/mcp/tools/echo.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'echo',
  description: 'Echo back a message',
  handler: async () => 'Echo: test',
})
```

For tools with parameters, define them using Zod schemas:

```typescript [server/mcp/tools/calculator.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'calculator',
  inputSchema: {
    // String input
    operation: z.string().describe('Operation to perform'),

    // Number input
    a: z.number().describe('First number'),
    b: z.number().describe('Second number'),

    // Optional field
    precision: z.number().optional().describe('Decimal precision'),

    // Enum input
    format: z.enum(['decimal', 'fraction']).describe('Output format'),

    // Array input
    numbers: z.array(z.number()).describe('List of numbers'),
  },
  handler: async ({ operation, a, b, precision, format, numbers }) => {
    // Handler implementation
  },
})
```

### Common Zod Types

| Zod Type       | Example                       | Description            |
| -------------- | ----------------------------- | ---------------------- |
| `z.string()`   | `z.string().min(1).max(100)`  | String with validation |
| `z.number()`   | `z.number().min(0).max(100)`  | Number with validation |
| `z.boolean()`  | `z.boolean()`                 | Boolean value          |
| `z.array()`    | `z.array(z.string())`         | Array of values        |
| `z.object()`   | `z.object({ ... })`           | Nested object          |
| `z.enum()`     | `z.enum(['a', 'b'])`          | Enumeration            |
| `z.optional()` | `z.string().optional()`       | Optional field         |
| `z.default()`  | `z.string().default('value')` | Field with default     |

## Output Schema

Define structured output using `outputSchema`:

```typescript [server/mcp/tools/bmi.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'calculate-bmi',
  description: 'Calculate Body Mass Index',
  inputSchema: {
    weightKg: z.number().describe('Weight in kilograms'),
    heightM: z.number().describe('Height in meters'),
  },
  outputSchema: {
    bmi: z.number(),
    category: z.string(),
  },
  handler: async ({ weightKg, heightM }) => {
    const bmi = weightKg / (heightM * heightM)
    let category = 'Normal'
    if (bmi < 18.5) category = 'Underweight'
    else if (bmi >= 25) category = 'Overweight'
    else if (bmi >= 30) category = 'Obese'

    return {
      structuredContent: {
        bmi: Math.round(bmi * 100) / 100,
        category,
      },
    }
  },
})
```

The `structuredContent` field provides structured data that matches your `outputSchema`, making it easier for AI assistants to work with the results.

## Handler Function

The handler is an async function that receives validated input and returns results. You can return simplified values directly — they are automatically wrapped into the MCP `CallToolResult` format.

### Simplified Returns

Return a `string`, `number`, `boolean`, object, or array directly from your handler:

::code-group
```typescript [String]
handler: async ({ name }) => `Hello ${name}`
// → { content: [{ type: 'text', text: 'Hello World' }] }
```

```typescript [Number]
handler: async ({ a, b }) => a + b
// → { content: [{ type: 'text', text: '10' }] }
```

```typescript [Object / Array]
handler: async ({ id }) => {
  const user = await getUser(id)
  return user
}
// → { content: [{ type: 'text', text: '{ "id": ... }' }] }
```

```typescript [Boolean]
handler: async ({ id }) => await exists(id)
// → { content: [{ type: 'text', text: 'true' }] }
```
::

You can also return the full `CallToolResult` format when you need more control (e.g., images, multiple content items, `structuredContent`).

### Content Types

For advanced use cases, return a full `CallToolResult` with typed content:

::code-group
```typescript [Image Content]
return {
  content: [{
    type: 'image',
    data: base64ImageData,
    mimeType: 'image/png',
  }],
}
```

```typescript [Structured Content]
return {
  structuredContent: {
    bmi: 25.5,
    category: 'Normal',
  },
}
// text content is auto-generated as fallback for older clients
```

```typescript [Resource Reference]
return {
  content: [{
    type: 'resource',
    resource: {
      uri: 'file:///path/to/file',
      text: 'File content',
      mimeType: 'text/plain',
    },
  }],
}
```
::

### Result Helpers

The module provides `imageResult` and `audioResult` helpers for binary media in tool responses (base64-encoded data plus MIME type):

```typescript
import { z } from 'zod'
import { defineMcpTool, imageResult, audioResult } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Generate chart',
  inputSchema: { data: z.array(z.number()) },
  handler: async ({ data }) => {
    const base64 = await generateChart(data)
    return imageResult(base64, 'image/png')
  },
})
```

```typescript
import { z } from 'zod'
import { defineMcpTool, audioResult } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Text to speech',
  inputSchema: { text: z.string() },
  handler: async ({ text }) => {
    const base64 = await synthesizeSpeech(text)
    return audioResult(base64, 'audio/mp3')
  },
})
```

::callout{color="info" icon="i-lucide-info"}
The 

`textResult`

, 

`jsonResult`

, and 

`errorResult`

 helpers are deprecated. Return values directly from your handler instead, and throw errors for error cases (see 

[Errors & caching](https://mcp-toolkit.nuxt.dev/tools/errors-caching)

).
::


# Annotations & input examples

## Tool Annotations

Annotations are behavioral hints that tell MCP clients how a tool behaves. Clients can use them to decide when to prompt users for confirmation (human-in-the-loop).

```typescript [server/mcp/tools/delete-user.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'delete-user',
  description: 'Delete a user account',
  inputSchema: {
    userId: z.string(),
  },
  annotations: {
    readOnlyHint: false,    // Tool modifies state
    destructiveHint: true,  // Tool performs destructive updates
    idempotentHint: true,   // Deleting the same user twice has no additional effect
    openWorldHint: false,   // Tool does not interact with external systems
  },
  handler: async ({ userId }) => {
    // ...
  },
})
```

### Annotation Reference

| Annotation        | Type      | Default | Description                                                                                                                                                        |
| ----------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `readOnlyHint`    | `boolean` | `false` | If `true`, the tool only reads data without modifying any state (safe to retry).                                                                                   |
| `destructiveHint` | `boolean` | `true`  | If `true`, the tool may perform destructive operations like deleting data. Only meaningful when `readOnlyHint` is `false`.                                         |
| `idempotentHint`  | `boolean` | `false` | If `true`, calling the tool multiple times with the same arguments has no additional effect beyond the first call. Only meaningful when `readOnlyHint` is `false`. |
| `openWorldHint`   | `boolean` | `true`  | If `true`, the tool may interact with the outside world (external APIs, internet). If `false`, it only operates on local/internal data.                            |

Here are common annotation patterns for typical tools:

::code-group
```typescript [Read-only tool]
// Search, list, lookup, calculate...
annotations: {
  readOnlyHint: true,
  destructiveHint: false,
  openWorldHint: false,
}
```

```typescript [Create tool]
// Creates a new record each time
annotations: {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: false,
  openWorldHint: false,
}
```

```typescript [Update tool]
// Updates are idempotent (same input → same result)
annotations: {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: true,
  openWorldHint: false,
}
```

```typescript [Delete tool]
// Destructive and idempotent (deleting twice is the same)
annotations: {
  readOnlyHint: false,
  destructiveHint: true,
  idempotentHint: true,
  openWorldHint: false,
}
```
::

::callout{color="info" icon="i-lucide-info"}
All annotations are 

**hints**

 — they are not guaranteed to be respected by every MCP client. Clients should never make security-critical decisions based on annotations from untrusted servers.
::

## Input Examples

You can provide concrete usage examples for your tools using `inputExamples`. These examples are type-safe (matching your `inputSchema`) and are transmitted to clients via `_meta.inputExamples`.

Input examples help AI models understand how to correctly fill in tool parameters, especially for tools with optional fields or complex inputs.

```typescript [server/mcp/tools/create-todo.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Create a new todo',
  inputSchema: {
    title: z.string().describe('The title of the todo'),
    content: z.string().optional().describe('Optional description'),
  },
  inputExamples: [
    { title: 'Buy groceries', content: 'Milk, eggs, bread' },
    { title: 'Fix login bug' },  // content is optional
  ],
  handler: async ({ title, content }) => {
    // ...
  },
})
```

::callout{color="warning" icon="i-lucide-lightbulb"}
`inputExamples`

 are particularly useful for tools with optional parameters, enums, or complex nested inputs where showing concrete values helps models pick the right format.
::


# Errors & caching

## Error Handling

Throw errors directly from your handlers — just like in Nitro event handlers. Thrown errors are automatically caught and converted into MCP-compliant `isError` results.

### H3 Errors (Recommended)

Use `createError()` from H3 for errors with status codes:

```typescript [server/mcp/tools/get-user.ts]
import { z } from 'zod'
import { createError } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'get-user',
  description: 'Get a user by ID',
  inputSchema: {
    id: z.string(),
  },
  handler: async ({ id }) => {
    const user = await findUser(id)
    if (!user) {
      throw createError({ statusCode: 404, message: 'User not found' })
    }
    return user
  },
})
// Error result: { isError: true, content: [{ type: 'text', text: '[404] User not found' }] }
```

H3 errors can also include structured data:

```typescript
throw createError({
  statusCode: 400,
  message: 'Validation failed',
  data: { fields: ['name', 'email'] },
})
// Error text: '[400] Validation failed\n{ "fields": ["name", "email"] }'
```

### Plain Errors

Regular `Error` instances work too:

```typescript [server/mcp/tools/safe-divide.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'safe-divide',
  inputSchema: {
    a: z.number(),
    b: z.number(),
  },
  handler: async ({ a, b }) => {
    if (b === 0) throw new Error('Division by zero')
    return a / b
  },
})
```

## Response Caching

You can cache tool responses using Nitro's caching system. The `cache` option accepts three formats:

### Simple Duration

Use a string duration (parsed by [`ms`](https://www.npmjs.com/package/ms){rel="&#x22;nofollow&#x22;"}) or a number in milliseconds:

```typescript [server/mcp/tools/cached-data.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Fetch data with 1 hour cache',
  inputSchema: {
    id: z.string(),
  },
  cache: '1h', // or '30m', '2 days', 3600000, etc.
  handler: async ({ id }) => {
    return await fetchExpensiveData(id)
  },
})
```

### Full Cache Options

For more control, use an object with all Nitro cache options:

```typescript [server/mcp/tools/cached-pages.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Get page with custom cache key',
  inputSchema: {
    path: z.string(),
  },
  cache: {
    maxAge: '1h',
    getKey: args => `page-${args.path}`,
    swr: true, // stale-while-revalidate
  },
  handler: async ({ path }) => {
    // ...
  },
})
```

### Cache Options Reference

| Option        | Type               | Required | Description                                                            |
| ------------- | ------------------ | -------- | ---------------------------------------------------------------------- |
| `maxAge`      | `string | number`  | Yes      | Cache duration (e.g., `'1h'`, `3600000`)                               |
| `getKey`      | `(args) => string` | No       | Custom cache key generator                                             |
| `staleMaxAge` | `number`           | No       | Duration for stale-while-revalidate                                    |
| `swr`         | `boolean`          | No       | Enable stale-while-revalidate (defaults to `false`, see warning below) |
| `name`        | `string`           | No       | Cache name (auto-generated from tool name)                             |
| `group`       | `string`           | No       | Cache group (default: `'mcp'`)                                         |

::callout{color="info" icon="i-lucide-info"}
See the 

[Nitro Cache documentation](https://nitro.build/guide/cache#options){rel=""nofollow""}

 for all available options.
::

::callout{color="warning" icon="i-lucide-triangle-alert"}
`swr`

 defaults to 

`false`

 (Nitro itself defaults to 

`true`

). With 

`swr: true`

, stale hits return immediately and the handler refreshes in the background after the request is answered, so request-scoped writes (structured logs, traces) may be dropped. Opt in only when you accept that trade-off.
::


# Groups, files & dynamic registration

## Advanced Examples

### Tool with API Integration

Here's an example showing a typical API-backed tool:

```typescript [server/mcp/tools/get-weather.ts]
import { z } from 'zod'
import { createError } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'get-weather',
  description: 'Get current weather for a city',
  inputSchema: {
    city: z.string().describe('City name'),
  },
  handler: async ({ city }) => {
    const data = await $fetch(`/api/weather/${city}`)
    if (!data) throw createError({ statusCode: 404, message: `City "${city}" not found` })
    return data
  },
})
```

## Groups and Tags

Organize your tools with `group` and `tags` for filtering and progressive discovery. Groups and tags are exposed in `_meta` and will map to [SEP-1300](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1300){rel="&#x22;nofollow&#x22;"} when adopted.

### Explicit Group and Tags

Set `group` and `tags` directly on the definition:

```typescript [server/mcp/tools/delete-user.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  group: 'admin',
  tags: ['destructive', 'user-management'],
  description: 'Delete a user account',
  inputSchema: {
    userId: z.string(),
  },
  handler: async ({ userId }) => {
    // ...
  },
})
```

### Auto-Inferred Group from Directory

Place tools in subdirectories and the group is inferred automatically:

```text
server/mcp/tools/
├── admin/
│   ├── delete-user.ts    → group: 'admin'
│   └── stats.ts          → group: 'admin'
├── content/
│   └── list-pages.ts     → group: 'content'
└── search.ts             → no group
```

An explicit `group` on the definition always takes precedence over the directory-inferred value.

### How Clients See Groups and Tags

Groups and tags are included in the `_meta` field of `tools/list` responses:

```json
{
  "name": "delete-user",
  "_meta": {
    "group": "admin",
    "tags": ["destructive", "user-management"]
  }
}
```

MCP clients can use these values to filter, sort, or group tools in their UI.

::callout{color="info" icon="i-lucide-info"}
For 

**resources**

 and 

**prompts**

, 

`group`

 and 

`tags`

 are stored on the definition objects but are not yet exposed in protocol responses (

`resources/list`

, 

`prompts/list`

). This will be supported when 

[SEP-1300](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1300){rel=""nofollow""}

 is adopted by the MCP SDK.
::

## File Organization

Organize your tools in the `server/mcp/tools/` directory. Both flat and nested layouts are supported:

```text
server/
└── mcp/
    └── tools/
        ├── echo.ts
        ├── calculator.ts
        ├── admin/
        │   ├── delete-user.ts
        │   └── stats.ts
        └── content/
            └── list-pages.ts
```

Each file should export a default tool definition. Subdirectories automatically set the `group` for all tools within them.

## Type Safety

The module provides full TypeScript type inference:

```typescript
// Input types are inferred from inputSchema
handler: async ({ message }) => {
  // message is typed as string
}

// Output types are inferred from outputSchema
const result = {
  structuredContent: {
    bmi: 25.5,      // number
    category: '...', // string
  },
}
```

## Conditional Registration

You can control whether a tool is visible to clients using the `enabled` guard:

```typescript [server/mcp/tools/admin-tool.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'admin-tool',
  description: 'Admin-only tool',
  enabled: event => event.context.user?.role === 'admin',
  handler: async () => {
    // ...
  },
})
```

When `enabled` returns `false`, the tool is hidden from `tools/list` and cannot be called.

::callout{color="primary" icon="i-lucide-book-open"}
See the 

[Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions)

 guide for detailed documentation on auth-based filtering.
::

## Next Steps

- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Create resources to expose data
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Create reusable prompts
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create custom MCP endpoints
- [Code Mode](https://mcp-toolkit.nuxt.dev/advanced/code-mode) - Let LLMs orchestrate tools with JavaScript
- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) - Conditionally register definitions
- [Examples](https://mcp-toolkit.nuxt.dev/examples/common-patterns) - See more tool examples


# Resources

## What are Resources?

Resources are a standardized way for MCP servers to expose **read-only data** to clients. They provide contextual information that can help AI models understand your application, such as files, database schemas, configuration, or any data accessible via a URI.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Scaffold a new MCP resource
icon: i-lucide-package
---
Create a new MCP resource in my Nuxt app using @nuxtjs/mcp-toolkit.

- Create a file in server/mcp/resources/ (e.g. server/mcp/resources/readme.ts)
- Use defineMcpResource (auto-imported) with a description
- For local files, use the file property: file: 'README.md' (URI, MIME type, and handler are auto-generated)
- For custom data, define uri and handler manually, returning { contents: [{ uri, text, mimeType }] }
- For dynamic resources, use ResourceTemplate from @modelcontextprotocol/sdk/server/mcp.js with URI variables
- Name and title are auto-generated from the filename
- Use subdirectories to auto-infer groups (e.g. resources/config/app.ts → group: 'config')

Docs: <https://mcp-toolkit.nuxt.dev/resources/overview>{rel=""nofollow""}
::

::callout{color="primary" icon="i-lucide-lightbulb"}
**Key concept**

: Unlike 

[tools](https://mcp-toolkit.nuxt.dev/tools/overview)

 which are invoked directly by the AI to perform actions, resources are 

**application-driven**

. The host application (not the AI) decides when and how to fetch and include resource content in the conversation.
::

Each resource is uniquely identified by a URI (e.g., `file:///project/README.md` or `api://users/123`).

## Resources vs Tools

Understanding the difference between resources and tools is essential:

| Aspect         | Resources                                 | Tools                              |
| -------------- | ----------------------------------------- | ---------------------------------- |
| **Purpose**    | Provide context and data                  | Perform actions                    |
| **Invocation** | Application-driven (user or app selects)  | AI-driven (model decides to call)  |
| **Nature**     | Read-only data access                     | Can read and modify state          |
| **Control**    | User/application controls what's included | AI decides when to use             |
| **Examples**   | Files, configs, DB schemas, logs          | Send email, create file, query API |

**When to use resources:**

- Exposing project files or documentation
- Sharing database schemas or configurations
- Providing logs or system information as context

**When to use tools:**

- Performing actions that modify state
- Executing operations the AI should decide to trigger
- Interacting with external APIs or services

## How Resources are Used

Resources follow an **application-driven** model. The typical flow:

1. **Discovery** — the host application calls `resources/list` to discover available resources.
2. **Selection** — the host displays resources in a UI (tree view, search, list) and the user (or application logic) picks which ones to include.
3. **Reading** — the host fetches the selected URIs via `resources/read`.
4. **Context inclusion** — the host injects the contents into the AI conversation as context.

::callout{color="info" icon="i-lucide-info"}
The AI model never directly requests resources. It's always the application that decides which resources to include based on user selection, heuristics, or automatic context detection.
::

## Going further

::card-group
  :::card
  ---
  color: neutral
  icon: i-lucide-file
  title: File operations example
  to: https://mcp-toolkit.nuxt.dev/examples/file-operations
  ---
  Read local files as MCP resources with graceful error handling.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-wrench
  title: Tools
  to: https://mcp-toolkit.nuxt.dev/tools/overview
  ---
  Pair resources with actions — tools are AI-driven, resources are application-driven.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-toggle-right
  title: Dynamic definitions
  to: https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions
  ---
  Hide resources from anonymous clients with the 

  `enabled`

   guard.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-list
  title: Listing definitions
  to: https://mcp-toolkit.nuxt.dev/advanced/listing-definitions
  ---
  Read your discovered catalog from your own server routes.
  :::
::

If you are new to MCP in Nuxt, start with [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) — resources complement tools but follow a different discovery model.


# Static resources & structure

## Static Resources

Static resources have a fixed URI that doesn't change.

### Simple File Resources

The easiest way to expose a local file is using the `file` property. This automatically handles the URI generation, MIME type detection, and file reading.

```typescript [server/mcp/resources/readme.ts]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'readme',
  description: 'Project README file',
  file: 'README.md', // Relative to project root
})
```

This generates:

- **URI**: `file:///path/to/project/README.md`
- **Handler**: Automatically reads the file content
- **MIME Type**: Automatically detected (e.g., `text/markdown`)

### Custom Static Resources

For more control, you can define the `uri` and `handler` manually:

```typescript [server/mcp/resources/custom-readme.ts]
import { readFile } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'custom-readme',
  title: 'README',
  description: 'Project README file',
  uri: 'file:///README.md',
  metadata: {
    mimeType: 'text/markdown',
  },
  handler: async (uri: URL) => {
    const filePath = fileURLToPath(uri)
    const content = await readFile(filePath, 'utf-8')
    return {
      contents: [{
        uri: uri.toString(),
        mimeType: 'text/markdown',
        text: content,
      }],
    }
  },
})
```

## Auto-Generated Name and Title

You can omit `name` and `title` - they will be automatically generated from the filename:

```typescript [server/mcp/resources/project-readme.ts]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  // name and title are auto-generated from filename:
  // name: 'project-readme'
  // title: 'Project Readme'
  file: 'README.md'
})
```

The filename `project-readme.ts` automatically becomes:

- `name`: `project-readme` (kebab-case)
- `title`: `Project Readme` (title case)

You can still provide `name` or `title` explicitly to override the auto-generated values.

## Resource Structure

A resource definition consists of:

::code-group
```typescript [File Resource]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'resource-name',
  file: 'path/to/file.txt', // Local file path
  metadata: { ... }
})
```

```typescript [Custom Resource]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'resource-name',  // Unique identifier
  uri: 'uri://...',      // Static URI or ResourceTemplate
  handler: async (uri) => { // Handler function
    return { contents: [...] }
  },
})
```
::


# Templates & handlers

## Dynamic Resources with Templates

Use `ResourceTemplate` to create dynamic resources that accept variables:

```typescript [server/mcp/resources/file.ts]
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
import type { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js'
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'file',
  title: 'File Resource',
  uri: new ResourceTemplate('file:///project/{+path}', {
    list: async () => {
      // Return list of available resources
      return {
        resources: [
          { uri: 'file:///project/README.md', name: 'README.md' },
          { uri: 'file:///project/src/index.ts', name: 'src/index.ts' },
        ],
      }
    },
  }),
  handler: async (uri: URL, variables: Variables) => {
    const path = variables.path as string
    const filePath = join(process.cwd(), path)
    const content = await readFile(filePath, 'utf-8')

    return {
      contents: [{
        uri: uri.toString(),
        mimeType: 'text/plain',
        text: content,
      }],
    }
  },
})
```

## ResourceTemplate

`ResourceTemplate` allows you to create resources with variable parts in the URI:

```typescript
new ResourceTemplate('file:///project/{+path}', {
  list: async () => {
    // Optional: Return list of available resources
    return {
      resources: [
        { uri: 'file:///project/file1.txt', name: 'File 1' },
        { uri: 'file:///project/file2.txt', name: 'File 2' },
      ],
    }
  },
})
```

### Template Variables

Variables in the URI are defined with `{variableName}`:

```typescript
// Single variable
new ResourceTemplate('file:///project/{path}', { ... })

// Variable allowing slashes (reserved expansion)
new ResourceTemplate('file:///project/{+path}', { ... })

// Multiple variables
new ResourceTemplate('api://users/{userId}/posts/{postId}', { ... })
```

## Handler Function

The handler receives the resolved URI and optional variables:

```typescript
// Static resource handler
handler: async (uri: URL) => {
  return {
    contents: [{
      uri: uri.toString(),
      mimeType: 'text/plain',
      text: 'Content',
    }],
  }
}

// Dynamic resource handler
handler: async (uri: URL, variables: Variables) => {
  const path = variables.path as string
  // Use variables to resolve the resource
  return {
    contents: [{
      uri: uri.toString(),
      mimeType: 'text/plain',
      text: 'Content',
    }],
  }
}
```


# Metadata, content & errors

## Resource Metadata

Add a `metadata` block to help clients render the resource correctly. It carries the MIME type, behavior annotations, and any extra fields you want to surface in `resources/list`:

```typescript [server/mcp/resources/readme.ts]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'readme',
  description: 'Project README file',
  file: 'README.md',
  metadata: {
    mimeType: 'text/markdown',
    annotations: {
      audience: ['user', 'assistant'],
      priority: 0.8,
      lastModified: new Date().toISOString(),
    },
  },
})
```

| Field                               | Type                       | Description                                                                                                     |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `metadata.mimeType`                 | `string`                   | Hint to clients about the content type. Auto-detected when you use `file: '…'`; set explicitly for custom URIs. |
| `metadata.annotations.audience`     | `('user' | 'assistant')[]` | Who should see this resource — the user, the AI, or both.                                                       |
| `metadata.annotations.priority`     | `number` (0–1)             | Suggested importance when clients have to choose which resources to include.                                    |
| `metadata.annotations.lastModified` | `string` (ISO 8601)        | When the resource last changed — clients may use this for caching.                                              |

Anything else you put inside `metadata` is forwarded verbatim under `_meta` in the listing response, so you can carry custom fields for your own UI.

## Content Types

Resources can return different MIME types:

::code-group
```typescript [Text/Markdown]
return {
  contents: [{
    uri: uri.toString(),
    mimeType: 'text/markdown',
    text: '# Markdown content',
  }],
}
```

```typescript [JSON]
return {
  contents: [{
    uri: uri.toString(),
    mimeType: 'application/json',
    text: JSON.stringify({ key: 'value' }),
  }],
}
```

```typescript [Binary Data]
return {
  contents: [{
    uri: uri.toString(),
    mimeType: 'image/png',
    blob: Buffer.from(binaryData),
  }],
}
```
::

## Error Handling

Handle errors gracefully in your handlers:

```typescript [server/mcp/resources/custom-readme.ts]
import { readFile } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'readme',
  uri: 'file:///README.md',
  handler: async (uri: URL) => {
    try {
      const filePath = fileURLToPath(uri)
      const content = await readFile(filePath, 'utf-8')

      return {
        contents: [{
          uri: uri.toString(),
          mimeType: 'text/markdown',
          text: content,
        }],
      }
    }
    catch (error) {
      return {
        contents: [{
          uri: uri.toString(),
          mimeType: 'text/plain',
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        }],
        isError: true,
      }
    }
  },
})
```


# Groups & organization

## Groups and Tags

Organize your resources with `group` and `tags` for categorization. These fields work the same way as for [tools](https://mcp-toolkit.nuxt.dev/tools/groups-organization#groups-and-tags).

```typescript [server/mcp/resources/config/app-settings.ts]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  group: 'config',
  tags: ['readonly', 'settings'],
  description: 'Application settings',
  file: 'config/app.json',
})
```

You can also place resource files in subdirectories to auto-infer the group:

```text
server/mcp/resources/
├── config/
│   └── app-settings.ts   → group: 'config'
├── docs/
│   └── readme.ts         → group: 'docs'
└── schema.ts             → no group
```

::callout{color="info" icon="i-lucide-info"}
Resource 

`group`

 and 

`tags`

 are stored on the definition objects but are not yet included in 

`resources/list`

 protocol responses. This will be supported when 

[SEP-1300](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1300){rel=""nofollow""}

 is adopted by the MCP SDK.
::

## File Organization

Organize your resources in the `server/mcp/resources/` directory. Both flat and nested layouts are supported:

```text
server/
└── mcp/
    └── resources/
        ├── readme.ts
        ├── file.ts
        └── config/
            └── app-settings.ts
```

Each file should export a default resource definition. Subdirectories automatically set the `group`.

## URI Schemes

You can use any URI scheme that makes sense for your use case:

- `file://` - File system resources
- `api://` - API endpoints
- `http://` / `https://` - Web resources
- `custom://` - Custom schemes

## Conditional Registration

You can control whether a resource is visible to clients using the `enabled` guard:

```typescript [server/mcp/resources/internal-data.ts]
export default defineMcpResource({
  name: 'internal-data',
  uri: 'app://internal',
  enabled: event => event.context.user?.role === 'admin',
  handler: async (uri) => ({
    contents: [{ uri: uri.toString(), text: 'Internal data...' }],
  }),
})
```

::callout{color="primary" icon="i-lucide-book-open"}
See the 

[Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions)

 guide for detailed documentation on auth-based filtering.
::

## Next Steps

- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Create tools to perform actions
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Create reusable prompts
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create custom MCP endpoints
- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) - Conditionally register definitions
- [Examples](https://mcp-toolkit.nuxt.dev/examples/file-operations) - More resource examples


# Prompts

## What are Prompts?

Prompts are reusable message templates that can be used by AI assistants. They can include dynamic arguments and return pre-formatted messages.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Scaffold a new MCP prompt
icon: i-lucide-message-square
---
Create a new MCP prompt in my Nuxt app using @nuxtjs/mcp-toolkit.

- Create a file in server/mcp/prompts/ (e.g. server/mcp/prompts/review-code.ts)
- Use defineMcpPrompt (auto-imported) with a description and handler
- The handler can return a string (auto-wrapped as a user message) or a full GetPromptResult with messages array
- Define arguments with `import { z } from 'zod'` in inputSchema (prompt arguments must be strings)
- Use the role option ('user' or 'assistant') to control the default role for string returns
- Use completable() to provide autocompletion suggestions for arguments
- Return multiple messages to create a conversation flow
- Name and title are auto-generated from the filename
- Prompts appear in Cursor and VS Code when typing / in the chat

Docs: <https://mcp-toolkit.nuxt.dev/prompts/overview>{rel=""nofollow""}
::

## Why Use Prompts?

MCP prompts offer several advantages over ad-hoc instructions:

::card-group
  :::card{icon="i-lucide-repeat" title="Reusability"}
  Define once, use everywhere. Share prompts across your team for consistent AI interactions.
  :::

  :::card{icon="i-lucide-check-square" title="Standardization"}
  Ensure consistent formatting and context for specific tasks like code reviews or documentation.
  :::

  :::card{icon="i-lucide-settings-2" title="Customization"}
  Use arguments to adapt prompts to different contexts while maintaining structure.
  :::

  :::card{icon="i-lucide-plug" title="IDE Integration"}
  Prompts appear in Cursor, VS Code, and Visual Studio for easy access during development.
  :::
::

## IDE Integration

MCP prompts integrate seamlessly with modern development environments. When your MCP server is connected, prompts become available directly in your IDE.

### Using Prompts in Cursor / VS Code

1. **Type `/`** — in the chat, type `/` to see all available MCP prompts.
2. **Select a prompt** — choose from the list (e.g. `local-mcp/setup-mcp-server`).
3. **Fill arguments** — for parameterized prompts, a dialog appears to collect the values defined in your `inputSchema`.
4. **Send** — the prompt's messages are inserted into the conversation as if you had typed them.

Prompts surface with the prefix `<server-name>/<prompt-name>`, so renaming your handler in `defineMcpHandler({ name })` changes how they appear in clients.

## Going further

::card-group
  :::card
  ---
  color: neutral
  icon: i-lucide-pen-line
  title: Authoring & structure
  to: https://mcp-toolkit.nuxt.dev/prompts/authoring
  ---
  Auto-generated names, simple prompts, default roles, and prompt structure.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-layers
  title: Input, handler & messages
  to: https://mcp-toolkit.nuxt.dev/prompts/input-handler-messages
  ---
  Zod arguments, completable autocomplete, return types, and multi-message conversations.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-line-chart
  title: Patterns & advanced
  to: https://mcp-toolkit.nuxt.dev/prompts/patterns-advanced
  ---
  Real-world examples, groups, type safety, best practices, and conditional registration.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-message-square
  title: Prompt examples
  to: https://mcp-toolkit.nuxt.dev/examples/prompt-examples
  ---
  Code review, documentation, email, and commit-message prompts you can copy.
  :::
::

## Next Steps

- [Authoring & structure](https://mcp-toolkit.nuxt.dev/prompts/authoring) — write your first prompt.
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) — pair prompts with actions the AI can take.
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) — feed context alongside your prompts.


# Authoring & structure

## Auto-Generated Name and Title

You can omit `name` and `title` - they will be automatically generated from the filename:

```typescript [server/mcp/prompts/greeting.ts]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  // name and title are auto-generated from filename:
  // name: 'greeting'
  // title: 'Greeting'
  description: 'Generate a personalized greeting message',
  handler: async () => {
    // ...
  },
})
```

The filename `greeting.ts` automatically becomes:

- `name`: `greeting` (kebab-case)
- `title`: `Greeting` (title case)

You can still provide `name` or `title` explicitly to override the auto-generated values.

## Simple Prompt (No Arguments)

Create a prompt without arguments. Handlers can return a simple string — it will be automatically wrapped into a single user message:

```typescript [server/mcp/prompts/greeting.ts]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'greeting',
  title: 'Greeting',
  description: 'Generate a personalized greeting message',
  handler: async () => {
    const hour = new Date().getHours()
    const timeOfDay = hour < 12 ? 'morning' : hour < 18 ? 'afternoon' : 'evening'

    return `Good ${timeOfDay}! How can I help you today?`
  },
})
```

### Default Role

When a handler returns a string, it is wrapped with the `user` role by default. Use the `role` option to change this:

```typescript [server/mcp/prompts/code-reviewer.ts]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  role: 'assistant',
  description: 'Code review assistant persona',
  handler: async () => 'I am a code review assistant. Share your code and I will review it for best practices.',
})
```

::callout{color="info" icon="i-lucide-info"}
The 

`role`

 option only affects string returns. When returning a full 

`GetPromptResult`

, define roles directly in the 

`messages`

 array.
::

## Prompt with Arguments

Create a prompt that accepts arguments:

```typescript [server/mcp/prompts/summarize.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'summarize',
  title: 'Text Summarizer',
  description: 'Summarize any text content',
  inputSchema: {
    text: z.string().describe('The text to summarize'),
    maxLength: z.string().optional().describe('Maximum length of summary in words'),
  },
  handler: async ({ text, maxLength }) => {
    const words = text.split(/\s+/)
    const maxWords = maxLength ? Number.parseInt(maxLength) : Math.ceil(words.length * 0.3)
    const summary = words.slice(0, maxWords).join(' ')

    return `Summary (${maxWords} words): ${summary}${words.length > maxWords ? '...' : ''}`
  },
})
```

## Prompt Structure

A prompt definition consists of:

::code-group
```typescript [Simple Prompt]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'prompt-name',  // Unique identifier
  handler: async () => 'Your prompt text here',
})
```

```typescript [With Role]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'prompt-name',
  role: 'assistant',             // Role for string returns (default: 'user')
  handler: async () => 'I am an assistant persona.',
})
```

```typescript [Prompt with Arguments]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'prompt-name',
  title: 'Prompt Title',        // Human-readable title
  description: 'Description',   // What the prompt does
  inputSchema: { ... },          // Zod schema for arguments
  handler: async (args) => {    // Handler with arguments
    return `Prompt text with ${args.param}`
  },
})
```
::


# Input, handler & messages

## Input Schema

Use Zod to define and validate prompt arguments:

```typescript [server/mcp/prompts/translate.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'translate',
  inputSchema: {
    // Required string argument
    text: z.string().describe('Text to translate'),

    // Required enum argument
    targetLanguage: z.enum(['en', 'fr', 'es', 'de']).describe('Target language'),

    // Optional argument
    sourceLanguage: z.string().optional().describe('Source language (auto-detect if not provided)'),

    // Optional with default
    formality: z.enum(['formal', 'informal']).default('formal'),
  },
  handler: async ({ text, targetLanguage, sourceLanguage, formality }) => {
    // Implementation
  },
})
```

### Common Argument Types

| Zod Type       | Example                       | Description            |
| -------------- | ----------------------------- | ---------------------- |
| `z.string()`   | `z.string().min(1)`           | String with validation |
| `z.enum()`     | `z.enum(['a', 'b'])`          | Enumeration            |
| `z.optional()` | `z.string().optional()`       | Optional field         |
| `z.default()`  | `z.string().default('value')` | Field with default     |

::callout{color="info" icon="i-lucide-info"}
**Note**

: Prompt arguments must be strings. Use 

`z.string()`

 and convert to other types in your handler if needed.
::

### Argument Autocompletion

Wrap a schema field with `completable()` to provide autocompletion suggestions when clients fill in prompt arguments:

```typescript [server/mcp/prompts/review-code.ts]
export default defineMcpPrompt({
  description: 'Review code for best practices',
  inputSchema: {
    language: completable(
      z.string().describe('Programming language'),
      value => ['typescript', 'javascript', 'python', 'rust', 'go']
        .filter(lang => lang.startsWith(value)),
    ),
  },
  handler: async ({ language }) => {
    return `Review the following ${language} code for best practices and potential issues.`
  },
})
```

The `completable` helper is auto-imported and re-exported from the MCP SDK. The callback receives the current input value and returns matching suggestions.

## Handler Function

The handler receives validated arguments (if `inputSchema` is provided) and returns a prompt result.

### Return Types

Handlers support two return types:

::code-group
```typescript [String (recommended)]
// Return a string — auto-wrapped into a single user message
handler: async () => 'You are a helpful assistant.'

// With arguments
handler: async ({ topic }) => `Help me understand ${topic}.`
```

```typescript [Full GetPromptResult]
// Return the full MCP result for multi-message or assistant-role prompts
handler: async () => ({
  messages: [
    { role: 'user', content: { type: 'text', text: 'Review this code.' } },
    { role: 'assistant', content: { type: 'text', text: 'I will review it.' } },
  ],
})
```
::

::callout{color="info" icon="i-lucide-info"}
When returning a string, it is automatically wrapped into 

`{ messages: [{ role, content: { type: 'text', text: '...' } }] }`

 using the 

`role`

 option (defaults to 

`'user'`

).
::

### Handler Arguments

```typescript
// Without inputSchema — no arguments
handler: async () => 'Message text'

// With inputSchema — receives validated arguments
handler: async (args, extra) => {
  // args: Validated arguments matching inputSchema
  // extra: Request handler extra information
  return `Message with ${args.param}`
}
```

## Message Roles

Prompts can return messages with different roles:

::code-group
```typescript [User Message]
return {
  messages: [{
    role: 'user',
    content: {
      type: 'text',
      text: 'User message with instructions',
    },
  }],
}
```

```typescript [Assistant Message]
return {
  messages: [{
    role: 'assistant',
    content: {
      type: 'text',
      text: 'Pre-filled assistant response',
    },
  }],
}
```
::

::callout{color="info" icon="i-lucide-info"}
**Note**

: The MCP specification only supports 

`user`

 and 

`assistant`

 roles. To provide context or instructions, include them in the 

`user`

 message text.
::

## Multiple Messages

Return multiple messages to create a conversation flow:

```typescript [server/mcp/prompts/conversation.ts]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'conversation-starter',
  inputSchema: {
    topic: z.string().describe('Conversation topic'),
  },
  handler: async ({ topic }) => {
    return {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `You are a helpful assistant. Let's discuss ${topic}.`,
          },
        },
        {
          role: 'assistant',
          content: {
            type: 'text',
            text: `I'd be happy to discuss ${topic} with you.`,
          },
        },
      ],
    }
  },
})
```


# Patterns & advanced

## Use Cases

Prompts are particularly useful for:

### 1. Setup and Onboarding

Help new developers or AI assistants understand how to work with your codebase:

```typescript [server/mcp/prompts/setup-guide.ts]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  description: 'Provide complete setup instructions for this project',
  handler: async () => `You are setting up this Nuxt project. Here's what you need to know:

1. Install dependencies: \`pnpm install\`
2. Start dev server: \`pnpm dev\`
3. Project structure follows Nuxt conventions
4. MCP tools are available in server/mcp/

Ask me what you'd like to build!`,
})
```

### 2. Code Review Standards

Ensure consistent code review criteria:

```typescript [server/mcp/prompts/review-standards.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  description: 'Apply team code review standards',
  inputSchema: {
    focus: z.enum(['security', 'performance', 'maintainability', 'all']).default('all'),
  },
  handler: async ({ focus }) => `You are a code reviewer following our team standards. Focus on: ${focus}.

Review the code I provide, checking for best practices and potential issues.`,
})
```

### 3. Documentation Generation

Standardize documentation format:

```typescript [server/mcp/prompts/generate-docs.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  description: 'Generate documentation in team format',
  inputSchema: {
    type: z.enum(['api', 'component', 'function']).describe('What to document'),
  },
  handler: async ({ type }) => {
    const templates = {
      api: 'Document this API endpoint with: endpoint, method, parameters, response format, and examples.',
      component: 'Document this Vue component with: props, emits, slots, and usage examples.',
      function: 'Document this function with: parameters, return value, and usage examples.',
    }

    return templates[type]
  },
})
```

### 4. Troubleshooting Workflows

Guide debugging for common issues:

```typescript [server/mcp/prompts/debug-helper.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  description: 'Help debug common issues',
  inputSchema: {
    area: z.enum(['api', 'auth', 'database', 'frontend']).describe('Area of the issue'),
  },
  handler: async ({ area }) => `You are debugging a ${area} issue. Ask clarifying questions and suggest diagnostic steps.`,
})
```

## Groups and Tags

Organize your prompts with `group` and `tags` for categorization. These fields work the same way as for [tools](https://mcp-toolkit.nuxt.dev/tools/groups-organization#groups-and-tags).

```typescript [server/mcp/prompts/onboarding/setup-guide.ts]
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  tags: ['getting-started'],
  description: 'Help new developers set up the project',
  handler: async () => 'You are setting up this project...',
})
```

Placing the file in `prompts/onboarding/` auto-infers `group: 'onboarding'`.

::callout{color="info" icon="i-lucide-info"}
Prompt 

`group`

 and 

`tags`

 are stored on the definition objects but are not yet included in 

`prompts/list`

 protocol responses. This will be supported when 

[SEP-1300](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1300){rel=""nofollow""}

 is adopted by the MCP SDK.
::

## File Organization

Organize your prompts in the `server/mcp/prompts/` directory. Both flat and nested layouts are supported:

```text
server/
└── mcp/
    └── prompts/
        ├── greeting.ts
        ├── summarize.ts
        ├── onboarding/
        │   └── setup-guide.ts
        └── debugging/
            └── troubleshoot.ts
```

Each file should export a default prompt definition. Subdirectories automatically set the `group`.

## Type Safety

The module provides full TypeScript type inference:

```typescript
// Argument types are inferred from inputSchema
handler: async ({ text, maxLength }) => {
  // text is typed as string
  // maxLength is typed as string | undefined
}
```

## Best Practices

### 1. Design for AI Understanding

Write prompts that give the AI clear context and expectations:

```typescript
// Good: Clear context and instructions
handler: async ({ code }) =>
  `You are a senior developer reviewing code for a Nuxt application.

Review this code for Vue 3 best practices:\n\n${code}`

// Less effective: Vague instructions
handler: async ({ code }) => code
```

### 2. Use Descriptive Arguments

Always use `.describe()` on Zod fields to help both users and AI understand what's expected:

```typescript
inputSchema: {
  // Good: Clear descriptions
  language: z.enum(['typescript', 'javascript']).describe('Programming language of the code'),
  strict: z.boolean().default(true).describe('Whether to enforce strict TypeScript rules'),

  // Less helpful: No descriptions
  lang: z.string(),
  s: z.boolean(),
}
```

### 3. Use Conversation Flow

Use user and assistant messages to guide the AI:

```typescript
// Effective: User provides context, assistant acknowledges
messages: [
  { role: 'user', content: { type: 'text', text: 'You are an expert in accessibility. Review this HTML for a11y issues.' } },
  { role: 'assistant', content: { type: 'text', text: 'I\'ll analyze the HTML for accessibility issues.' } },
]
```

### 4. Keep Prompts Focused

Each prompt should have a single, clear purpose. Create multiple prompts instead of one complex one:

```typescript
// Good: Separate focused prompts
// server/mcp/prompts/review-security.ts
// server/mcp/prompts/review-performance.ts
// server/mcp/prompts/review-style.ts

// Less maintainable: One complex prompt trying to do everything
```

### 5. Provide Default Values

Use `.default()` for optional arguments to improve usability:

```typescript
inputSchema: {
  format: z.enum(['brief', 'detailed']).default('detailed').describe('Output format'),
  language: z.string().default('en').describe('Response language'),
}
```

### 6. Include Examples in Complex Prompts

For prompts that need specific output formats, include examples:

```typescript
handler: async () => `Generate a commit message following this format:

type(scope): description

Example:
feat(auth): add OAuth2 login support

Types: feat, fix, docs, style, refactor, test, chore`
```

## Conditional Registration

You can control whether a prompt is visible to clients using the `enabled` guard:

```typescript [server/mcp/prompts/admin-prompt.ts]
export default defineMcpPrompt({
  name: 'admin-prompt',
  description: 'Admin-only prompt',
  enabled: event => event.context.user?.role === 'admin',
  handler: async () => 'Admin instructions...',
})
```

::callout{color="primary" icon="i-lucide-book-open"}
See the 

[Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions)

 guide for detailed documentation on auth-based filtering.
::

## Next Steps

- [Prompt Examples](https://mcp-toolkit.nuxt.dev/examples/prompt-examples) - See advanced prompt examples
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Create tools to perform actions
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Create resources to expose data
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create custom MCP endpoints
- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) - Conditionally register definitions


# Handlers

## What are Handlers?

Handlers allow you to create **multiple MCP endpoints** in a single Nuxt application. Each handler has its own route, name, version, and can include its own set of tools, resources, and prompts.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Create a custom MCP handler and endpoint
icon: i-lucide-server
---
Create a custom MCP handler with its own endpoint and tools using @nuxtjs/mcp-toolkit.

- Create a .ts file at the root of server/mcp/ (e.g. server/mcp/admin.ts) — files in subdirectories like tools/, resources/, prompts/ are definitions, not handlers
- Use defineMcpHandler (auto-imported) with name, route, tools, resources, and prompts
- Set the route explicitly (e.g. route: '/mcp/admin')
- Define tools inline with defineMcpTool or import shared tools
- Override the default handler by creating server/mcp/index.ts with defineMcpHandler
- Add middleware for handler-specific authentication or logging
- Set version and browserRedirect per handler

Docs: <https://mcp-toolkit.nuxt.dev/handlers/overview>{rel=""nofollow""}
::

This is useful when you want to:

- Separate different MCP functionalities into different endpoints
- Create versioned MCP APIs
- Organize tools/resources by domain or feature

## Guides

::card-group
  :::card
  ---
  color: neutral
  icon: i-lucide-network
  title: Multi-handler organization
  to: https://mcp-toolkit.nuxt.dev/handlers/organization
  ---
  Folder convention to attribute tools, resources, and prompts to MCP routes — plus the 

  `getMcp*`

   escape hatch.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-toggle-left
  title: Default & custom handlers
  to: https://mcp-toolkit.nuxt.dev/handlers/default-and-custom
  ---
  Override 

  `/mcp`

   via 

  `server/mcp/index.ts`

  , or expose new endpoints with 

  `defineMcpHandler`

  .
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-sliders-horizontal
  title: Structure & options
  to: https://mcp-toolkit.nuxt.dev/handlers/structure-and-options
  ---
  Every 

  `defineMcpHandler`

   field — 

  `name`

  , 

  `route`

  , 

  `middleware`

  , 

  `tools`

  , 

  `experimental_codeMode`

  .
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-share-2
  title: Sharing & practices
  to: https://mcp-toolkit.nuxt.dev/handlers/sharing-practices
  ---
  Cross-handler tool sharing, file layout, and use cases.
  :::
::


# Default & custom handlers

## Default Handler

By default, the module creates a single MCP endpoint at `/mcp` (or your configured route) that includes all tools, resources, and prompts from the `server/mcp/` directory.

### Overriding the Default Handler

You can override the default handler's configuration by creating an `index.ts` file in `server/mcp/`:

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  version: '2.0.0',
  browserRedirect: '/docs',
  // If tools/resources/prompts not specified, uses global definitions
})
```

This allows you to customize:

- `version` - Override the server version
- `browserRedirect` - Override the browser redirect URL
- `name` - Override the server name (optional)
- `tools`, `resources`, `prompts` - Use specific definitions instead of global ones
- `middleware` - Add request interception for auth, logging, etc. ([learn more](https://mcp-toolkit.nuxt.dev/advanced/middleware))

::callout{color="info" icon="i-lucide-info"}
The 

`route`

 property is 

**ignored**

 for the default handler. To change the route, use 

`mcp.route`

 in your 

`nuxt.config.ts`

.
::

#### Example: Custom Version and Redirect

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  name: 'My Documentation MCP',
  version: '1.2.0',
  browserRedirect: '/getting-started',
})
```

#### Example: Limiting Exposed Tools

```typescript [server/mcp/index.ts]
import { myTool, anotherTool } from './tools/my-tools'

export default defineMcpHandler({
  // Only expose specific tools instead of all tools in server/mcp/tools/
  tools: [myTool, anotherTool],
})
```

## Custom Handlers

Create custom handlers using `defineMcpHandler`:

```typescript [server/mcp/migration.ts]
import { z } from 'zod'
import { defineMcpTool, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const migrationTool = defineMcpTool({
  name: 'migrate-v3-to-v4',
  title: 'Migrate v3 to v4',
  description: 'Migrate code from version 3 to version 4',
  inputSchema: {
    code: z.string().describe('The code to migrate'),
  },
  handler: async ({ code }) => {
    return code.replace(/v3/g, 'v4')
  },
})

export default defineMcpHandler({
  name: 'migration',
  version: '0.1.0',
  route: '/mcp/migration',
  tools: [migrationTool],
  browserRedirect: '/',
})
```


# Structure & options

## Handler Structure

A handler definition consists of:

::code-group
```typescript [Required Fields]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler-name',  // Unique identifier
})
```

```typescript [Optional Fields]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler-name',
  version: '1.0.0',              // Handler version
  description: 'Admin tools',    // serverInfo description shown by clients
  instructions: 'Always …',      // System-prompt guidance for LLMs
  icons: [ ... ],                 // Server icons shown in client UIs
  route: '/mcp/custom',          // Custom route
  browserRedirect: '/',          // Browser redirect URL
  middleware: async (event) => { ... }, // Request interception
  tools: [ ... ],                 // Array of tools
  resources: [ ... ],            // Array of resources
  prompts: [ ... ],               // Array of prompts
  experimental_codeMode: true,    // Enable code mode (experimental)
})
```
::

## Handler Options

### `name` (required)

Unique identifier for the handler. The `name` determines where the handler will be mounted. By default, the handler will be accessible at `/mcp/:name`.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'migration', // Handler mounted at /mcp/migration
})
```

### `version` (optional)

Version of the handler. Defaults to the module's configured version.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'migration',
  version: '2.0.0',
})
```

### `description` (optional)

Human-readable description sent as part of `serverInfo` during MCP initialization. Clients use it to identify the handler in UIs (server lists, install prompts, tooltips). Falls back to `mcp.description` from `nuxt.config.ts`.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'admin',
  description: 'Admin tools — destructive operations gated by Bearer auth.',
})
```

### `instructions` (optional)

Operational guidance for AI agents — typically injected by clients into the model's system prompt. Use this to describe workflows, constraints, or relationships between tools (use `description` to identify the handler). Falls back to `mcp.instructions` from `nuxt.config.ts`.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'admin',
  instructions: 'Always call list-users before delete-user. Confirm with the operator before any destructive action.',
})
```

### `icons` (optional)

Icons displayed by clients in their UIs. Each entry needs `src` and `mimeType`, with optional `sizes` and `theme` (`'light' | 'dark'`). Falls back to `mcp.icons` from `nuxt.config.ts`.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'admin',
  icons: [
    { src: 'https://example.com/admin.png', mimeType: 'image/png', sizes: ['64x64'] },
  ],
})
```

::callout{color="info" icon="i-lucide-info"}
`description`

, 

`instructions`

, and 

`icons`

 are part of the 

[MCP lifecycle spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization){rel=""nofollow""}

. Set them at the module level for shared metadata, override per-handler when a specific endpoint needs different identity.
::

### `route` (optional)

Custom route for the handler. Defaults to `/mcp/:name`.

::callout{color="info" icon="i-lucide-info"}
This option is only used for 

**custom handlers**

. For the default handler override (

`index.ts`

), use 

`mcp.route`

 in 

`nuxt.config.ts`

 instead.
::

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'migration',
  route: '/api/mcp/migration', // Custom route
})
```

### `browserRedirect` (optional)

URL to redirect browsers when they access the handler endpoint. Defaults to the module's configured `browserRedirect`.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'migration',
  browserRedirect: '/docs/migration',
})
```

### `middleware` (optional)

Function to intercept requests before/after they are processed. Useful for authentication, logging, and setting context.

```typescript [server/mcp/custom.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'custom',
  middleware: async (event) => {
    event.context.userId = 'user-123'
  },
})
```

::callout{color="primary" icon="i-lucide-book-open"}
See the 

[Middleware guide](https://mcp-toolkit.nuxt.dev/advanced/middleware)

 for detailed documentation and examples.
::

### `experimental_codeMode` (optional)

Enable [Code Mode](https://mcp-toolkit.nuxt.dev/advanced/code-mode) to let LLMs orchestrate multiple tool calls in a single JavaScript execution. Pass `true` for defaults or an options object:

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'custom',
  experimental_codeMode: {
    progressive: true,
    memoryLimit: 128,
  },
})
```

Code Mode requires `secure-exec` and Node.js `>=18.16.0`.

::callout{color="primary" icon="i-lucide-book-open"}
See the 

[Code Mode guide](https://mcp-toolkit.nuxt.dev/advanced/code-mode)

 for full documentation, security details, and configuration options.
::

### `tools` (optional)

Accepts three shapes — pick whichever matches your use case:

::code-group
```typescript [Auto (default)]
// server/mcp/handlers/admin/index.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

// `tools` omitted → every tool under handlers/admin/tools/
// is auto-registered (folder convention).
export default defineMcpHandler({
  middleware: requireAdmin,
})
```

```typescript [Static array]
import { defineMcpTool, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const tool1 = defineMcpTool({ ... })
const tool2 = defineMcpTool({ ... })

export default defineMcpHandler({
  name: 'custom',
  tools: [tool1, tool2],
})
```

```typescript [Dynamic function]
import { defineMcpHandler, getMcpTools } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  // Every tool tagged 'searchable', regardless of folder.
  tools: event => getMcpTools({ event, tags: ['searchable'] }),
})
```
::

::callout{color="primary" icon="i-lucide-book-open"}
See 

[multi-handler organization](https://mcp-toolkit.nuxt.dev/handlers/organization)

 for the folder convention, and 

[`getMcpTools`](https://mcp-toolkit.nuxt.dev/advanced/listing-definitions)

 for ad-hoc filtering. Per-tool 

`enabled()`

 guards apply automatically — see 

[Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions)

.
::

### `resources` (optional)

Same shapes as [`tools`](https://mcp-toolkit.nuxt.dev/#tools-optional): omit for folder-convention auto-attribution, pass an array, or pass `event => getMcpResources({ event, ... })`.

```typescript
import { defineMcpResource, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const resource1 = defineMcpResource({ ... })
const resource2 = defineMcpResource({ ... })

export default defineMcpHandler({
  name: 'custom',
  resources: [resource1, resource2],
})
```

### `prompts` (optional)

Same shapes as [`tools`](https://mcp-toolkit.nuxt.dev/#tools-optional): omit for folder-convention auto-attribution, pass an array, or pass `event => getMcpPrompts({ event, ... })`.

```typescript
import { defineMcpPrompt, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const prompt1 = defineMcpPrompt({ ... })
const prompt2 = defineMcpPrompt({ ... })

export default defineMcpHandler({
  name: 'custom',
  prompts: [prompt1, prompt2],
})
```


# Examples & routing

## Complete Example

Here's a complete example of a custom handler:

```typescript [server/mcp/api-handler.ts]
import { z } from 'zod'
import { defineMcpTool, defineMcpResource, defineMcpPrompt, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const getUserTool = defineMcpTool({
  name: 'get-user',
  description: 'Get user information',
  inputSchema: {
    userId: z.string(),
  },
  handler: async ({ userId }) => {
    const user = await db.users.find(userId)
    return user
  },
})

const createUserTool = defineMcpTool({
  name: 'create-user',
  description: 'Create a new user',
  inputSchema: {
    name: z.string(),
    email: z.string().email(),
  },
  handler: async ({ name, email }) => {
    const user = await db.users.create({ name, email })
    return `User created: ${user.id}`
  },
})

// Define resources for this handler
const userResource = defineMcpResource({
  name: 'user',
  uri: 'api://users/{id}',
  handler: async (uri, variables) => {
    const id = variables.id as string
    const user = await db.users.find(id)
    return {
      contents: [{
        uri: uri.toString(),
        mimeType: 'application/json',
        text: JSON.stringify(user),
      }],
    }
  },
})

// Define prompts for this handler
const userPrompt = defineMcpPrompt({
  name: 'user-help',
  description: 'Get help with user operations',
  handler: async () => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: 'How can I manage users?',
        },
      }],
    }
  },
})

// Export the handler
export default defineMcpHandler({
  name: 'api',
  version: '1.0.0',
  route: '/mcp/api',
  tools: [getUserTool, createUserTool],
  resources: [userResource],
  prompts: [userPrompt],
  browserRedirect: '/docs/api',
})
```

## Multiple Handlers

You can create multiple handlers in your application:

```text
server/
└── mcp/
    ├── migration.ts          # Migration handler
    ├── api-handler.ts        # API handler
    ├── admin-handler.ts      # Admin handler
    ├── tools/
    │   └── echo.ts           # Default handler tools
    ├── resources/
    │   └── readme.ts         # Default handler resources
    └── prompts/
        └── greeting.ts       # Default handler prompts
```

Each handler file should export a default handler definition:

```typescript [server/mcp/migration.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'migration',
  tools: [ ... ],
})
```

```typescript [server/mcp/api-handler.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'api',
  tools: [ ... ],
})
```

## Handler Routes

The handler's `name` determines where it will be mounted. By default, handlers are accessible at `/mcp/:name` where `:name` is the handler's name:

- Handler with `name: 'migration'` → mounted at `/mcp/migration`
- Handler with `name: 'api'` → mounted at `/mcp/api`
- Handler with `name: 'admin'` → mounted at `/mcp/admin`

You can also specify a custom route to override the default:

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'api',
  route: '/api/mcp/v1', // Custom route instead of /mcp/api
})
```

## Default vs Custom Handlers

| Feature   | Default Handler              | Default Handler Override (`index.ts`) | Custom Handler                 |
| --------- | ---------------------------- | ------------------------------------- | ------------------------------ |
| Route     | `/mcp` (via config)          | `/mcp` (via config)                   | `/mcp/:name` (or custom route) |
| Tools     | From `server/mcp/tools/`     | Custom or global                      | Defined in handler             |
| Resources | From `server/mcp/resources/` | Custom or global                      | Defined in handler             |
| Prompts   | From `server/mcp/prompts/`   | Custom or global                      | Defined in handler             |
| Name      | From config                  | Custom or config                      | Handler name (required)        |
| Version   | From config                  | Custom or config                      | Handler version                |


# Sharing & practices

## Use Cases

### 1. Feature Separation

Separate different features into different handlers:

```typescript [server/mcp/user-management.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'users',
  tools: [getUserTool, createUserTool, updateUserTool],
})
```

```typescript [server/mcp/content-management.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'content',
  tools: [createPostTool, updatePostTool, deletePostTool],
})
```

### 2. Versioned APIs

Create versioned handlers:

```typescript [server/mcp/api-v1.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'api-v1',
  version: '1.0.0',
  route: '/api/v1/mcp',
  tools: [ ... ],
})
```

```typescript [server/mcp/api-v2.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'api-v2',
  version: '2.0.0',
  route: '/api/v2/mcp',
  tools: [ ... ],
})
```

### 3. Domain-Specific Handlers

Organize by domain:

```typescript [server/mcp/ecommerce.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'ecommerce',
  tools: [addToCartTool, checkoutTool, getProductsTool],
})
```

```typescript [server/mcp/analytics.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'analytics',
  tools: [getStatsTool, generateReportTool],
})
```

## Sharing Tools Between Handlers

::callout{color="primary" icon="i-lucide-arrow-right"}
Prefer the 

[multi-handler organization](https://mcp-toolkit.nuxt.dev/handlers/organization)

 features (folder convention plus the 

`getMcp*`

 function form) for any new handler. The patterns below remain fully supported for explicit, hand-built handler configs.
::

You can share tool definitions between handlers by exporting them from a separate file:

```typescript [server/mcp/shared-tools.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export const sharedTool = defineMcpTool({
  name: 'shared-tool',
  description: 'A shared tool',
  inputSchema: {
    input: z.string(),
  },
  handler: async ({ input }) => `Shared: ${input}`,
})
```

```typescript [server/mcp/handler1.ts]
import { sharedTool } from './shared-tools'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler1',
  tools: [sharedTool],
})
```

```typescript [server/mcp/handler2.ts]
import { sharedTool } from './shared-tools'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler2',
  tools: [sharedTool],
})
```

## File Organization

Two conventions can coexist in `server/mcp/`:

```text
server/
└── mcp/
    ├── index.ts              # Default handler override (optional)
    ├── migration.ts          # Top-level handler (defaults to all tools)
    ├── tools/                # Default handler tools (orphans)
    ├── resources/            # Default handler resources (orphans)
    ├── prompts/              # Default handler prompts (orphans)
    └── handlers/             # ✨ Named handler folders (recommended)
        ├── admin/
        │   ├── index.ts      # Required: defineMcpHandler({ ... })
        │   ├── tools/        # Auto-attached to /mcp/admin
        │   └── prompts/
        └── apps/
            ├── index.ts
            └── tools/        # Auto-attached to /mcp/apps
```

::callout{color="primary" icon="i-lucide-lightbulb"}
The 

`index.ts`

 at the root of 

`server/mcp/`

 overrides the default handler configuration. Inside a 

`handlers/<name>/`

 directory, 

`index.ts`

 is required (even as a one-liner: 

`export default defineMcpHandler({})`

) — it's what registers the 

`/mcp/<name>`

 route.
::

## Best Practices

1. **Use descriptive names**: Make handler names clear and specific
2. **Group related functionality**: Put related tools/resources together
3. **Version your handlers**: Use semantic versioning for handler versions
4. **Document your handlers**: Add comments explaining what each handler does
5. **Keep handlers focused**: Each handler should have a clear, single purpose

## Next Steps

- [Multi-handler organization](https://mcp-toolkit.nuxt.dev/handlers/organization) - Folder convention + `getMcp*` function form
- [Code Mode](https://mcp-toolkit.nuxt.dev/advanced/code-mode) - Orchestrate tools with LLM-generated JavaScript
- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) - Add authentication and logging
- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) - Conditionally register definitions
- [Configuration](https://mcp-toolkit.nuxt.dev/getting-started/configuration) - Configure the default handler
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Create tools for your handlers
- [Examples](https://mcp-toolkit.nuxt.dev/examples/common-patterns) - See more handler examples


# Multi-handler organization

When you have more than one named handler (`/mcp/admin`, `/mcp/apps`, `/mcp/api-v2`…) you usually want every tool, resource, and prompt to land in **exactly one place** without writing manual filters.

The toolkit gives you **one mechanism** to attribute definitions and **one escape hatch** for everything else.

## A. Folder convention (the way to attribute)

Place named-handler definitions under `server/mcp/handlers/<name>/`. Every file under `tools/`, `resources/`, or `prompts/` is auto-attached to that handler via `_meta.handler`.

```bash
server/mcp/
├── tools/                          # → default handler
├── resources/                      # → default handler
├── prompts/                        # → default handler
└── handlers/
    ├── admin/
    │   ├── index.ts                # defineMcpHandler({ middleware: requireAdmin })
    │   ├── tools/
    │   │   └── delete-user.ts      # → handler 'admin' (auto)
    │   └── prompts/
    │       └── help.ts             # → handler 'admin' (auto)
    └── widgets/
        ├── index.ts                # defineMcpHandler({})
        └── tools/
            └── carousel.ts         # → handler 'widgets' (auto)
```

The handler `name` is inferred from the directory name and **wins over** anything you set in `index.ts`.

::callout{color="primary" icon="i-lucide-lightbulb"}
`index.ts`

 is required even if it's a one-liner: 

`export default defineMcpHandler({})`

. It's what registers the 

`/mcp/<name>`

 route and lets you add 

`middleware`

, 

`description`

, 

`experimental_codeMode`

, etc.
::

## B. Function form (the escape hatch)

For cross-cutting cases — "every tool tagged X", "every orphan", "everything except this group" — pass a function that calls one of the `getMcp*` helpers:

```typescript [server/mcp/handlers/searchable/index.ts]
import { defineMcpHandler, getMcpTools } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  // Every tool tagged 'searchable', regardless of folder.
  tools: event => getMcpTools({ event, tags: ['searchable'] }),
})
```

`getMcpTools`, `getMcpResources`, and `getMcpPrompts` return the **raw** definition objects (with handlers and Zod schemas intact) — exactly what `defineMcpHandler` expects. They accept the same options as their `listMcp*` counterparts: `event`, `group`, `tags`, `handler`, `orphansOnly`. See [Listing definitions](https://mcp-toolkit.nuxt.dev/advanced/listing-definitions) for the full reference.

## Default handler strategy

The default `/mcp` route obeys `mcp.defaultHandlerStrategy` in `nuxt.config.ts`:

::field-group
  :::field{name="`'orphans'`" type="default"}
  Only definitions 

  **not attached**

   to any named handler are exposed. Each definition shows up in exactly one place.
  :::

  :::field{name="`'all'`"}
  Every discovered definition is exposed (the pre-multi-handler behaviour). Useful when you want a "kitchen sink" route on top of specialized ones.
  :::
::

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  mcp: {
    defaultHandlerStrategy: 'orphans', // (default)
  },
})
```

::callout{color="primary" icon="i-lucide-shield-check"}
**Zero-effort back-compat**

: when no definition uses the folder convention, 

`'orphans'`

 behaves exactly like 

`'all'`

 — every definition is an orphan, so it's exposed. Existing apps don't change behaviour after upgrading.
::

## Resolution rule

The toolkit picks where each definition shows up using a single rule, deterministic by file location:

| Handler config file                                    | Default behaviour for `tools | resources | prompts: undefined` |
| ------------------------------------------------------ | -------------------------------------------------------------- |
| `server/mcp/index.ts` (default route)                  | Obeys `defaultHandlerStrategy`                                 |
| `server/mcp/handlers/<name>/index.ts` (folder handler) | Definitions attributed to `<name>`                             |
| `server/mcp/<name>.ts` (top-level handler)             | Every discovered definition (back-compat)                      |
| Any (array)                                            | Used as-is                                                     |
| Any (function `(event) => T[]`)                        | Called per request                                             |

::callout{color="info" icon="i-lucide-info"}
The distinction between "folder handler" and "top-level handler" is purely about where the file lives — not magic. The loader injects 

`_meta.handler`

 on folder handlers; the runtime reads it to choose the default.
::

## Migration tips

1. **Start small.** Move one handler at a time into `handlers/<name>/`. Existing `tools: [...]` and `tools: ev => [...]` keep working untouched.
2. **Drop manual filters.** If you were doing `tools: allTools.filter(t => t._meta?.group === 'apps')`, move those tools to `handlers/apps/tools/` and let the system attribute them automatically.
3. **Wrap-everything handlers.** A top-level handler that wraps every tool (e.g. a code-mode wrapper at `mcp/codemode.ts`) keeps its current behaviour — top-level handlers default to the full pool. To filter, pass a function: `tools: ev => getMcpTools({ event: ev, ... })`.
4. **Force the old behaviour.** Set `mcp.defaultHandlerStrategy: 'all'` to keep `/mcp` exposing everything even after you adopt folder handlers.

## See also

- [Listing definitions](https://mcp-toolkit.nuxt.dev/advanced/listing-definitions) — programmatic access to summaries and raw defs (`listMcp*` / `getMcp*`).
- [Sharing & practices](https://mcp-toolkit.nuxt.dev/handlers/sharing-practices) — handler organization patterns and best practices.
- [Dynamic definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) — per-request `enabled()` guards on individual definitions.


# Apps

## What are MCP Apps?

MCP Apps are **interactive HTML widgets** returned by an MCP tool and rendered inline by compatible hosts. Instead of streaming back text, your tool ships a small UI that the user can read, scroll, filter, and click — connected back to your server through a typed message bridge.

They follow the [MCP UI proposal (SEP-1865)](https://modelcontextprotocol.io){rel="&#x22;nofollow&#x22;"}: a tool returns a `text/html;profile=mcp-app` resource referenced by `ui://`, the host loads it inside a sandboxed `iframe`, and the iframe talks back over `postMessage`.

`@nuxtjs/mcp-toolkit` makes that authoring experience feel like writing a regular Nuxt page:

- One **Vue SFC** per app in `app/mcp/`.
- A `defineMcpApp` macro inside `<script setup>` declares the tool, schema, and server handler.
- A `useMcpApp()` composable gives you reactive data, host context, and a typed bridge to the host.
- The toolkit bundles the SFC into a single self-contained HTML file at build time and serves it from your MCP endpoint.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Scaffold a new MCP App (Vue SFC)
icon: i-lucide-app-window
---
Create a new MCP App in my Nuxt app using @nuxtjs/mcp-toolkit.

- Create a Vue SFC in app/mcp/ (e.g. app/mcp/color-picker.vue)
- Use defineMcpApp({ description, inputSchema, handler }) inside
- inputSchema uses Zod; handler runs server-side and returns { structuredContent }
- handler can call any Nuxt API route via $fetch — keep heavy data work on the server
- In the template, call useMcpApp :t-payload[() to get { data, loading, hostContext, sendPrompt, callTool, openLink }]
- data is hydrated from structuredContent on first render — no extra request
- Use sendPrompt(text) to push a follow-up into the chat that triggers another tool/app
- Use callTool(name, params) to re-invoke an MCP tool and refresh data in place
- Use openLink(url) to ask the host to open a URL outside the iframe
- Add CSP allow-lists with csp: { resourceDomains, connectDomains } if you load images or call external APIs
- To route the app to a dedicated handler, either drop the SFC under `app/mcp/<handler>/` or set `attachTo: '<handler>'` (string literal) on `defineMcpApp`. `group` and `tags` are also accepted as literals.
- Make the layout fluid (no fixed heights); hosts often render the iframe inline at variable widths

Docs: <https://mcp-toolkit.nuxt.dev/apps/overview>{rel=""nofollow""}
::

## Going further

::card-group
  :::card
  ---
  color: neutral
  icon: i-lucide-cog
  title: MCP Apps internals
  to: https://mcp-toolkit.nuxt.dev/advanced/mcp-apps-internals
  ---
  Build pipeline, host bridge protocol, security model, and advanced composition patterns.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-network
  title: Multi-handler organization
  to: https://mcp-toolkit.nuxt.dev/apps/authoring#routing-apps-to-a-specific-handler
  ---
  Route apps to dedicated MCP endpoints (e.g. 

  `/mcp/finder`

  ) via sub-folders or 

  `attachTo`

  .
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-shield-check
  title: Authenticate clients
  to: https://mcp-toolkit.nuxt.dev/examples/authentication
  ---
  Hide apps from anonymous callers with the same patterns as tools.
  :::
::

The rest of this section assumes you are comfortable with [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) (Zod, handlers) and have read [Connection](https://mcp-toolkit.nuxt.dev/getting-started/connection) for MCP URLs in dev and production.


# Authoring & defineMcpApp

## Quick Start

A complete app — schema, server handler, UI — in one file:

```vue [app/mcp/color-picker.vue]
<script setup lang="ts">
import { z } from 'zod'

interface PalettePayload {
  base: string
  swatches: { name: string, hex: string }[]
}

defineMcpApp({
  description: 'Pick a colour and preview a 5-tone palette.',
  inputSchema: {
    base: z.string().describe('Hex colour to anchor the palette, e.g. #2563eb'),
  },
  handler: async ({ base }): Promise<{ structuredContent: PalettePayload }> => {
    const swatches = await $fetch<{ name: string, hex: string }[]>('/api/palette', {
      query: { base },
    })
    return { structuredContent: { base, swatches } }
  },
})

const { data, loading, sendPrompt } = useMcpApp<PalettePayload>()
</script>

<template>
  <main class="picker">
    <p v-if="loading">
      Mixing colours…
    </p>
    <ul v-else-if="data" class="swatches">
      <li v-for="s in data.swatches" :key="s.hex">
        <button
          type="button"
          :style="{ background: s.hex }"
          @click="sendPrompt(`Use ${s.name} (${s.hex}) as the primary colour.`)"
        >
          {{ s.name }}
        </button>
      </li>
    </ul>
  </main>
</template>

<style scoped>
.picker { padding: 16px; font-family: system-ui, sans-serif; }
.swatches { display: grid; grid-template-columns: repeat(5, 1fr); gap: 8px; padding: 0; list-style: none; }
.swatches button { width: 100%; aspect-ratio: 1; border-radius: 8px; border: 0; cursor: pointer; }
</style>
```

That's it. The toolkit:

1. Detects `defineMcpApp` and **registers an MCP tool** named `color-picker` (from the filename).
2. Generates a **UI resource** at `ui://mcp-app/color-picker` exposing `text/html;profile=mcp-app`.
3. Bundles the SFC + assets into a single HTML file with [`vite-plugin-singlefile`](https://github.com/richardtallent/vite-plugin-singlefile){rel="&#x22;nofollow&#x22;"}.
4. Wires the `handler`'s `structuredContent` into the iframe so the UI hydrates **without a second round-trip**.

## File Convention

MCP Apps live in &#x2A;*`app/mcp/`** by default (not `server/mcp/`). Change the app-side directory with `mcp.appsDir` in `nuxt.config.ts`. They sit on the client side of Nuxt because they author Vue components — but the `handler` you declare runs server-side, just like a tool.

```bash
app/
└── mcp/
    ├── color-picker.vue    # → tool: color-picker, resource: ui://mcp-app/color-picker
    └── admin/
        └── audit-log.vue   # → tool: audit-log
```

::callout{color="info" icon="i-lucide-info"}
Co-locate helpers next to the SFC (e.g. 

`format.ts`

) — the bundler inlines them. Keep data generation in 

`server/api/`

 and call it via 

`$fetch`

 from the handler.
::

### Auto-Generated Name & Title

Like tools and resources, `name` and `title` are inferred from the filename:

| File                  | Name           | Title          |
| --------------------- | -------------- | -------------- |
| `color-picker.vue`    | `color-picker` | `Color Picker` |
| `weather-card.vue`    | `weather-card` | `Weather Card` |
| `admin/audit-log.vue` | `audit-log`    | `Audit Log`    |

Override either by passing `name` / `title` to `defineMcpApp`.

### Routing Apps to a Specific Handler

By default, every app is attached to the implicit `apps` handler and only surfaces on `/mcp/apps`. Two ways to route an app to a different named handler:

**1. Sub-folder convention** — the first sub-directory under `app/mcp/` becomes the handler attribution:

```bash
app/
└── mcp/
    ├── color-picker.vue          # → /mcp/apps (default)
    ├── finder/
    │   └── stay-finder.vue       # → /mcp/finder
    └── checkout/
        └── stay-checkout.vue     # → /mcp/checkout
```

Pair each handler folder with `server/mcp/handlers/<name>/index.ts`:

```ts [server/mcp/handlers/finder/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({})
```

**2. Explicit `attachTo` override** — overrides the sub-folder default if both are present:

```vue [app/mcp/stay-finder.vue]
<script setup lang="ts">
defineMcpApp({
  attachTo: 'finder',
  group: 'stays',
  tags: ['searchable'],
  // ...
})
</script>
```

The generated tool and resource carry `_meta.handler = 'finder'`, top-level `group = 'stays'`, and `tags = ['searchable']`. Filter on them with `getMcpTools({ handler: 'finder' })`, `getMcpTools({ tags: ['searchable'] })`, etc.

## `defineMcpApp`

A macro — like `definePageMeta` — extracted at build time and **stripped from the browser bundle**. The fields it accepts:

```ts
defineMcpApp({
  name?: string                          // Override auto-derived name
  title?: string                         // Override auto-derived title
  description?: string                   // Shown to the LLM to help it pick this app
  inputSchema?: ZodRawShape              // Validates tool input on the server
  handler?: (args, extra) => Result      // Runs server-side; defaults to (args) => ({ structuredContent: args })
  csp?: McpAppCsp | false                // Tighten or disable iframe CSP
  attachTo?: string                      // Named MCP handler this app routes to (default: 'apps' or sub-folder)
  group?: string                         // Top-level group label (default: same as attachTo)
  tags?: string[]                        // Top-level tags forwarded to the generated tool
  _meta?: Record<string, unknown>        // Extra _meta fields surfaced to the host
})
```

::callout{color="info" icon="i-lucide-info"}
`attachTo`

, 

`group`

, and 

`tags`

 must be 

**literals**

 (

`'finder'`

, 

`['a', 'b']`

) — the toolkit reads them statically at build time to route the generated tool and resource. A dynamic expression (

`attachTo: someVar`

) fails the build with a clear error.
::

### Server Handler

The `handler` runs in your Nitro server, not in the iframe. It receives validated input and returns `structuredContent` that the UI hydrates from. **Treat it like a tool handler** — call APIs, query a database, hit `$fetch`:

```ts
defineMcpApp({
  description: 'Pick a colour and preview a 5-tone palette.',
  inputSchema: {
    base: z.string().describe('Hex colour to anchor the palette, e.g. #2563eb'),
  },
  handler: async ({ base }) => {
    const swatches = await $fetch('/api/palette', { query: { base } })
    return { structuredContent: { base, swatches } }
  },
})
```

::callout{color="primary" icon="i-lucide-zap"}
Returning 

`structuredContent`

 from the handler 

**inlines the data into the HTML**

 as a 

`<script type="application/json">`

. The iframe boots with full data already present — no extra fetch, no flicker.
::

If you omit `handler`, the toolkit defaults to `(args) => ({ structuredContent: args })`. Useful for stateless apps that only need the input echoed back.

### Sharing Types Between Server & UI

Place shared types in Nuxt's `shared/types/` directory — they're **auto-imported globally** in both the SFC and your API endpoints, no `import` statement required:

```ts [shared/types/palette.ts]
export interface Swatch { name: string, hex: string }
export interface PalettePayload { base: string, swatches: Swatch[] }
```

```ts [server/api/palette.get.ts]
export default defineEventHandler(async (event): Promise<PalettePayload> => {
  const { base } = getQuery(event)
  return { base: String(base), swatches: buildPalette(String(base)) }
})
```

```vue [app/mcp/color-picker.vue]
<script setup lang="ts">
defineMcpApp({
  inputSchema: { base: z.string() },
  handler: async ({ base }): Promise<{ structuredContent: PalettePayload }> => ({
    structuredContent: await $fetch('/api/palette', { query: { base } }),
  }),
})

const { data } = useMcpApp<PalettePayload>()
</script>
```

Type-only references are stripped from the browser bundle by esbuild — nothing has to resolve inside the iframe at runtime.


# useMcpApp() bridge

## `useMcpApp()`

The single client-side composable, **auto-imported into every MCP App SFC**. It returns everything the iframe needs to talk to the host:

```ts
const {
  initialData,  // Ref<T | null>          — snapshot of the handler payload at mount, never updated
  data,         // Ref<T | null>          — hydrated from structuredContent, refreshed by callTool
  loading,      // Ref<boolean>           — true until first payload arrives
  error,        // Ref<Error | null>      — bridge / transport / payload errors
  pending,      // Ref<boolean>           — true while a callTool() is in flight
  hostContext,  // Ref<HostContext | null> — theme, displayMode, locale, …
  callTool,     // (name, params?) => Promise<T | null> — re-invoke any MCP tool
  sendPrompt,   // (prompt: string) => void              — push a message into the chat
  openLink,     // (url: string) => void                 — ask the host to open a URL
} = useMcpApp<MyPayload>()
```

Pass your payload type as the generic to get full inference downstream.

### `initialData` & `data`

`initialData` is a **frozen snapshot** of the handler's `structuredContent` inlined at build time (or `window.openai.toolOutput` on ChatGPT). It never changes — use it for bootstrap values such as IDs or query params that later `callTool` results might overwrite in `data`.

`data` is **already populated on first render** when the handler returns `structuredContent`, then refreshed by `callTool` or host `tool-result` pushes. `loading` starts as `true` and becomes `false` after the first payload arrives. Use `pending` for in-flight `callTool()` refreshes:

```vue
<script setup lang="ts">
const { initialData, data, callTool } = useMcpApp<{ listId: string }>()

async function refresh() {
  const result = await callTool('list_todos', { listId: initialData.value!.listId })
  // `data` now holds the latest tool result; `initialData` still has `{ listId }`
}
</script>
```

```vue
<template>
  <section v-if="loading" class="skeleton" />
  <section v-else-if="data" class="content">
    {{ data.swatches.length }} swatches from {{ data.base }}
  </section>
</template>
```

### `hostContext`

The host hands the iframe a context object during the `ui/initialize` handshake. Use it to **adapt to dark mode, fullscreen, or a fixed iframe size**:

```ts
interface HostContext {
  theme?: 'light' | 'dark'
  displayMode?: 'inline' | 'fullscreen' | 'pip'
  containerDimensions?: { width?: number, height?: number, maxWidth?: number, maxHeight?: number }
  locale?: string
  timeZone?: string
  platform?: 'web' | 'desktop' | 'mobile'
}
```

```vue
<script setup lang="ts">
const { hostContext } = useMcpApp()
const isDark = computed(() => hostContext.value?.theme === 'dark')
const isFullscreen = computed(() => hostContext.value?.displayMode === 'fullscreen')
</script>

<template>
  <main :data-theme="isDark ? 'dark' : 'light'" :data-mode="isFullscreen ? 'fullscreen' : 'inline'">
    …
  </main>
</template>
```

::callout{color="info" icon="i-lucide-info"}
`hostContext`

 is 

`null`

 on the very first paint and populates after the handshake (typically <50 ms). Always use a fallback in your template.
::

### `sendPrompt(prompt)` — Follow-Ups

Push a message into the chat as if the user had typed it. The LLM then routes it like any other request — including invoking another MCP App:

```vue
<button @click="sendPrompt(`Use ${swatch.name} (${swatch.hex}) as the brand colour.`)">
  Use this colour
</button>
```

The host receives the prompt as if the user had typed it. The LLM may reply, call another tool, or open a different MCP App in response — **app-to-app workflows** fall out of this primitive.

::callout{color="warning" icon="i-lucide-triangle-alert"}
Follow-ups are best-effort. Hosts that implement 

`ui/message`

 forward the prompt cleanly. ChatGPT acknowledges the request but doesn't always re-render the next tool inline (an upstream limitation).
::

### `callTool(name, params)` — In-Place Refresh

Re-invoke any MCP tool from the iframe. The result replaces `data` automatically:

```vue
<script setup lang="ts">
const { data, pending, callTool } = useMcpApp<PalettePayload>()

async function refresh(base: string) {
  await callTool('color-picker', { base })
}
</script>
```

Use this for filters, pagination, refresh buttons — anything that changes the query without a full chat round-trip.

### `openLink(url)`

Sandbox iframes can't open windows. `openLink` asks the host to do it for you (e.g. open a booking confirmation in a new browser tab):

```vue
<button @click="openLink(`https://example.com/colors/${swatch.hex.slice(1)}`)">
  View on the web
</button>
```

::callout{color="info" icon="i-lucide-info"}
Add the target host to 

`csp.connectDomains`

 if you also need to 

`fetch()`

 it from the iframe.
::


# CSP & build pipeline

## CSP & Resource Allow-Lists

The toolkit injects a **conservative Content Security Policy** into every app HTML. By default the iframe can:

- Run only its own inline script.
- Render images and styles only from the same response.
- Talk over `postMessage` to its parent host.

If your UI needs external assets or APIs, allow them explicitly:

```vue [app/mcp/color-picker.vue]
<script setup lang="ts">
defineMcpApp({
  description: 'Pick a colour and preview a palette.',
  csp: {
    resourceDomains: ['https://images.unsplash.com'],
    connectDomains: ['https://api.example.com'],
  },
  handler: async ({ base }) => ({ structuredContent: await $fetch('/api/palette', { query: { base } }) }),
})
</script>
```

The CSP is mirrored into `_meta.ui.csp` (and `openai/widgetCSP` for ChatGPT) so hosts that enforce CSP at the iframe level pick up the same rules.

::callout{color="warning" icon="i-lucide-shield"}
Pass 

`csp: false`

 only as a last resort — and only if you fully control the assets the iframe loads. The default policy is what makes apps safe to render across hosts.
::

| Field             | What it allows                                                |
| ----------------- | ------------------------------------------------------------- |
| `resourceDomains` | `<img>`, `<style>`, `<link>`, fonts loaded from these origins |
| `connectDomains`  | `fetch()`, `XHR`, `WebSocket`, `EventSource` to these origins |

Origins should use `http(s)://` or `ws(s)://`. The toolkit rejects empty values, unsupported URL schemes, whitespace, quotes, and semicolons before the app response is served.

## How It's Wired

Behind the scenes, each `.vue` file under the configured apps directory becomes **three artifacts** at build time:

1. A **tool definition** registered on your MCP handler (input schema, description, server handler).
2. A **UI resource** at `ui://mcp-app/<name>` returning `text/html;profile=mcp-app`.
3. A **single-file HTML bundle** of the Vue SFC (Vue runtime, your code, scoped CSS, assets) inlined into the resource response.

When the LLM calls the tool:

1. Your `handler` runs on the server and produces `structuredContent`.
2. The toolkit injects that data into the bundled HTML as `<script type="application/json" id="__mcp_app_data__">…</script>`.
3. The host returns the resource to the user; its iframe boots and `useMcpApp()` reads the inline data into `data` synchronously.
4. From there, the iframe and the host exchange messages over a JSON-RPC bridge for `callTool`, `sendPrompt`, `openLink`, and theme/size updates.

::callout{color="primary" icon="i-lucide-zap"}
Everything ships in 

**one HTML response**

. No extra HTTP request from the iframe, no waterfall, no flicker.
::


# Testing & publishing

## Host compatibility

| Host                               | Render | `sendPrompt` | `callTool` | `openLink` | Notes                                                                                                                             |
| ---------------------------------- | ------ | ------------ | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Cursor**                         | ✅      | ✅            | ✅          | ✅          | Tested with the JSON-RPC bridge and legacy ready/resize messages.                                                                 |
| **ChatGPT (Apps SDK)**             | ✅      | ⚠️           | ✅          | ✅          | Uses `window.openai` when available. Follow-ups are sent, but the next tool is not always rendered inline.                        |
| **MCP UI / Inspector-style hosts** | ✅      | varies       | varies     | varies     | The bridge emits spec JSON-RPC messages plus legacy `mcp-ui` envelopes where useful. Verify each host before documenting support. |

The bridge auto-detects the host on handshake and adapts to its protocol — modern JSON-RPC for MCP UI hosts, the legacy `mcp-ui` envelope for older clients, the ChatGPT Apps SDK globals when present. Your code just calls `useMcpApp()`.

## Local test loop

MCP Apps use the same streamable HTTP endpoint as your tools, resources, and prompts. The default route is `/mcp` unless you set `mcp.route` in `nuxt.config`.

Start your Nuxt app:

::code-group
```bash [pnpm]
pnpm dev
```

```bash [npm]
npm run dev
```

```bash [yarn]
yarn dev
```

```bash [bun]
bun dev
```
::

Your local MCP URL is:

```txt
http://localhost:3000/mcp
```

Use the [MCP Inspector](https://mcp-toolkit.nuxt.dev/getting-started/inspector), `npx @modelcontextprotocol/inspector@latest`, or the **MCP** panel in **Nuxt DevTools** first. Confirm that:

- the app SFC appears as a tool, for example `color-picker` or `release-control`;
- calling the tool returns `structuredContent`;
- the tool result includes a `text/html;profile=mcp-app` resource;
- the resource URI looks like `ui://mcp-app/<name>`.

Some clients can call the tool but cannot render the iframe. Use a host with MCP Apps support when validating the UI itself.

## Test in ChatGPT with ngrok

ChatGPT requires a public HTTPS endpoint, even for local development. Tunnel your local Nuxt server:

```bash
ngrok http 3000
```

ngrok prints a forwarding URL:

```txt
Forwarding https://your-subdomain.ngrok-free.dev -> http://localhost:3000
```

Use the `/mcp` route on that origin:

```txt
https://your-subdomain.ngrok-free.dev/mcp
```

In ChatGPT:

1. Enable **Developer Mode** in **Settings** → **Apps** → **Advanced settings**.
2. Open **Settings** → **Apps**.
3. Click **Create app**.
4. Enter your public MCP URL, including `/mcp`.
5. Enable the app and start a new chat.
6. Select your app from the composer before prompting the model.

Mention the app with `@` so ChatGPT routes the prompt through your connector:

```txt
@Weather App What is the weather in London?
```

Then test the iframe behaviour:

- click a button that calls `callTool()` and confirm the widget updates without a new chat turn;
- click a button that calls `sendPrompt()` and confirm a follow-up message appears in the conversation;
- click a button that calls `openLink()` and confirm ChatGPT opens or prompts for the external URL;
- watch your Nuxt terminal and ngrok dashboard for POST requests to `/mcp`.

If you expose local dev through ngrok, allow the tunnel host in Vite:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vite: {
    server: {
      allowedHosts: ['.ngrok-free.dev', '.ngrok.app'],
    },
  },
})
```

For cross-origin hosts such as ChatGPT, configure MCP origin checks intentionally:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  mcp: {
    security: {
      allowedOrigins: '*',
    },
  },
})
```

Use `'*'` only for demos or public read-only surfaces. For production apps with private data or real side effects, use a list of trusted origins.

## Deploy to Vercel or another cloud

MCP Apps do **not** use a second URL. Deploy the Nuxt app and connect ChatGPT to the same MCP route:

```txt
https://your-project.vercel.app/mcp
```

The toolkit auto-detects `_meta.ui.domain` from common hosting variables:

- `NUXT_PUBLIC_APP_URL`;
- Vercel: `VERCEL_PROJECT_PRODUCTION_URL`, `VERCEL_URL`;
- Netlify: `URL`;
- Render: `RENDER_EXTERNAL_URL`;
- Railway: `RAILWAY_PUBLIC_DOMAIN`;
- Fly: `FLY_APP_NAME`.

If you need to override the detected value, set it explicitly:

```vue [app/mcp/my-app.vue]
<script setup lang="ts">
defineMcpApp({
  _meta: {
    ui: {
      domain: 'https://my-app.example.com',
    },
  },
})
</script>
```

For Vercel, make sure your build includes the MCP Apps bundling dependencies from the toolkit version you deploy. If you test an unreleased package, use a fresh `pkg.pr.new` build or install the required build dependencies in the app until the package is published.

## Prepare for ChatGPT submission

OpenAI reviews apps before broad distribution. Before submitting, check:

- your MCP server is publicly reachable over HTTPS;
- each app resource returns `text/html;profile=mcp-app`;
- each app tool has clear `description`, `inputSchema`, and behavior annotations;
- `_meta.ui.resourceUri` is present (the toolkit generates it);
- `_meta.ui.domain` is set or auto-detected;
- CSP is explicit for external images, scripts, fonts, APIs, or iframes;
- `structuredContent` is concise and safe for the model to read;
- large or widget-only data goes in `_meta`, not in `structuredContent`;
- OAuth, privacy policy, app name, screenshots, and test prompts are ready if your app needs public distribution.

When the host exposes the **Apps SDK** (`window.openai`) or enforces widget CSP, the toolkit mirrors your `csp&#x60; to &#x2A;*`_meta.ui.csp`*&#x2A; and &#x2A;*`openai/widgetCSP`**. Behaviour, especially `sendPrompt` and follow-up re-renders, can change between ChatGPT releases. Re-test your app before submitting or announcing support.

## Troubleshooting

### `403 Forbidden` from `/mcp`

The request reached your server but failed an origin or host check.

- For ChatGPT/ngrok demos, set `mcp.security.allowedOrigins` to `'*'` or to a trusted origin list.
- For Vite dev server tunnels, add the tunnel domain to `vite.server.allowedHosts`.
- Restart the Nuxt dev server after changing `nuxt.config.ts`.

### Widget does not render

Check the tool result:

- The resource MIME type must be `text/html;profile=mcp-app`.
- The resource URI should match `_meta.ui.resourceUri`.
- The host must support MCP Apps. Some MCP clients can call the tool but only display text.

### No `ui/*` messages arrive

The iframe loaded, but the host did not enable the MCP Apps bridge.

- Confirm the host renders the HTML as an MCP App resource, not as a plain file.
- Check the browser console inside the host devtools for CSP or sandbox errors.
- Test in Cursor or ChatGPT to compare host behaviour.

### CSP blocks images or fetch calls

Add explicit allow-lists:

```ts
defineMcpApp({
  csp: {
    resourceDomains: ['https://images.example.com'],
    connectDomains: ['https://api.example.com'],
  },
})
```

The toolkit mirrors these to `_meta.ui.csp` and `openai/widgetCSP` for hosts that enforce widget CSP.

### Vercel cannot find generated MCP App files

Use a toolkit version that includes the MCP Apps build fixes. Older unreleased builds may import `.nuxt/mcp-apps/gen/*.ts` at runtime, which does not exist inside the deployed Vercel function.

### `vite-plugin-singlefile` or `@vitejs/plugin-vue` is missing

Use a toolkit version that ships the MCP Apps bundling dependencies, or install them in the app while testing an unreleased build.

### ChatGPT keeps showing an old widget

ChatGPT can cache widget templates by URI. If you make a breaking UI change, change the resource URI or file name so hosts load a fresh template.

## Other clients

**Claude Code**, **Claude Desktop** (where remote MCP is enabled), **Cursor**, **VS Code**, and **Codex**-style clients connect to your server with the same MCP URL you use for tools. There is no separate “apps-only” endpoint.

Web and mobile ChatGPT/Claude apps may not render MCP UI widgets on every release channel. Always verify inline iframes on the product version you support.

Prefer Cursor as the main development vehicle when debugging the JSON-RPC UI bridge; it is the most exercised environment in this module’s test suite.

## Related

- [CSP & build pipeline](https://mcp-toolkit.nuxt.dev/apps/csp-and-wiring) — how HTML and `_meta` are produced.
- [Patterns & limits](https://mcp-toolkit.nuxt.dev/apps/patterns-reference) — iframe constraints and API cheat sheet.
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) — optional `https://…/mcp/apps` surface if you split apps from other tools.
- [OpenAI: Build your MCP server](https://developers.openai.com/apps-sdk/build/mcp-server){rel="&#x22;nofollow&#x22;"}
- [OpenAI: Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt){rel="&#x22;nofollow&#x22;"}
- [OpenAI: Test your integration](https://developers.openai.com/apps-sdk/deploy/testing){rel="&#x22;nofollow&#x22;"}
- [OpenAI: Submit and maintain your app](https://developers.openai.com/apps-sdk/deploy/submission){rel="&#x22;nofollow&#x22;"}
- [OpenAI: App submission guidelines](https://developers.openai.com/apps-sdk/app-submission-guidelines){rel="&#x22;nofollow&#x22;"}


# Patterns & limits

## Patterns

### Skeletons during `callTool`

`pending` flips to `true` only during in-flight `callTool` calls — perfect for partial UI updates without losing the previous data:

```vue
<button :disabled="pending" @click="callTool('color-picker', { base: nextBase })">
  {{ pending ? 'Mixing…' : 'Try this colour' }}
</button>
```

### Adapting to fullscreen vs inline

Hosts can mount your app inline (small) or expand it fullscreen. Switch layout primitives:

```vue
<section :class="['rail', isFullscreen && 'rail-grid']">
  <!-- horizontal scroll inline, CSS grid in fullscreen -->
</section>
```

### App-to-app workflows

Use `sendPrompt` from app A and let the LLM dispatch to app B. The user perceives a smooth transition; the LLM stays in the loop and can carry parameters through:

```vue
<button @click="sendPrompt(`Generate a typography scale for ${swatch.hex}.`)">
  Pair with type
</button>
```

The LLM picks the right tool from the prompt — keep names predictable.

### Co-locating CSS

Use scoped styles or any CSS-in-JS solution that emits inline styles. The bundler inlines all styles into the HTML; **no external CSS request fires from the iframe**.

## What You Cannot Do (Yet)

MCP Apps run inside an isolated `iframe` with no access to your Nuxt runtime context. That means:

- ❌ **Nuxt UI / Nuxt Image / NuxtLink** — they need the parent Nuxt app's runtime.
- ❌ **Auto-imported Nuxt composables** (`useFetch`, `useState`, `useRoute`, `useNuxtApp`, …).
- ❌ **Pinia stores or app-level plugins** — different module graph.
- ❌ **Cookies, headers, session from the parent page** — sandboxed origin.

What you can use:

- ✅ Vue 3 + Composition API (auto-imported: `ref`, `computed`, `watch`, `onMounted`, …).
- ✅ `useMcpApp()` — the only toolkit composable in the iframe.
- ✅ `$fetch` inside `handler` (server side) — call any Nuxt API.
- ✅ Co-located `.ts`/`.css` helpers next to the SFC (the bundler inlines them).
- ✅ Headless UI libraries (Reka UI, Headless UI Vue, Floating UI) — they're framework-agnostic.

::callout{color="info" icon="i-lucide-info"}
Need rich components? Build a small co-located design system in your apps directory, such as 

`app/mcp/_components/`

 — it gets bundled into every app that imports it. Or pull in a headless library that doesn't depend on the host runtime.
::

## Reference

| API                   | Where            | Purpose                                                                                             |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `defineMcpApp()`      | `<script setup>` | Declare the tool, schema, handler, CSP. Stripped from the browser bundle.                           |
| `useMcpApp<T>()`      | SFC body         | Reactive `initialData` / `data` / `loading` / `hostContext` + `callTool`, `sendPrompt`, `openLink`. |
| `csp.resourceDomains` | `defineMcpApp`   | Allow-list image / font / style origins.                                                            |
| `csp.connectDomains`  | `defineMcpApp`   | Allow-list `fetch` / `XHR` / `WebSocket` origins.                                                   |
| `_meta`               | `defineMcpApp`   | Extra `_meta` fields surfaced to the host alongside `ui.resourceUri` and `ui.csp`.                  |

Looking for the underlying tool / resource APIs? See [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) and [Resources](https://mcp-toolkit.nuxt.dev/resources/overview).


# Customize MCP definition paths

## Default Path Structure

By default, the module looks for definitions in:

```text
server/
└── mcp/
    ├── tools/
    │   └── # Tool definitions
    ├── resources/
    │   └── # Resource definitions
    └── prompts/
        └── # Prompt definitions
```

## Changing the Base Directory

Change the base directory using the `dir` configuration option:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    dir: 'my-mcp', // Look in server/my-mcp/ instead of server/mcp/
  },
})
```

This will look for definitions in:

```text
server/
└── my-mcp/
    ├── tools/
    │   └── # Tool definitions
    ├── resources/
    │   └── # Resource definitions
    └── prompts/
        └── # Prompt definitions
```

## Extending Paths with Hooks

For more advanced use cases, use the `mcp:definitions:paths` hook to add additional directories to scan. This is useful when you want to share definitions across multiple modules or layers.

### Using the Hook in nuxt.config.ts

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Add additional paths for tools
      paths.tools.push('shared/tools')

      // Add additional paths for resources
      paths.resources.push('shared/resources')

      // Add additional paths for prompts
      paths.prompts.push('shared/prompts')
    },
  },
})
```

### Using the Hook in a Custom Module

```typescript [my-module.ts]
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('mcp:definitions:paths', (paths) => {
      // Add additional paths for tools
      paths.tools.push('shared/tools')

      // Add additional paths for resources
      paths.resources.push('shared/resources')

      // Add additional paths for prompts
      paths.prompts.push('shared/prompts')
    })
  },
})
```

## Path Structure

The `paths` object has the following structure:

```typescript
{
  tools: string[]      // Array of tool directory paths
  resources: string[]  // Array of resource directory paths
  prompts: string[]    // Array of prompt directory paths
  handlers: string[]   // Array of handler directory paths
}
```

All paths are relative to the `server/` directory of each Nuxt layer.

## Example: Shared Definitions

Share definitions across multiple Nuxt layers:

```text
project/
├── shared/
│   ├── tools/
│   │   └── common-tool.ts
│   └── resources/
│       └── common-resource.ts
└── apps/
    ├── web/
    │   └── server/
    │       └── mcp/
    │           └── tools/
    │               └── web-tool.ts
    └── api/
        └── server/
            └── mcp/
                └── tools/
                    └── api-tool.ts
```

Configure the hook to include shared definitions:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Include shared tools from project root
      paths.tools.push('../../shared/tools')
      paths.resources.push('../../shared/resources')
      paths.prompts.push('../../shared/prompts')
    },
  },
})
```

## Example: Multiple Source Directories

Scan multiple directories for definitions:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    dir: 'mcp', // Default directory
  },
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Add additional tool directories
      paths.tools.push('legacy-tools')
      paths.tools.push('new-tools')

      // Add additional resource directories
      paths.resources.push('external-resources')
    },
  },
})
```

This will scan:

- `server/mcp/tools/` (default)
- `server/legacy-tools/`
- `server/new-tools/`
- `server/mcp/resources/` (default)
- `server/external-resources/`

## Example: Layer-Specific Paths

In a Nuxt layer setup, configure paths per layer:

```typescript [layers/api/nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Only include API-specific tools
      paths.tools = ['api/tools']
      paths.resources = ['api/resources']
    },
  },
})
```

## Path Resolution

Paths are resolved relative to:

1. The `server/` directory of the current Nuxt layer
2. The project root (for absolute paths)

```typescript
// Relative to server/
paths.tools.push('custom/tools')

// Absolute from project root
paths.tools.push('/absolute/path/to/tools')
```

## Best Practices

1. **Use descriptive directory names**: Make it clear what each directory contains
2. **Keep paths organized**: Group related definitions together
3. **Document custom paths**: Add comments explaining why custom paths are used
4. **Test path resolution**: Ensure paths resolve correctly in all environments
5. **Consider layer structure**: Use layers for complex multi-app setups

## Next Steps

- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create multiple MCP endpoints
- [Hooks](https://mcp-toolkit.nuxt.dev/advanced/hooks) - Learn more about hooks
- [Configuration](https://mcp-toolkit.nuxt.dev/getting-started/configuration) - Configure the module


# Capture MCP logs and wide events

`useMcpLogger()` exposes two channels with two audiences:

| Channel    | Goes to                                               | API                                                                      |
| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
| **Client** | The end user / agent UI (Cursor, Claude, Inspector)   | `log.notify(level, data)` + `.debug` / `.info` / `.warning` / `.error`   |
| **Server** | Your dev terminal and drains (Axiom, Sentry, OTLP, …) | `log.set` / `log.event` / `log.setUser` / `log.setSession` / `log.evlog` |

The client channel always works. The server channel needs `evlog/nuxt`.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Add useMcpLogger and evlog-style wide events
icon: i-lucide-scroll-text
---
Add structured logging to my Nuxt MCP server (@nuxtjs/mcp-toolkit).

- Use useMcpLogger() inside a tool handler (auto-imported)
- log.notify.info({ … }) sends notifications/message to the connected MCP client (respects logging/setLevel)
- log.set({ … }) accumulates context onto the request's evlog wide event
- log.event(name, fields?) captures a discrete event in the same wide event
- log.setUser({ id, email, name }) / log.setSession({ id }) for canonical schema
- log.evlog gives you the underlying RequestLogger
- Install evlog and register evlog/nuxt for server-side wide events; configure from the top-level evlog: { … } key in nuxt.config

Docs: <https://mcp-toolkit.nuxt.dev/advanced/logging>{rel=""nofollow""}
::

## Setup

Client notifications work out of the box. For server-side wide events, install [evlog](https://evlog.dev){rel="&#x22;nofollow&#x22;"} and register `evlog/nuxt`:

::code-group
```bash [pnpm]
pnpm add evlog
```

```bash [npm]
npm install evlog
```

```bash [yarn]
yarn add evlog
```

```bash [bun]
bun add evlog
```
::

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['evlog/nuxt', '@nuxtjs/mcp-toolkit'],
  evlog: {
    env: { service: 'my-app' },
  },
})
```

That's it. Configure drains, sampling, redaction, and exclude patterns from the same `evlog: { … }` block — see the [evlog docs](https://evlog.dev){rel="&#x22;nofollow&#x22;"} for the full schema.

### Auto-tagged fields

Every MCP wide event lands in your drain pre-tagged:

| Field                                                                              | Source                                                                                      |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `mcp.transport` / `mcp.route` / `mcp.session_id` / `mcp.method` / `mcp.request_id` | Transport headers                                                                           |
| `mcp.tool` / `mcp.resource` / `mcp.prompt`                                         | JSON-RPC payload                                                                            |
| `user.id` / `user.email` / `user.name`                                             | `event.context.user` (from your auth middleware — better-auth, API key, …)                  |
| `session.id`                                                                       | `event.context.session.id`                                                                  |
| `service`                                                                          | `<evlog.env.service>/mcp` (or slugified `mcp.name`) — auto-injected on `/mcp` and `/mcp/**` |

Batched JSON-RPC calls flip the singular keys (`method`, `tool`, …) to plural arrays (`methods`, `tools`, …).

### Override the auto service

Pin your own value to opt out of the derived `<service>/mcp`:

```typescript [nuxt.config.ts]
evlog: {
  env: { service: 'my-app' },
  routes: {
    '/mcp': { service: 'my-app/agents' },
    '/mcp/**': { service: 'my-app/agents' },
  },
}
```

### Force on / opt out

| `mcp.logging` value   | Behavior                                                      |
| --------------------- | ------------------------------------------------------------- |
| `undefined` (default) | On if `evlog/nuxt` is registered, off otherwise.              |
| `true`                | Asserts `evlog/nuxt` is registered. Build throws if it isn't. |
| `false`               | Opt out. `log.notify(...)` keeps working.                     |

## Usage

`useMcpLogger()` is auto-imported. Call it inside a tool, resource, or prompt handler:

```typescript [server/mcp/tools/charge.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'charge_card',
  inputSchema: { userId: z.string(), amount: z.number().int() },
  handler: async ({ userId, amount }) => {
    const log = useMcpLogger('billing')

    log.set({ billing: { amount } })
    await log.notify.info({ msg: 'starting charge', amount })

    try {
      const receipt = await charge(userId, amount)
      log.event('charge_completed', { receiptId: receipt.id })
      return `Charged ${amount}.`
    }
    catch (err) {
      log.evlog.error('charge failed', err)
      await log.notify.error({ msg: 'charge failed', error: String(err) })
      throw err
    }
  },
})
```

In your dev terminal:

```bash
INFO [my-app/mcp] POST /mcp 200 in 18ms
├─ mcp: transport=streamable-http route=/mcp method=tools/call tool=charge_card
├─ user: id=user-42 email=alice@example.com
├─ billing: amount=1000
└─ requestLogs: 0={"level":"info","message":"charge_completed",...}
```

### API

| Method                                        | Channel | Description                                                                                                                              |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `notify(level, data, logger?)`                | client  | Send a `notifications/message`. Drops silently when filtered out by `logging/setLevel`.                                                  |
| `notify.debug` / `info` / `warning` / `error` | client  | Level shortcuts.                                                                                                                         |
| `set(fields)`                                 | server  | Merge fields into the wide event.                                                                                                        |
| `event(name, fields?)`                        | server  | Append a discrete event to the wide event's `requestLogs`.                                                                               |
| `setUser({ id, email, name })`                | server  | Tag the canonical `user` schema (auto-filled from `event.context.user`).                                                                 |
| `setSession({ id })`                          | server  | Tag `session.id` (auto-filled from `event.context.session`).                                                                             |
| `evlog`                                       | server  | Underlying [`RequestLogger`](https://evlog.dev/docs/api/request-logger){rel="&#x22;nofollow&#x22;"} for `fork`, `error`, `getContext`, … |

`log.notify` always resolves and never throws — safe on hot paths. The server methods throw `McpObservabilityNotEnabledError` if `evlog/nuxt` isn't registered.

## Drains

Ship every MCP wide event to **Axiom, Sentry, OTLP, HyperDX, Datadog, Better Stack, or PostHog** with one Nitro plugin:

```typescript [server/plugins/evlog-axiom.ts]
import { createAxiomDrain } from 'evlog/adapters/axiom'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createAxiomDrain())
})
```

```bash [.env]
NUXT_AXIOM_TOKEN=xaat-...
NUXT_AXIOM_DATASET=mcp-server
```

The hook is additive — register multiple drains in parallel. Custom drains are just `(ctx) => Promise<void>` registered on the same hook.

::callout{icon="i-lucide-arrow-up-right" target="_blank" to="https://evlog.dev"}
See the 

[evlog docs](https://evlog.dev){rel=""nofollow""}

 for the full list of adapters, sampling, redaction, and how to build custom drains.
::

::callout{color="warning" icon="i-lucide-triangle-alert"}
`useMcpLogger()`

 requires 

`nitro.experimental.asyncContext: true`

 (default since Nuxt 3.8+).
::

## Next Steps

- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) — capture `requestId`, timing, and tool names in your handler middleware.
- [Sessions](https://mcp-toolkit.nuxt.dev/advanced/sessions) — tag every wide event with `session.id` automatically.
- [Authentication](https://mcp-toolkit.nuxt.dev/examples/authentication) — soft auth populates `user.id` / `user.email` on every event.
- [evlog docs](https://evlog.dev){rel="&#x22;nofollow&#x22;"} — drains, sampling, redaction, and custom adapters.


# MCP Apps Internals

This page covers the moving parts behind [MCP Apps](https://mcp-toolkit.nuxt.dev/apps/overview): the build pipeline, the host bridge, the security model, and patterns you can compose on top.

## Build Pipeline

For each `app/mcp/*.vue` file, the Nuxt module emits **three artifacts** at build time and registers them on the configured handler:

```bash
.nuxt/mcp-apps/
├── color-picker.app.ts       # McpAppDefinition (the parsed defineMcpApp call)
├── color-picker.tool.ts      # McpToolDefinition wrapping the app
├── color-picker.resource.ts  # McpResourceDefinition serving the HTML
└── color-picker.html         # Single-file Vue bundle (vite-plugin-singlefile)
```

The pipeline runs in three phases:

1. **Parse** — extract the `defineMcpApp({ … })` call from `<script setup>` and pull out only the imports that are referenced inside the macro arguments. The macro is then **stripped** from the browser bundle.
2. **Bundle** — call Vite programmatically with [`vite-plugin-singlefile`](https://github.com/richardtallent/vite-plugin-singlefile){rel="&#x22;nofollow&#x22;"} to produce one self-contained HTML file (Vue runtime, your code, scoped CSS, assets) per SFC.
3. **Emit** — write the three TypeScript files plus the HTML, then add them to Nuxt's auto-import + handler registration so they behave like any other tool / resource.

::callout{color="info" icon="i-lucide-info"}
Output lives under 

`<buildDir>/mcp-apps/`

. It's regenerated on every build, and the dev server watches 

`app/mcp/**`

 so changes hot-reload.
::

### What Gets Inlined Into The HTML

When the LLM calls the tool, the toolkit takes the bundled HTML and injects:

```html
<meta http-equiv="Content-Security-Policy" content="…">
<script type="application/json" id="__mcp_app_data__">
  { "base": "#2563eb", "swatches": [ … ] }
</script>
```

The first `useMcpApp()` call reads `#__mcp_app_data__` synchronously, so `data.value` is **already populated on the first paint** — no fetch, no waterfall.

## The Host Bridge

The iframe and the host communicate over `postMessage` using a JSON-RPC 2.0 envelope. The toolkit ships a singleton `useHostBridge()` (internal) that:

1. Performs the `ui/initialize` handshake to negotiate capabilities and receive `HostContext`.
2. Routes incoming `tool-result` messages back into `data`.
3. Dispatches outbound `callTool`, `prompt`, `openLink` requests to the host.
4. Falls back to the legacy `mcp-ui` envelope (`{ type, payload }`) when talking to older hosts.
5. Detects the **ChatGPT Apps SDK** (`window.openai`) and uses its native APIs when available.

You don't talk to it directly — `useMcpApp()` composes the public surface.

The full round-trip when the LLM calls `color-picker`:

1. **Host → Server** — `tools/call color-picker { base }`.
2. **Server** — runs `handler()` and produces `structuredContent`.
3. **Server → Host** — returns the bundled HTML with the data inlined and a `ui://` resource reference.
4. **Host → Iframe** — mounts the iframe inline, sandboxed.
5. **Iframe** — `useMcpApp()` reads the inline `<script id="__mcp_app_data__">` synchronously, so `data` is populated on first paint.
6. **Iframe → Host** — sends `ui/initialize` to negotiate capabilities.
7. **Host → Iframe** — replies with `HostContext` (`theme`, `displayMode`, `containerDimensions`, …).
8. **Iframe → Host*&#x2A; &#x2A;(optional)* — `ui/callTool { name, params }` for in-place refreshes.
9. **Host → Server** — forwards the call as `tools/call name { params }`.
10. **Server → Host → Iframe** — new `structuredContent` flows back as a `tool-result` and replaces `data`.

## Security Model

MCP Apps run in a sandboxed iframe loaded from the same origin as your MCP endpoint. The toolkit hardens the surface in three layers.

### 1. Default CSP

Every app HTML gets a CSP `<meta>` that:

- Blocks all third-party scripts. Only the inline bundle script may execute.
- Blocks `<form>` action targets.
- Disallows `connect-src`, `img-src`, `style-src`, `font-src` external origins until you explicitly allow them.

You opt into external resources per app:

```ts
defineMcpApp({
  csp: {
    resourceDomains: ['https://images.example.com'], // img / style / font / link
    connectDomains: ['https://api.example.com'],     // fetch / XHR / WebSocket
  },
  // …
})
```

The same allow-list is mirrored into `_meta.ui.csp` and `_meta['openai/widgetCSP']` for hosts that enforce CSP themselves.

### 2. Domain Validation

CSP origins are validated at build time. The toolkit rejects:

- Non-string or empty values.
- URL schemes other than `http(s)://` or `ws(s)://`.
- Strings that contain quotes, semicolons, or whitespace.

If a domain looks suspicious, the build fails — you can't accidentally ship an injection vector via misconfiguration.

### 3. Iframe Isolation

The iframe runs as if it were a third-party page on your origin: no cookies, no `localStorage` from the parent app, no shared module graph. This is **by design** — apps must declare what they need, and they cannot reach into the parent Nuxt runtime.

::callout{color="warning" icon="i-lucide-shield"}
Pass 

`csp: false`

 only when you fully control every byte the iframe loads. Stripping the CSP turns off the only line of defense against compromised dependencies.
::

## Custom `_meta`

The handler returns a regular MCP `CallToolResult`, so you can attach any host-specific metadata via `_meta`:

```ts
defineMcpApp({
  _meta: {
    'openai/widgetAccessible': true,
    'openai/toolInvocation/invoking': 'Loading stays…',
    'openai/toolInvocation/invoked': 'Stays loaded',
  },
  handler: async () => ({ structuredContent: { … } }),
})
```

The toolkit auto-fills `_meta.ui.resourceUri` (so hosts can re-fetch the HTML on demand) and `_meta.ui.csp`. Anything you put in `_meta` is merged on top.

## Advanced Patterns

### Re-using server logic

Apps share `server/api/`, `server/utils/`, and `shared/` with the rest of your Nuxt app. A typical layout:

```bash
app/mcp/color-picker.vue          # UI + handler that calls $fetch('/api/palette')
server/api/palette.get.ts         # The actual data endpoint (callable by humans + tools)
server/utils/palette.ts           # Shared generators / helpers
shared/types/palette.ts           # Types auto-imported by both the SFC and the endpoint
```

A regular Nuxt page, an external client, or the MCP App handler all hit `/api/palette` with the exact same contract — and types under `shared/types/` resolve globally without an `import` statement.

### Multiple handlers

Apps are attributed to a named MCP handler at build time, exactly like tools and resources under `server/mcp/handlers/<name>/`. Two ways to control attribution:

**Sub-folder convention** — drop the SFC under a sub-directory matching the handler name:

```bash
app/mcp/
├── color-picker.vue          # → handler 'apps' (default)
├── finder/
│   └── stay-finder.vue       # → handler 'finder' (/mcp/finder)
└── checkout/
    └── stay-checkout.vue     # → handler 'checkout' (/mcp/checkout)
```

**Explicit override** — `attachTo` (plus `group` / `tags`) on `defineMcpApp` win over the folder default:

```vue [app/mcp/stay-finder.vue]
<script setup lang="ts">
defineMcpApp({
  attachTo: 'finder',
  group: 'stays',
  tags: ['searchable'],
  // ...
})
</script>
```

Then add the matching handler index file:

```ts [server/mcp/handlers/finder/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({})
```

With `defaultHandlerStrategy: 'orphans'` (the default) the app no longer leaks into `/mcp` — it only shows up on `/mcp/finder`. Need a manual cross-cut? `getMcpTools({ handler: 'finder' })` and `getMcpResources({ handler: 'finder' })` return the raw definitions for further filtering. See [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview).

::callout{color="info" icon="i-lucide-info"}
`attachTo`

, 

`group`

, and 

`tags`

 must be 

**literals**

. The toolkit reads them statically at build time so the routing decision is deterministic across dev, build, and deploy. Dynamic expressions fail the build with a clear error.
::

### Per-host adaptation

Use `hostContext` to opt into host-specific affordances:

```ts
const isChatGpt = computed(() => typeof window !== 'undefined' && 'openai' in window)
const supportsFullscreen = computed(() => hostContext.value?.displayMode !== undefined)
```

Avoid hard-coding behaviours per host whenever you can — the bridge already smooths over the major differences.

### Testing apps

Server-side: the `handler` is a plain async function. Import the parsed app definition from `.nuxt/mcp-apps/<name>.app.ts` (or import the SFC's `defineMcpApp` arguments via the parser) and call the handler directly with mock input.

Iframe-side: render the SFC with `@vue/test-utils` and stub the host bridge by injecting `window.parent.postMessage` listeners. The toolkit's own test suite (`packages/nuxt-mcp-toolkit/test/apps-handshake.test.ts`) shows the pattern.

::callout{color="info" icon="i-lucide-info"}
Most regressions in MCP Apps come from forgetting that 

**`handler` runs server-side and the template runs client-side**

. Treat them as two halves of an API: one produces a contract (

`structuredContent`

), the other consumes it.
::

## Limits & Footguns

- **One handler per app.** If you need a second tool from the same UI, declare it elsewhere and call it via `callTool('other-tool', …)`.
- **No top-level await in `<script setup>`** of an app — the macro must be statically analysable.
- **Only relative imports + auto-imports + the `#shared` alias** in the SFC. Anything that pulls in the Nuxt runtime won't bundle.
- **Keep payloads small.** The data is inlined into the HTML; large payloads (>1 MB) noticeably slow first paint.
- **Style with `scoped`.** Global styles leak across apps because every app loads its own copy of Vue's style runtime.


# Listing Definitions

## Overview

The toolkit auto-discovers every tool, resource, and prompt under `server/mcp/`. From your own server routes you sometimes need to read that catalog back — to render an [`/.well-known/mcp/server-card.json`](https://modelcontextprotocol.io/specification/2025-11-25/basic/server-cards){rel="&#x22;nofollow&#x22;"}, an admin dashboard, an API catalog, or a sitemap.

Use the `listMcp*` helpers from `@nuxtjs/mcp-toolkit/server` to get JSON-friendly summaries of every discovered definition without duplicating their names and descriptions in your own code.

| Helper                         | Returns                                                          |
| ------------------------------ | ---------------------------------------------------------------- |
| `listMcpTools(options?)`       | `McpToolSummary[]` (JSON-friendly)                               |
| `listMcpResources(options?)`   | `McpResourceSummary[]` (JSON-friendly)                           |
| `listMcpPrompts(options?)`     | `McpPromptSummary[]` (JSON-friendly)                             |
| `listMcpDefinitions(options?)` | `{ tools, resources, prompts }`                                  |
| `getMcpTools(options?)`        | `McpToolDefinitionListItem[]` (raw, with handlers + Zod schemas) |
| `getMcpResources(options?)`    | `McpResourceDefinition[]` (raw)                                  |
| `getMcpPrompts(options?)`      | `McpPromptDefinition[]` (raw)                                    |

Each summary contains `name`, `title`, `description`, `group`, `tags`, and `handler` (plus `uri` for resources). Names auto-generated from the filename are already resolved, so what you get matches exactly what the MCP client sees in `tools/list`.

::callout{color="info" icon="i-lucide-info"}
Use 

`listMcp*`

 for 

**summaries**

 (JSON catalog endpoints). Use 

`getMcp*`

 to feed 

**raw definitions**

 back into 

[`defineMcpHandler({ tools: ev => getMcpTools(...) })`](https://mcp-toolkit.nuxt.dev/handlers/organization#b-function-form-the-escape-hatch)

.
::

## Usage

### Server card

Expose the toolkit's catalog as a [`server-card.json`](https://modelcontextprotocol.io/specification/2025-11-25/basic/server-cards){rel="&#x22;nofollow&#x22;"} so other agents can discover what your server provides:

```typescript [server/routes/.well-known/mcp/server-card.json.get.ts]
import { listMcpDefinitions } from '@nuxtjs/mcp-toolkit/server'

export default defineEventHandler(async (event) => {
  const { tools, resources, prompts } = await listMcpDefinitions({ event })
  return {
    name: 'My MCP Server',
    description: 'Tools, resources and prompts exposed by my Nuxt app.',
    tools: tools.map(t => ({ name: t.name, description: t.description })),
    resources: resources.map(r => ({ name: r.name, uri: r.uri, description: r.description })),
    prompts: prompts.map(p => ({ name: p.name, description: p.description })),
  }
})
```

### Tool catalog

Render a public list of available tools, optionally grouped:

```typescript [server/api/tools.get.ts]
import { listMcpTools } from '@nuxtjs/mcp-toolkit/server'

export default defineEventHandler(async (event) => {
  const tools = await listMcpTools({ event })
  return Object.groupBy(tools, t => t.group ?? 'default')
})
```

## Options

Every helper accepts the same `ListMcpDefinitionsOptions` object. All keys are optional and combine with AND semantics — a definition must pass every active filter.

| Option        | Type                | Description                                                                                                                                                                         |
| ------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event`       | `H3Event`           | Apply per-definition [`enabled()` guards](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions#the-enabled-guard) using the request context.                                   |
| `group`       | `string | string[]` | Keep only definitions whose [group](https://mcp-toolkit.nuxt.dev/tools/groups-organization) matches one of these (OR).                                                              |
| `tags`        | `string | string[]` | Keep only definitions tagged with at least one of these (OR).                                                                                                                       |
| `handler`     | `string | string[]` | Keep only definitions attached to one of these named handlers via [folder convention](https://mcp-toolkit.nuxt.dev/handlers/organization#a-folder-convention-the-way-to-attribute). |
| `orphansOnly` | `boolean`           | Return only orphan definitions (those not attached to any named handler). Mutually exclusive with `handler`.                                                                        |

### Filter by `enabled()`

Pass the current `H3Event` to apply per-definition `enabled` guards. Definitions hidden for the current request are excluded so the catalog you expose matches what the request would actually see in `tools/list`:

```typescript
const all = await listMcpTools()
const visible = await listMcpTools({ event })
```

### Filter by group

Auto-inferred from the directory structure (e.g. `server/mcp/tools/admin/foo.ts` → `'admin'`) or set explicitly on the definition.

```typescript
const adminTools = await listMcpTools({ group: 'admin' })
const adminOrContent = await listMcpTools({ group: ['admin', 'content'] })
```

### Filter by tags

Tags use OR-match — pass several to widen the result. To require **every** listed tag (AND), post-filter the result with `Array.filter`.

```typescript
const publicTools = await listMcpTools({ tags: 'public' })
const publicOrDocs = await listMcpTools({ tags: ['public', 'docs'] })

const publicAndStable = (await listMcpTools({ tags: 'public' }))
  .filter(t => t.tags?.includes('stable'))
```

### Filter by handler attribution

Use `handler` to scope the catalog to a single [named handler](https://mcp-toolkit.nuxt.dev/handlers/organization), or `orphansOnly: true` to enumerate definitions only exposed via the default route:

```typescript
const adminCatalog = await listMcpTools({ handler: 'admin' })
const adminOrPublic = await listMcpTools({ handler: ['admin', 'public'] })
const orphans = await listMcpTools({ orphansOnly: true })
```

### Combine everything

Filters compose freely — request-aware visibility plus group, tag, and handler narrowing in one call:

```typescript
const adminDestructive = await listMcpTools({
  event,
  handler: 'admin',
  tags: 'destructive',
})
```

## Caching

Listings are cheap (in-memory reads of the auto-generated registry), but if you expose them on a public route you can still wrap the handler with [`defineCachedEventHandler`](https://nitro.build/guide/cache#cached-event-handlers){rel="&#x22;nofollow&#x22;"} to add HTTP cache headers:

```typescript [server/routes/.well-known/mcp/server-card.json.get.ts]
import { listMcpDefinitions } from '@nuxtjs/mcp-toolkit/server'

export default defineCachedEventHandler(async (event) => {
  const definitions = await listMcpDefinitions({ event })
  return { name: 'My MCP Server', ...definitions }
}, {
  maxAge: 60 * 60,
  swr: true,
})
```

::callout{color="warning" icon="i-lucide-triangle-alert"}
Skip the cache wrapper if you pass 

`event`

 to apply 

`enabled()`

 guards that depend on per-request context (auth, headers). Caching would freeze the response for the first request's context.
::

## Next Steps

- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) — Hide or show definitions per request with `enabled()` guards.
- [Hooks](https://mcp-toolkit.nuxt.dev/advanced/hooks) — Add extra directories to scan for definitions.
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) — Define custom MCP endpoints with their own subset of tools.


# Add middleware to MCP handlers

## What is Middleware?

Middleware allows you to run code **before** (and optionally **after**) MCP requests are processed.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Add MCP server middleware and auth
icon: i-lucide-shield
---
Add authentication middleware to my Nuxt MCP server (@nuxtjs/mcp-toolkit).

- Create or edit server/mcp/index.ts with defineMcpHandler and a middleware function
- In the middleware, validate the auth header (e.g. Bearer token or API key from getHeader(event, 'authorization'))
- Set the authenticated user on event.context.user for tools to access
- Do NOT throw 401 errors for missing auth — use a "soft" approach that sets context when auth succeeds
- Access user context in tools via useEvent().context.user (requires nitro.experimental.asyncContext: true)
- Use extractToolNames(event) to restrict specific tools to certain roles
- Extend H3EventContext in server/types.ts for type-safe context
- For post-handler logic (logging, timing), call next() explicitly and return its result

Docs: <https://mcp-toolkit.nuxt.dev/advanced/middleware>{rel=""nofollow""}
::

This is useful for:

- **Authentication** - Validate tokens and set user context
- **Logging** - Track request timing and analytics
- **Context** - Pass data to your tools via `event.context`
- **Rate limiting** - Control request frequency
- **Error handling** - Wrap handlers with try/catch

## Basic Usage

Add middleware to your handler using the `middleware` option:

```typescript [server/mcp/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event) => {
    // Set context that tools can access
    event.context.userId = 'user-123'
    event.context.startTime = Date.now()
  },
})
```

::callout{color="primary" icon="i-lucide-lightbulb"}
If you don't call 

`next()`

, the handler is called 

**automatically**

 after your middleware runs. This makes simple use cases straightforward.
::

## Simple Middleware

For most cases, you just need to set context before the handler runs. Use a **soft** approach — set context only when authentication succeeds, and let unauthenticated requests continue:

```typescript [server/mcp/index.ts]
import { getHeader } from 'h3'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event) => {
    const apiKey = getHeader(event, 'x-api-key')
    if (!apiKey) return

    const user = await validateApiKey(apiKey).catch(() => null)
    if (!user) return

    event.context.apiKey = apiKey
    event.context.user = user
  },
})
```

::callout{color="warning" icon="i-lucide-triangle-alert"}
**Do not throw `401` from MCP middleware.**

 Many MCP clients treat a 401 as a signal to start OAuth discovery (looking for 

`.well-known/oauth-*`

 endpoints). Set context softly and use 

[`enabled` guards](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions)

 or per-tool checks to gate functionality. See 

[Authentication](https://mcp-toolkit.nuxt.dev/examples/authentication)

 for the full pattern.
::

Your tools can then access this context:

```typescript [server/mcp/tools/my-tool.ts]
import { useEvent } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'my-tool',
  description: 'A tool that uses middleware context',
  inputSchema: {},
  handler: async () => {
    const event = useEvent()
    const user = event.context.user
    return `Hello, ${user.name}!`
  },
})
```

::callout{color="info" icon="i-lucide-info"}
To use `useEvent()` in your tools, enable `asyncContext` in your Nuxt config:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    experimental: {
      asyncContext: true,
    },
  },
})
```
::

## Advanced Middleware with `next()`

For more control, call `next()` explicitly to run code **before and after** the handler:

```typescript [server/mcp/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event, next) => {
    const startTime = Date.now()
    console.log('[MCP] Request started:', event.path)

    // Call the handler
    const response = await next()

    // Code after the handler
    const duration = Date.now() - startTime
    console.log(`[MCP] Request completed in ${duration}ms`)

    return response
  },
})
```

### When to use `next()`

| Use Case                     | Need `next()`? |
| ---------------------------- | -------------- |
| Set context before handler   | No             |
| Validate auth before handler | No             |
| Log request timing           | Yes            |
| Modify response              | Yes            |
| Catch errors                 | Yes            |

## Authentication Example

Set the user on context when the token is valid; do nothing otherwise. Tools that require auth can check `event.context.user` and use [`enabled` guards](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) to hide themselves from anonymous callers:

```typescript [server/mcp/index.ts]
import { getHeader } from 'h3'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event) => {
    const authHeader = getHeader(event, 'authorization')
    if (!authHeader?.startsWith('Bearer ')) return

    const token = authHeader.slice(7)
    const user = await verifyToken(token).catch(() => null)
    if (!user) return

    event.context.user = user
    event.context.userId = user.id
  },
})
```

See the [Authentication guide](https://mcp-toolkit.nuxt.dev/examples/authentication) for a complete walkthrough (Better Auth API keys, custom validation, configuring clients).

## Logging & Analytics Example

::callout
---
color: primary
icon: i-lucide-arrow-right
to: https://mcp-toolkit.nuxt.dev/advanced/logging
---
For structured wide events, drains (Axiom, Sentry, OTLP, Datadog…), and per-tool context, use 

[`useMcpLogger()`](https://mcp-toolkit.nuxt.dev/advanced/logging)

 instead of the manual 

`console.log`

 pattern below. The middleware example here is kept minimal so it doesn't depend on 

`evlog`

.
::

```typescript [server/mcp/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event, next) => {
    const requestId = crypto.randomUUID()
    const startTime = Date.now()

    event.context.requestId = requestId

    console.log(JSON.stringify({
      type: 'mcp_request_start',
      requestId,
      path: event.path,
      method: event.method,
      timestamp: new Date().toISOString(),
    }))

    const response = await next()

    console.log(JSON.stringify({
      type: 'mcp_request_end',
      requestId,
      duration: Date.now() - startTime,
      timestamp: new Date().toISOString(),
    }))

    return response
  },
})
```

## Extracting Tool Names

Use the `extractToolNames` utility to inspect which tools are being called in the current request. It parses the JSON-RPC body and returns the tool names from any `tools/call` messages.

```typescript [server/mcp/index.ts]
import { defineMcpHandler, extractToolNames } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event, next) => {
    const toolNames = await extractToolNames(event)

    if (toolNames.length > 0) {
      console.log(`[MCP] Calling tools: ${toolNames.join(', ')}`)
    }

    return next()
  },
})
```

This is useful for:

- **Logging** which tools are called per request
- **Monitoring** tool usage and frequency
- **Access control** based on tool names (e.g. restricting certain tools to admin users)

```typescript [server/mcp/index.ts]
import { createError } from 'h3'
import { defineMcpHandler, extractToolNames } from '@nuxtjs/mcp-toolkit/server'

const ADMIN_TOOLS = ['delete-user', 'reset-database']

export default defineMcpHandler({
  middleware: async (event) => {
    const toolNames = await extractToolNames(event)
    const user = event.context.user

    if (toolNames.some(name => ADMIN_TOOLS.includes(name)) && user?.role !== 'admin') {
      throw createError({ statusCode: 403, message: 'Admin access required for this tool' })
    }
  },
})
```

::callout{color="info" icon="i-lucide-info"}
Throwing 

`403`

 for a specific in-flight tool call is safe — by the time 

`tools/call`

 arrives, the client has already initialized and won't enter OAuth discovery. The "no throw" rule applies to 

**`401` on missing/invalid auth at the transport level**

.
::

::callout{color="primary" icon="i-lucide-lightbulb"}
`extractToolNames`

 is auto-imported in the server context — no import needed when using it in your 

`server/`

 directory.
::

## Middleware with Custom Handlers

Middleware works the same way with custom handlers. For an admin-only endpoint mounted at a non-discovery route (e.g. `/mcp/admin`), throwing `403` is safe — the client targeted this route explicitly:

```typescript [server/mcp/admin.ts]
import { createError } from 'h3'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'admin',
  middleware: async (event) => {
    const user = await getUser(event)

    if (user?.role !== 'admin') {
      throw createError({
        statusCode: 403,
        message: 'Admin access required',
      })
    }

    event.context.user = user
  },
  tools: [adminTool1, adminTool2],
})
```

## TypeScript

For type-safe context, extend the H3 context:

```typescript [server/types.ts]
declare module 'h3' {
  interface H3EventContext {
    user?: {
      id: string
      name: string
      role: 'user' | 'admin'
    }
    requestId?: string
    startTime?: number
  }
}
```

Now your middleware and tools will have typed context:

```typescript [server/mcp/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event) => {
    event.context.user = {
      id: 'user-123',
      name: 'John',
      role: 'admin', // TypeScript will validate this
    }
  },
})
```

## Best Practices

1. **Keep middleware focused** - Do one thing well
2. **Don't call `next()` if you don't need it** - Let it be called automatically
3. **Always return `next()` result** - If you call `next()`, return its result
4. **Handle errors gracefully** - Use `createError` for HTTP errors
5. **Type your context** - Extend H3EventContext for type safety

## Next Steps

- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Learn about custom handlers
- [TypeScript](https://mcp-toolkit.nuxt.dev/advanced/typescript) - Type-safe definitions
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Create tools that use middleware context


# Add type safety with TypeScript

## Type Safety

The Nuxt MCP module provides full TypeScript support with complete type inference and type safety.

## Auto-Imports

All helper functions and types are auto-imported in your server files:

**Functions:**

- `defineMcpTool`, `defineMcpResource`, `defineMcpPrompt`, `defineMcpHandler`, `defineMcpApp`
- `imageResult`, `audioResult` (binary media helpers for tool responses)
- `completable`, `extractToolNames`
- `useMcpSession`, `useMcpServer`, `useMcpLogger`, `useMcpElicitation`, `useMcpApp`
- `listMcpTools`, `listMcpResources`, `listMcpPrompts`, `listMcpDefinitions`
- `getMcpTools`, `getMcpResources`, `getMcpPrompts`

::callout{color="warning" icon="i-lucide-triangle-alert"}
The 

`textResult`

, 

`jsonResult`

, and 

`errorResult`

 helpers are 

**deprecated**

. Return strings, numbers, booleans, objects, or arrays directly from your handler — the toolkit auto-wraps them. For errors, throw an 

`Error`

 or use 

`createError`

 from 

`h3`

. See 

[Errors & caching](https://mcp-toolkit.nuxt.dev/tools/errors-caching)

.
::

**Types:**

- `McpRequestExtra` — extra arguments passed to every tool, prompt, and resource handler (abort signal, auth info, session ID, metadata). Equivalent to `RequestHandlerExtra<ServerRequest, ServerNotification>` from the SDK.
- `McpServerHelper` — return type of [`useMcpServer()`](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions#mid-session-registration).
- `McpSessionStore` — typed store returned by [`useMcpSession()`](https://mcp-toolkit.nuxt.dev/advanced/sessions).
- `McpClientNotifier`, `McpLogger`, `McpRequestLogger`, `McpUserFields`, `McpSessionFields` — types behind [`useMcpLogger()`](https://mcp-toolkit.nuxt.dev/advanced/logging).
- `McpElicitation`, `ElicitationFormParams`, `ElicitationFormResult`, `ElicitationUrlParams`, `ElicitationUrlResult`, `ElicitationMode` — types behind [`useMcpElicitation()`](https://mcp-toolkit.nuxt.dev/advanced/elicitation).
- Common SDK protocol types are re-exported from a single import path: `Annotations`, `CallToolResult`, `GetPromptResult`, `ReadResourceResult`, `Resource`, `ServerNotification`, `ServerRequest`, `ToolAnnotations`.

::callout{color="warning" icon="i-lucide-triangle-alert"}
The aliases 

`McpToolExtra`

, 

`McpPromptExtra`

, and 

`McpResourceExtra`

 are kept for back-compat but 

**deprecated**

 — they all resolve to 

`McpRequestExtra`

. Prefer the canonical name in new code.
::

```typescript
import { z } from 'zod'

export default defineMcpTool({
  name: 'example',
  inputSchema: {
    message: z.string(),
  },
  handler: async ({ message }, extra: McpRequestExtra) => {
    // message is typed as string
    // extra.signal, extra.authInfo, extra.sessionId are available
  },
})
```

You can disable auto-imports entirely with `autoImports: false` in your [configuration](https://mcp-toolkit.nuxt.dev/getting-started/configuration) and import explicitly from `@nuxtjs/mcp-toolkit/server` instead.

## Type Inference

### Tool Input Types

Input types are automatically inferred from your `inputSchema`:

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'example',
  inputSchema: {
    name: z.string(),
    age: z.number(),
    email: z.string().email().optional(),
  },
  handler: async ({ name, age, email }) => {
    // name: string
    // age: number
    // email: string | undefined
  },
})
```

### Tool Output Types

Output types are inferred from `outputSchema`:

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'example',
  inputSchema: {
    value: z.number(),
  },
  outputSchema: {
    result: z.number(),
    doubled: z.number(),
  },
  handler: async ({ value }) => {
    const result = value * 2

    return {
      structuredContent: {
        result,      // TypeScript knows this is number
        doubled: result * 2, // TypeScript knows this is number
      },
    }
  },
})
```

### Prompt Argument Types

Prompt argument types are inferred from `inputSchema`:

```typescript
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'example',
  inputSchema: {
    text: z.string(),
    maxLength: z.string().optional(),
  },
  handler: async ({ text, maxLength }) => {
    // text: string
    // maxLength: string | undefined
  },
})
```

## Runtime Config Types

Access typed runtime configuration:

```typescript [server/api/config.ts]
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event).mcp

  // config is typed with:
  // - enabled: boolean
  // - route: string
  // - browserRedirect: string
  // - name: string
  // - version: string
  // - dir: string

  return config
})
```

## Next Steps

- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Learn about creating tools
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Learn about creating resources
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Learn about creating prompts


# Extend the module with hooks

The toolkit exposes two flavours of hooks:

- **Build-time hooks** on `NuxtHooks` — fire during `nuxt build` / `nuxt prepare`, useful to register additional definition directories.
- **Runtime hooks** on `NitroRuntimeHooks` — fire **per request**, inside Nitro plugins, to mutate the resolved config or reach the SDK `McpServer` instance.

User listeners are best-effort: a hook that throws is logged via [consola](https://github.com/unjs/consola){rel="&#x22;nofollow&#x22;"} and the MCP request continues.

## Build-time hooks

### `mcp:definitions:paths`

Add additional directories to scan for tool / resource / prompt / handler definitions. Useful for sharing definitions across Nuxt layers or shipping them from a custom module.

#### Hook Signature

```typescript
nuxt.hook('mcp:definitions:paths', (paths: {
  tools: string[]
  resources: string[]
  prompts: string[]
  handlers: string[]
}) => {
  // Mutate paths in place
})
```

#### Usage in `nuxt.config.ts`

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      paths.tools.push('shared/tools')
      paths.tools.push('legacy/tools')
      paths.resources.push('shared/resources')
      paths.prompts.push('shared/prompts')
      paths.handlers.push('custom/handlers')
    },
  },
})
```

#### Usage in a Custom Module

```typescript [my-module.ts]
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('mcp:definitions:paths', (paths) => {
      paths.tools.push('my-module/tools')
      paths.resources.push('my-module/resources')
      paths.prompts.push('my-module/prompts')
    })
  },
})
```

#### Path Structure

```typescript
{
  tools: string[]      // Directories to scan for tools
  resources: string[]  // Directories to scan for resources
  prompts: string[]    // Directories to scan for prompts
  handlers: string[]   // Directories to scan for handlers
}
```

All paths are relative to the `server/` directory of each Nuxt layer:

1. **Relative paths** like `'tools'` resolve to `server/tools/`.
2. **Absolute paths** starting with `/` resolve from project root.
3. **Layer-specific** — each Nuxt layer resolves paths relative to its own `server/` directory.

## Runtime hooks

Runtime hooks fire **per MCP request**, from inside the Nitro server. Subscribe to them from a [Nitro plugin](https://nuxt.com/docs/guide/directory-structure/server#server-plugins){rel="&#x22;nofollow&#x22;"} at `server/plugins/`.

```typescript [server/plugins/mcp.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:server:created', ({ server, event }) => {
    // ...
  })
})
```

The hooks run in this order:

```text
H3 Event
   │
   ▼
defineMcpHandler middleware (if any)
   │
   ▼
resolveDynamicDefinitions  ──►  mcp:config:resolved
   │
   ▼
createMcpServer            ──►  mcp:server:created
   │
   ▼
transport.handleRequest
```

### `mcp:config:resolved`

Fired after dynamic `tools` / `resources` / `prompts` resolvers and `enabled(event)` guards have run, **before** the per-request `McpServer` is built. Mutate `ctx.config` in place to add, remove or transform definitions for this request only.

#### Hook signature

```typescript
import type { McpResolvedConfig } from '@nuxtjs/mcp-toolkit/server'
import type { H3Event } from 'h3'

nitroApp.hooks.hook('mcp:config:resolved', (ctx: {
  config: McpResolvedConfig
  event: H3Event
}) => {
  // Mutate ctx.config in place
})
```

#### Example: hide admin tools from anonymous clients

```typescript [server/plugins/mcp-auth.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:config:resolved', ({ config, event }) => {
    if (!event.context.user) {
      config.tools = config.tools.filter(
        tool => !tool.tags?.includes('admin'),
      )
    }
  })
})
```

#### Example: rebrand the server per request

```typescript [server/plugins/mcp-rebrand.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:config:resolved', ({ config, event }) => {
    const tenant = event.context.tenant?.name
    if (tenant) {
      config.name = `${tenant} MCP`
      config.instructions = `You are connected to ${tenant}'s MCP server.`
    }
  })
})
```

### `mcp:server:created`

Fired after `createMcpServer` has registered every tool / resource / prompt and **before** the server is connected to the transport. Receives the SDK [`McpServer`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/server/mcp.ts){rel="&#x22;nofollow&#x22;"} instance.

Use it to register definitions late or reach the underlying low-level [`Server`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/server/index.ts){rel="&#x22;nofollow&#x22;"} via `getSdkServer(ctx.server)` to install custom JSON-RPC handlers.

#### Hook signature

```typescript
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import type { H3Event } from 'h3'

nitroApp.hooks.hook('mcp:server:created', (ctx: {
  server: McpServer
  event: H3Event
}) => {
  // Reach into the SDK
})
```

#### Example: register a tool dynamically

```typescript [server/plugins/mcp-whoami.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:server:created', ({ server, event }) => {
    server.registerTool(
      'whoami',
      { description: 'Return the current user id' },
      async () => ({
        content: [{
          type: 'text',
          text: String(event.context.userId ?? 'anonymous'),
        }],
      }),
    )
  })
})
```

#### Example: instrument the low-level SDK server

```typescript [server/plugins/mcp-instrument.ts]
import { getSdkServer } from '@nuxtjs/mcp-toolkit/server'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:server:created', ({ server }) => {
    const sdkServer = getSdkServer(server)
    sdkServer.oninitialized = () => {
      console.log('Client initialized')
    }
  })
})
```

::tip
Need request- or session-scoped state? Pull it from 

`event.context`

 inside the hook — middleware (and any auth layer that runs before the MCP handler) has already populated it.
::

## Error handling

Listeners that throw are caught and reported via consola (tag `mcp-toolkit`):

```text
[error] [mcp-toolkit] Hook "mcp:server:created" threw — request continues
```

The MCP request always proceeds. If you need an error to surface to the client, throw inside the corresponding tool / resource / prompt handler instead — the toolkit converts thrown errors (including [H3 errors](https://h3.unjs.io/utils/response#createerror){rel="&#x22;nofollow&#x22;"}) into MCP-compliant `isError` results.

## Next Steps

- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) - Run code per MCP request, including `next()` interception.
- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) - Pick tools / resources / prompts dynamically from `defineMcpHandler`.
- [Custom Paths](https://mcp-toolkit.nuxt.dev/advanced/custom-paths) - Customize where definitions are scanned from.
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create multiple MCP endpoints.


# MCP Evals

## Overview

Evals help you verify that your MCP tools are called correctly by an LLM. This guide shows how to run tool-call evaluations with [Evalite](https://www.evalite.dev/){rel="&#x22;nofollow&#x22;"} using the AI SDK MCP client.

The approach stays library-agnostic, Evalite is just the example runner. You can adapt the patterns to other evaluation frameworks.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Set up Evalite MCP tool-call evals
icon: i-lucide-flask-conical
---
Set up MCP evals for my Nuxt app (@nuxtjs/mcp-toolkit) with Evalite.

1. Add dev dependencies: `pnpm add -D evalite vitest @ai-sdk/mcp ai` (or `npm install -D evalite vitest @ai-sdk/mcp ai` / `yarn add -D evalite vitest @ai-sdk/mcp ai` / `bun add -D evalite vitest @ai-sdk/mcp ai`)
2. Add eval scripts to package.json: "eval": "evalite" and "eval\:ui": "evalite watch"
3. Set your AI provider API key and MCP\_URL=<http://localhost:3000/mcp>{rel=""nofollow""} in .env
4. Create test/mcp.eval.ts with evalite() test cases
5. Each test case has an input (natural language prompt) and expected tool calls (e.g. [{ toolName: 'my-tool', input: { ... } }] )
6. Use experimental\_createMCPClient from @ai-sdk/mcp to connect to the MCP server
7. Use generateText from ai with the MCP tools to test tool selection
8. Score with toolCallAccuracy from evalite/scorers
9. Start the dev server, then run your eval scripts (e.g. `pnpm eval` and `pnpm eval:ui`, or `npm run eval` / `yarn eval` / `bun run eval` and the matching watch/ UI script)

Docs: <https://mcp-toolkit.nuxt.dev/advanced/evals>{rel=""nofollow""}
::

::callout{color="primary" icon="i-lucide-lightbulb"}
For a real-world example, check out the 

[nuxt.com MCP evals](https://github.com/nuxt/nuxt.com/blob/main/test/mcp.eval.ts){rel=""nofollow""}

.
::

## Prerequisites

- An MCP server running locally (e.g., `pnpm dev` with the module enabled)
- A model provider API key (AI Gateway, OpenAI, etc.)

## Setup

::steps
### Install dependencies

Install Evalite, Vitest, and the AI SDK packages:

  :::code-group
  ```bash [pnpm]
  pnpm add -D evalite vitest @ai-sdk/mcp ai
  ```

  ```bash [npm]
  npm install -D evalite vitest @ai-sdk/mcp ai
  ```

  ```bash [yarn]
  yarn add -D evalite vitest @ai-sdk/mcp ai
  ```

  ```bash [bun]
  bun add -D evalite vitest @ai-sdk/mcp ai
  ```
  :::

### Add eval scripts

Add the following scripts to your `package.json`:

```json [package.json]
{
  "scripts": {
    "eval": "evalite",
    "eval:ui": "evalite watch"
  }
}
```

### Configure environment variables

Create a `.env` file with your AI provider key and MCP endpoint:

```bash [.env]
# AI provider (AI Gateway example)
AI_GATEWAY_API_KEY=your_key

# MCP endpoint exposed by your dev server
MCP_URL=http://localhost:3000/mcp
```

### Write your first eval

Create an eval file in your `test/` directory:

```typescript [test/mcp.eval.ts]
import { experimental_createMCPClient as createMCPClient } from '@ai-sdk/mcp'
import { generateText } from 'ai'
import { evalite } from 'evalite'
import { toolCallAccuracy } from 'evalite/scorers'

// AI Gateway model format: provider/model-name
const model = 'openai/gpt-4o-mini'
const MCP_URL = process.env.MCP_URL ?? 'http://localhost:3000/mcp'

evalite('BMI Calculator', {
  data: async () => [
    {
      input: 'Calculate BMI for someone who weighs 70kg and is 1.75m tall',
      expected: [{ toolName: 'calculate-bmi', input: { weightKg: 70, heightM: 1.75 } }],
    },
  ],
  task: async (input) => {
    const mcp = await createMCPClient({ transport: { type: 'http', url: MCP_URL } })
    try {
      const result = await generateText({
        model,
        prompt: input,
        tools: await mcp.tools(),
      })
      return result.toolCalls ?? []
    }
    finally {
      await mcp.close()
    }
  },
  scorers: [({ output, expected }) => toolCallAccuracy({ actualCalls: output, expectedCalls: expected })],
})
```
::

## Running Evals

Make sure your MCP server is running first:

::code-group
```bash [pnpm]
pnpm dev
```

```bash [npm]
npm run dev
```

```bash [yarn]
yarn dev
```

```bash [bun]
bun dev
```
::

Then run your evals in a separate terminal:

::code-group
```bash [pnpm]
pnpm eval
```

```bash [npm]
npm run eval
```

```bash [yarn]
yarn eval
```

```bash [bun]
bun eval
```
::

Or launch the Evalite UI for a visual interface:

::code-group
```bash [pnpm]
pnpm eval:ui
```

```bash [npm]
npm run eval:ui
```

```bash [yarn]
yarn eval:ui
```

```bash [bun]
bun eval:ui
```
::

The UI is available at `http://localhost:3006` and shows traces, scores, inputs, and outputs for each eval.

## Project Structure

We recommend placing eval files in a `test/` directory at your project root:

```text
your-project/
├── server/
│   └── mcp/
│       ├── tools/
│       │   └── calculate-bmi.ts
│       ├── resources/
│       └── prompts/
├── test/
│   └── mcp.eval.ts          # Your MCP eval tests
├── nuxt.config.ts
└── package.json
```

::callout{color="neutral" icon="i-lucide-info"}
Evalite looks for files with the 

`.eval.ts`

 extension by default.
::

## Writing Effective Evals

### Testing Tool Selection

Verify the model picks the correct tool:

```typescript [test/mcp.eval.ts]
evalite('Tool Selection', {
  data: async () => [
    {
      input: 'List all available documentation pages',
      expected: [{ toolName: 'list-pages' }],
    },
    {
      input: 'Show me the installation guide',
      expected: [{ toolName: 'get-page', input: { path: '/getting-started/installation' } }],
    },
  ],
  task: async (input) => {
    const mcp = await createMCPClient({ transport: { type: 'http', url: MCP_URL } })
    try {
      const result = await generateText({
        model,
        prompt: input,
        tools: await mcp.tools(),
      })
      return result.toolCalls ?? []
    }
    finally {
      await mcp.close()
    }
  },
  scorers: [({ output, expected }) => toolCallAccuracy({ actualCalls: output, expectedCalls: expected })],
})
```

### Testing Multi-Step Workflows

For workflows that require multiple tool calls, increase `maxSteps`:

```typescript [test/mcp.eval.ts]
evalite('Multi-Step Workflows', {
  data: async () => [
    {
      input: 'Find the installation page and show me its content',
      expected: [
        { toolName: 'list-pages' },
        { toolName: 'get-page', input: { path: '/getting-started/installation' } },
      ],
    },
  ],
  task: async (input) => {
    const mcp = await createMCPClient({ transport: { type: 'http', url: MCP_URL } })
    try {
      const result = await generateText({
        model,
        prompt: input,
        tools: await mcp.tools(),
        maxSteps: 5, // Allow multiple tool calls
      })
      return result.toolCalls ?? []
    }
    finally {
      await mcp.close()
    }
  },
  scorers: [({ output, expected }) => toolCallAccuracy({ actualCalls: output, expectedCalls: expected })],
})
```

### Grouping Related Evals

Organize evals by feature or tool category:

```typescript [test/mcp.eval.ts]
// Documentation tools
evalite('Documentation Tools', {
  data: async () => [
    { input: 'List all docs', expected: [{ toolName: 'list-pages' }] },
    { input: 'Get the intro page', expected: [{ toolName: 'get-page' }] },
  ],
  // ...
})

// API tools
evalite('API Tools', {
  data: async () => [
    { input: 'Fetch user data', expected: [{ toolName: 'get-user' }] },
    { input: 'Create a new post', expected: [{ toolName: 'create-post' }] },
  ],
  // ...
})
```

## Tips

- **Keep prompts specific** so the model chooses the intended tool
- **Use realistic inputs** that match how users phrase requests
- **Start with happy-path cases** before adding edge cases
- **Test parameter extraction** by including specific values in your prompts
- **Run evals before deploying** to catch regressions in tool behavior


# Persist state with MCP sessions

## What are Sessions?

By default, the MCP server is **stateless** — a fresh server instance is created for every request. This works fine for simple request/response tools, but some scenarios require the server to remember context across multiple tool calls.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Enable MCP sessions in Nuxt
icon: i-lucide-database
---
Add session support to my Nuxt MCP server (@nuxtjs/mcp-toolkit).

- Enable sessions in nuxt.config.ts: mcp: { sessions: true }
- Use useMcpSession :t[() (auto-imported) in tool handlers to get/set per-session state]
- await session.get(key) and await session.set(key, value) persist data across tool calls in the same session
- Define a TypeScript interface for your session data and pass it as the generic parameter to useMcpSession :my-session[()]
- Sessions are identified by the MCP-Session-Id header, assigned automatically
- For custom timeout: mcp: { sessions: { enabled: true, maxDuration: 3600000 } }
- Sessions also enable SSE streaming and session continuity

Docs: <https://mcp-toolkit.nuxt.dev/advanced/sessions>{rel=""nofollow""}
::

When sessions are enabled, the server assigns a unique `MCP-Session-Id` to each client connection. This ID is included in every subsequent request, allowing the server to:

- **Maintain state** across multiple tool calls within the same conversation
- **Enable SSE streaming** for real-time server-to-client communication
- **Support session continuity** so clients can reconnect to an existing session

## When to Use Sessions

Sessions are useful when your MCP tools need to:

| Use Case                       | Example                                                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Track conversation context** | Remember user preferences, language, or prior answers within a session                                           |
| **Accumulate data**            | Build up a shopping cart, a list of notes, or a set of selections across tool calls                              |
| **Multi-step workflows**       | Guide users through a wizard (e.g. form builder, deployment pipeline) where each step depends on previous inputs |
| **Per-session counters**       | Track API usage, rate limits, or progress within a session                                                       |
| **Temporary caches**           | Cache expensive computation results that are only relevant to the current session                                |

::callout{color="info" icon="i-lucide-info"}
If your tools are purely stateless (e.g. fetching data, performing calculations, reading files), you don't need sessions. Only enable them when state across tool calls adds real value.
::

## Setup

Enable sessions in your `nuxt.config.ts`:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    sessions: true,
  },
})
```

You can also configure the session timeout:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    sessions: {
      enabled: true,
      maxDuration: 60 * 60 * 1000, // 1 hour (default: 30 minutes)
    },
  },
})
```

## `useMcpSession()`

The `useMcpSession()` server utility provides a typed, per-session key-value store. It is auto-imported and backed by [unstorage](https://unstorage.unjs.io){rel="&#x22;nofollow&#x22;"}, so it works with any storage driver out of the box.

### Typed Session (Recommended)

Define an interface for your session data and pass it as a generic. Keys and values are fully type-checked:

```typescript [server/mcp/tools/counter.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

interface CounterSession {
  counter: number
}

export default defineMcpTool({
  name: 'increment',
  description: 'Increment a per-session counter',
  handler: async () => {
    const session = useMcpSession<CounterSession>()
    const count = await session.get('counter') ?? 0
    await session.set('counter', count + 1)
    return `Counter: ${count + 1}`
  },
})
```

TypeScript will enforce that:

- `session.get('counter')` returns `number | null`
- `session.set('counter', 'wrong')` is a compile error
- `session.get('unknown_key')` is a compile error

### Untyped Session

Without generics, the store accepts any string key and untyped values:

```typescript
const session = useMcpSession()
await session.set('key', { any: 'value' })
const data = await session.get('key')
```

### API Reference

| Method            | Description                                         |
| ----------------- | --------------------------------------------------- |
| `get(key)`        | Retrieve a value by key (returns `null` if missing) |
| `set(key, value)` | Store a value for the given key                     |
| `remove(key)`     | Delete a key from the session                       |
| `has(key)`        | Check if a key exists                               |
| `keys()`          | List all keys in the session                        |
| `clear()`         | Remove all data from the session                    |
| `storage`         | Access the underlying unstorage instance            |

All methods except `storage` are asynchronous and return a `Promise`.

## Examples

### Notepad

A pair of tools that let the AI take notes during a conversation and retrieve them later:

```typescript [server/mcp/tools/add-note.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

interface NotesSession {
  notes: { text: string, createdAt: string }[]
}

export default defineMcpTool({
  name: 'add_note',
  description: 'Add a note to the session notepad',
  inputSchema: {
    note: z.string().describe('The note content'),
  },
  handler: async ({ note }) => {
    const session = useMcpSession<NotesSession>()
    const notes = await session.get('notes') ?? []
    notes.push({ text: note, createdAt: new Date().toISOString() })
    await session.set('notes', notes)
    return `Note added (${notes.length} total).`
  },
})
```

```typescript [server/mcp/tools/get-notes.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

interface NotesSession {
  notes: { text: string, createdAt: string }[]
}

export default defineMcpTool({
  name: 'get_notes',
  description: 'Retrieve all notes from the session notepad',
  handler: async () => {
    const session = useMcpSession<NotesSession>()
    const notes = await session.get('notes') ?? []
    if (notes.length === 0) return 'No notes yet.'
    return notes
  },
})
```

### Multi-Step Wizard

Guide the user through a multi-step form where each step depends on the previous one:

```typescript [server/mcp/tools/wizard.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

interface WizardSession {
  step: number
  projectName: string
  framework: string
}

export default defineMcpTool({
  name: 'wizard_next',
  description: 'Advance to the next step of the project setup wizard',
  inputSchema: {
    answer: z.string().describe('Answer for the current step'),
  },
  handler: async ({ answer }) => {
    const session = useMcpSession<WizardSession>()
    const step = await session.get('step') ?? 1

    if (step === 1) {
      await session.set('projectName', answer)
      await session.set('step', 2)
      return `Project name set to "${answer}". Step 2: Choose a framework (nuxt, next, svelte).`
    }

    if (step === 2) {
      await session.set('framework', answer)
      await session.set('step', 3)
      const name = await session.get('projectName')
      return `Creating "${name}" with ${answer}. Setup complete!`
    }

    return 'Wizard already completed. Use session.clear() to restart.'
  },
})
```

### User Preferences

Remember user preferences for the duration of the session:

```typescript [server/mcp/tools/set-preference.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

interface PreferencesSession {
  language: string
  verbose: boolean
}

export default defineMcpTool({
  name: 'set_preference',
  description: 'Set a user preference for this session',
  inputSchema: {
    language: z.string().optional().describe('Preferred response language'),
    verbose: z.boolean().optional().describe('Enable verbose output'),
  },
  handler: async ({ language, verbose }) => {
    const session = useMcpSession<PreferencesSession>()
    if (language) await session.set('language', language)
    if (verbose !== undefined) await session.set('verbose', verbose)
    return 'Preferences updated.'
  },
})
```

## Custom Storage Driver

By default, session data is stored **in memory**. Data is lost when the server restarts, which is fine for development and most use cases.

For production environments where you need persistence or shared state across multiple server instances, configure a different storage backend via the standard Nitro `storage` config:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  mcp: { sessions: true },
  nitro: {
    storage: {
      'mcp:sessions': {
        driver: 'redis',
        url: 'redis://localhost:6379',
      },
    },
  },
})
```

Any [unstorage driver](https://unstorage.unjs.io/drivers){rel="&#x22;nofollow&#x22;"} can be used: Redis, filesystem, Cloudflare KV, Vercel KV, etc.

## Lifecycle and Cleanup

Session data is **automatically cleaned up** when:

- A session is closed by the client (transport `onclose`)
- A session expires after `maxDuration` of inactivity (default: 30 minutes)

You don't need to manage cleanup manually.

## Session Invalidation

Use `invalidateMcpSession()` (auto-imported) to terminate the current session programmatically. This is useful when auth state changes (e.g., token revocation) and you want to force the client to re-initialize:

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  middleware: async (event) => {
    const isRevoked = await checkIfTokenRevoked(event)
    if (isRevoked) {
      invalidateMcpSession()
    }
  },
})
```

::callout{color="info" icon="i-lucide-info"}
`enabled`

 guards on tools, resources, and prompts are evaluated when the session is created. If auth state changes mid-session, call 

`invalidateMcpSession()`

 to force re-evaluation.
::

::callout{color="info" icon="i-lucide-info"}
**Node:**

 invalidation is tied to the HTTP response — the current MCP request can still complete with 

**200**

, then storage and transport are torn down; the next request with the same 

`MCP-Session-Id`

 gets 

**404**

. 

**Cloudflare Workers:**

 the session is marked invalid before your handler runs; the same request still completes, but the next request with that id gets 

**404**

. To reject the in-flight MCP call immediately on any runtime, return 

**401**

/

**403**

 from middleware (optionally after calling 

`invalidateMcpSession()`

).
::

## Session Continuity vs Resumability

The current implementation provides **session continuity** — a client can make multiple requests using the same `MCP-Session-Id` and the server maintains state across them. This is not the same as **SSE event replay** (true resumability), which would require an `eventStore` to replay missed events after a reconnection. SSE event replay may be added in a future release.

## Requirements

::callout{color="warning" icon="i-lucide-triangle-alert"}
`useMcpSession()` requires:

- `mcp.sessions` to be enabled in your config
- `nitro.experimental.asyncContext` to be `true` (default since Nuxt 3.8+)
::


# Dynamic Definitions

## Overview

By default, every tool, resource, and prompt defined in `server/mcp/` is registered for all clients. Dynamic definitions let you control **which definitions are visible** based on request context — for example, showing admin-only tools to authenticated admins while hiding them from regular users.

There are two complementary mechanisms:

1. **`enabled` guard** — A per-definition callback that controls visibility
2. **Dynamic handler definitions** — A function in `defineMcpHandler` that returns definitions based on context

Both mechanisms run **after middleware**, so `event.context` (e.g. authentication data) is available.

::callout{color="info" icon="i-lucide-info"}
If you only need to change tool/prompt 

**behavior**

 (not visibility), you can already do that by reading 

`event.context`

 inside your handler via 

`useEvent()`

. Dynamic definitions are for controlling which definitions appear in 

`tools/list`

, 

`prompts/list`

, and 

`resources/list`

.
::

## The `enabled` Guard

Add an `enabled` callback to any tool, resource, or prompt definition. When the callback returns `false`, the definition is hidden from the client.

### Tools

```typescript [server/mcp/tools/delete-all.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'delete-all',
  description: 'Delete all records (admin only)',
  inputSchema: {
    confirm: z.boolean().describe('Confirm deletion'),
  },
  enabled: event => event.context.user?.role === 'admin',
  handler: async ({ confirm }) => {
    if (!confirm) return 'Deletion cancelled'
    await deleteAllRecords()
    return 'All records deleted'
  },
})
```

### Resources

```typescript [server/mcp/resources/internal-logs.ts]
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'internal-logs',
  description: 'Application logs (admin only)',
  uri: 'app://logs',
  enabled: event => event.context.user?.role === 'admin',
  handler: async (uri) => ({
    contents: [{ uri: uri.toString(), text: await readLogs() }],
  }),
})
```

### Prompts

```typescript [server/mcp/prompts/onboarding.ts]
import { useEvent } from 'h3'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'onboarding',
  description: 'Personalized onboarding (authenticated users only)',
  enabled: event => !!event.context.user,
  handler: async () => {
    const event = useEvent()
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `Welcome ${event.context.user.name}! Here's how to get started...`,
        },
      }],
    }
  },
})
```

### Middleware Setup

The `enabled` guard runs after middleware, so set up your auth context in middleware:

```typescript [server/mcp/index.ts]
import { getHeader } from 'h3'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event) => {
    const token = getHeader(event, 'authorization')?.replace('Bearer ', '')
    if (token) {
      event.context.user = await verifyToken(token)
    }
  },
})
```

::callout{color="primary" icon="i-lucide-lightbulb"}
To use `useEvent()` inside handlers, enable `asyncContext` in your Nuxt config:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    experimental: {
      asyncContext: true,
    },
  },
})
```
::

## Dynamic Handler Definitions

For more control, pass a **function** as `tools`, `resources`, or `prompts` in `defineMcpHandler`. The function receives the H3 event and returns an array of definitions.

```typescript [server/mcp/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
import { adminTools } from './admin-tools'
import { publicTools } from './public-tools'

export default defineMcpHandler({
  middleware: async (event) => {
    event.context.user = await getUser(event)
  },
  tools: async (event) => {
    const base = [...publicTools]
    if (event.context.user?.role === 'admin') {
      base.push(...adminTools)
    }
    return base
  },
  prompts: async (event) => {
    if (event.context.user) {
      return [authenticatedPrompt, dashboardPrompt]
    }
    return [guestPrompt]
  },
})
```

This is useful when you need to:

- Build the tool list programmatically from a database or config
- Compose definitions from multiple modules
- Apply complex filtering logic

## Combining Both Approaches

The `enabled` guard and dynamic handler definitions work together. When you use dynamic handler definitions, each returned definition's `enabled` guard is still evaluated:

```typescript [server/mcp/index.ts]
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event) => {
    event.context.user = await getUser(event)
  },
  tools: async (event) => {
    const allTools = await loadToolsFromConfig()
    return allTools
  },
})
```

```typescript [server/mcp/tools/admin-delete.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'admin-delete',
  enabled: event => event.context.user?.role === 'admin',
  handler: async () => { /* ... */ },
})
```

In this case, `admin-delete` is loaded by auto-discovery (or dynamically) **and** filtered by its `enabled` guard.

## Session Behavior

When [sessions](https://mcp-toolkit.nuxt.dev/advanced/sessions) are enabled, the MCP server is created on the **first request** of a session. Dynamic definitions are resolved at that point, and the same tool set persists for the session's lifetime.

This means:

- An admin who connects gets admin tools for the entire session
- A regular user who connects never sees admin tools, even if they gain admin access mid-session
- Different sessions can have different tool sets

Without sessions, a new server is created per request, so definitions can vary per request.

## Mid-Session Mutations

The `enabled` guard and dynamic handler definitions control which definitions are registered **when the session starts**. For cases where you need to add, remove, or update definitions **during** an active session, use the `useMcpServer()` composable.

`useMcpServer()` returns a helper with methods to register, remove, and manage tools, prompts, and resources. The SDK automatically sends `notifications/tools/list_changed` (or the equivalent for prompts/resources) to the client, prompting it to re-fetch the list.

### API

| Method                                         | Description                                                      |
| ---------------------------------------------- | ---------------------------------------------------------------- |
| `registerTool(name, config, handler)`          | Register a new tool. Returns a `RegisteredTool` handle.          |
| `registerPrompt(name, config, handler)`        | Register a new prompt. Returns a `RegisteredPrompt` handle.      |
| `registerResource(name, uri, config, handler)` | Register a new resource. Returns a `RegisteredResource` handle.  |
| `removeTool(name)`                             | Remove a tool by name. Returns `true` if found.                  |
| `removePrompt(name)`                           | Remove a prompt by name. Returns `true` if found.                |
| `removeResource(name)`                         | Remove a resource by name. Returns `true` if found.              |
| `server`                                       | The underlying `McpServer` instance for advanced SDK operations. |

### Registering a Tool Mid-Session

```typescript [server/mcp/tools/create-shortcut.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Create a shortcut tool for a specific query',
  inputSchema: {
    name: z.string().describe('Name for the shortcut tool'),
    query: z.string().describe('The query this shortcut runs'),
  },
  handler: async ({ name, query }) => {
    const mcp = useMcpServer()
    mcp.registerTool(name, {
      description: `Shortcut: ${query}`,
    }, async () => {
      const result = await runQuery(query)
      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
    })
    return `Shortcut "${name}" created`
  },
})
```

After calling this tool, the client's tool list refreshes and includes the new shortcut.

### Removing a Tool Mid-Session

Use `removeTool(name)` to remove a tool by name -- no need to store handles:

```typescript [server/mcp/tools/manage-agents.ts]
import { z } from 'zod'
import { createError } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export const registerAgent = defineMcpTool({
  name: 'register-agent',
  inputSchema: {
    agentId: z.string(),
    agentName: z.string(),
  },
  handler: async ({ agentId, agentName }) => {
    const mcp = useMcpServer()
    mcp.registerTool(`call-${agentId}`, {
      description: `Call agent: ${agentName}`,
    }, async () => {
      const response = await callAgent(agentId)
      return { content: [{ type: 'text', text: response }] }
    })
    return `Agent "${agentName}" registered`
  },
})

export const unregisterAgent = defineMcpTool({
  name: 'unregister-agent',
  inputSchema: {
    agentId: z.string(),
  },
  handler: async ({ agentId }) => {
    const mcp = useMcpServer()
    const removed = mcp.removeTool(`call-${agentId}`)
    if (!removed) throw createError({ statusCode: 404, message: `Agent "${agentId}" not found` })
    return `Agent "${agentId}" unregistered`
  },
})
```

### Updating and Toggling Definitions

For in-place updates, use the `RegisteredTool` handle returned by `registerTool()`:

```typescript
const mcp = useMcpServer()
const registered = mcp.registerTool('my-tool', { description: 'v1' }, handler)

// Update the description and handler
registered.update({ description: 'v2', callback: newHandler })

// Temporarily hide from the client
registered.disable()

// Re-enable
registered.enable()
```

The same pattern applies to `registerPrompt()` and `registerResource()`, which return handles with the same methods.

### Requirements

- **`nitro.experimental.asyncContext`** must be `true` in your Nuxt config (required for `useMcpServer()` to access the request context)
- Mid-session mutations are most useful with **sessions enabled**, since the server instance persists across requests. Without sessions, each request creates a fresh server, so mutations only last for a single request.

::callout{color="warning" icon="i-lucide-triangle-alert"}
Not all MCP clients support 

`notifications/tools/list_changed`

. If a client doesn't support it, the user may need to reconnect to see updated definitions. Check your client's documentation for compatibility.
::

## TypeScript

For type-safe context, extend the H3 event context:

```typescript [server/types.ts]
declare module 'h3' {
  interface H3EventContext {
    user?: {
      id: string
      name: string
      role: 'user' | 'admin'
    }
  }
}
```

## Next Steps

- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) — Set up authentication context
- [Sessions](https://mcp-toolkit.nuxt.dev/advanced/sessions) — Enable per-session state
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) — Create custom MCP endpoints


# Code Mode

## What is Code Mode?

Code Mode replaces the traditional multi-turn tool calling pattern with a single `code` tool. Instead of the LLM calling tools one at a time — each requiring a round-trip — it writes JavaScript code that orchestrates multiple tools in one execution.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Enable Code Mode in the MCP server
icon: i-lucide-code
---
Enable Code Mode in my Nuxt MCP server (@nuxtjs/mcp-toolkit).

- Install secure-exec: `pnpm add secure-exec` or `npm install secure-exec` or `yarn add secure-exec` or `bun add secure-exec` (Node >=18.16.0)
- Set experimental\_codeMode: true on the handler in server/mcp/index.ts (via defineMcpHandler)
- Code Mode replaces all registered tools with a single 'code' tool
- The LLM writes JavaScript that calls tools via a codemode object (e.g. await codemode.listUsers())
- This reduces round-trips and token usage — especially with many tools (10+ tools saves 50%+ tokens)
- Code runs in a secure V8 sandbox (workerd) — no access to filesystem, network, or Node APIs
- If there are many tools (10+), consider progressive mode (experimental\_codeMode: { progressive: true }) to keep both individual tools and the code tool — for fewer tools, standard mode is sufficient
- Code Mode is experimental — the API may evolve

Docs: <https://mcp-toolkit.nuxt.dev/advanced/code-mode>{rel=""nofollow""}
::

|                   | Traditional MCP                       | Code Mode                      |
| ----------------- | ------------------------------------- | ------------------------------ |
| **Pattern**       | LLM calls tools one by one            | LLM writes JS that calls tools |
| **Round-trips**   | One per tool call                     | One for all operations         |
| **Complex logic** | Multiple turns for conditionals/loops | Native JS control flow         |
| **Token usage**   | Higher (repeated context)             | Lower (single invocation)      |

::callout{color="warning" icon="i-lucide-flask-conical"}
Code Mode is 

**experimental for now**

. The API may evolve as we stabilize this feature based on feedback.
::

## Why Code Mode?

Every LLM round-trip resends **all tool descriptions** as context. With traditional MCP, a task that requires 5 steps with 50 tools sends the full tool catalog 5 times — that's 15,500 tokens just for tool descriptions. Code Mode sends compact TypeScript signatures in a single tool, cutting that to \~3,000 tokens.

### The scaling problem

In traditional MCP, tool description overhead scales as **tools × round-trips**. Code Mode replaces all tools with one `code` tool containing compact type signatures — and usually needs fewer round-trips.

| Server size                | Traditional MCP                     | Code Mode      | Savings  |
| -------------------------- | ----------------------------------- | -------------- | -------- |
| **10 tools**, 3-step task  | \~1,860 tokens in tool descriptions | \~920 tokens   | **-51%** |
| **25 tools**, 4-step task  | \~6,200 tokens                      | \~1,700 tokens | **-73%** |
| **50 tools**, 5-step task  | \~15,500 tokens                     | \~3,000 tokens | **-81%** |
| **100 tools**, 5-step task | \~31,000 tokens                     | \~5,600 tokens | **-82%** |

These numbers represent tool description overhead only. Total savings depend on the task, but the trend is clear: **the more tools you have, the bigger the savings**.

::callout{color="primary" icon="i-lucide-zap"}
On a real benchmark with Claude Sonnet (9 tools, 7 tasks), Code Mode saved 

**15% of total tokens overall**

 and up to 

**33% on complex batch operations**

 — collapsing 8 tool calls into a single JavaScript block.
::

### Beyond token savings

Code Mode also unlocks patterns that traditional MCP cannot do efficiently:

- **Parallel execution** — `Promise.all()` for independent calls instead of sequential round-trips
- **Conditional logic** — `if/else` branching without an extra LLM step
- **Loops** — `for` over data instead of repeating tool calls one by one
- **Error handling** — `try/catch` to handle failures mid-workflow

## Setup

### 1. Install secure-exec

Code Mode uses [secure-exec](https://github.com/nicolo-ribaudo/secure-exec){rel="&#x22;nofollow&#x22;"} to run LLM-generated code in a secure V8 isolate:

::code-group
```bash [pnpm]
pnpm add secure-exec
```

```bash [npm]
npm install secure-exec
```

```bash [yarn]
yarn add secure-exec
```

```bash [bun]
bun add secure-exec
```
::

::callout{color="info" icon="i-lucide-info"}
Code Mode requires 

`secure-exec`

 and Node.js 

`>=18.16.0`

. The rest of the module still supports Node.js 18.x, but code mode depends on 

`AsyncLocalStorage.snapshot()`

 to preserve request context.
::

### 2. Enable on a handler

Add `experimental_codeMode` to any handler:

::code-group
```typescript [Default handler]
// server/mcp/index.ts
export default defineMcpHandler({
  experimental_codeMode: true,
})
```

```typescript [Custom handler]
// server/mcp/ai-agent.ts
export default defineMcpHandler({
  name: 'ai-agent',
  experimental_codeMode: true,
  tools: [getUserTool, listTodosTool, createTodoTool],
})
```
::

That's it. The module replaces all your tools with a single `code` tool that the LLM uses to orchestrate them.

## How It Works

When Code Mode is enabled:

1. All registered tools are converted to TypeScript type definitions
2. A `code` tool is created with those types embedded in its description
3. The LLM writes JavaScript using a `codemode` object to call tools
4. The code runs in a V8 isolate with only RPC access to your tools

### Example: what the LLM generates

Given tools `get-user`, `list-todos`, and `create-todo`, the LLM receives type definitions and writes code like:

::code-group
```javascript [Sequential calls]
const user = await codemode.get_user({ id: "123" });
const todos = await codemode.list_todos({ userId: user.id });

if (todos.length === 0) {
  await codemode.create_todo({
    title: "Welcome task",
    userId: user.id,
  });
}

return { user, todos };
```

```javascript [Parallel calls]
const [users, products, orders] = await Promise.all([
  codemode.list_users(),
  codemode.list_products(),
  codemode.list_orders({ status: "pending" }),
]);

return {
  userCount: users.length,
  productCount: products.length,
  pendingOrders: orders.length,
};
```

```javascript [Loop + conditional]
const users = await codemode.list_users();
const results = [];

for (const user of users) {
  const todos = await codemode.list_todos({ userId: user.id });
  if (todos.some(t => t.overdue)) {
    await codemode.send_reminder({ userId: user.id });
    results.push(user.name);
  }
}

return { reminded: results };
```
::

## Configuration Options

Pass an options object instead of `true` for fine-grained control:

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  experimental_codeMode: {
    memoryLimit: 64,
    cpuTimeLimitMs: 10_000,
    maxResultSize: 102_400,
    maxRequestBodyBytes: 1_048_576,
    maxToolResponseSize: 1_048_576,
    wallTimeLimitMs: 60_000,
    maxToolCalls: 200,
    progressive: false,
    description: undefined,
  },
})
```

::field-group
  :::field{name="memoryLimit" type="number"}
  Default: `64`

  V8 isolate memory limit in MB. Set once at first execution — call `disposeCodeMode()` to change.
  :::

  :::field{name="cpuTimeLimitMs" type="number"}
  Default: `10000`

  CPU time limit per execution in milliseconds. The sandbox is killed after this duration.
  :::

  :::field{name="maxResultSize" type="number"}
  Default: `102400` (100 KB)

  Maximum result size in bytes before truncation. Large results are intelligently truncated — arrays by number of items, objects by number of keys.
  :::

  :::field{name="maxRequestBodyBytes" type="number"}
  Default: `1048576` (1 MB)

  Maximum bytes accepted in a single RPC request body from the sandbox. Returns HTTP 413 if exceeded. Prevents memory exhaustion from oversized payloads. Like `memoryLimit`, this applies when the RPC server **first** starts; call `disposeCodeMode()` before changing it.
  :::

  :::field{name="maxToolResponseSize" type="number"}
  Default: `1048576` (1 MB)

  Maximum bytes for individual tool RPC responses. Large results are truncated using the same strategy as `maxResultSize`.
  :::

  :::field{name="wallTimeLimitMs" type="number"}
  Default: `60000` (60 seconds)

  Per-execution deadline checked at the **start of each** sandbox→host RPC call (tool invocation or return value). After the deadline, the next RPC receives HTTP 408. This bounds host-side work (e.g. slow tools); pure CPU loops in the isolate are primarily limited by `cpuTimeLimitMs`.
  :::

  :::field{name="maxToolCalls" type="number"}
  Default: `200`

  Maximum number of tool RPC calls per execution. Prevents runaway loops that repeatedly invoke expensive tools. Returns HTTP 429 when exceeded.
  :::

  :::field{name="progressive" type="boolean"}
  Default: `false`

  Enable progressive disclosure mode. See [Progressive Mode](https://mcp-toolkit.nuxt.dev/#progressive-mode) below.
  :::

  :::field{name="description" type="string"}
  Default: built-in template

  Custom description for the `code` tool. Supports `{{types}}` and `{{count}}` placeholders.
  :::
::

## Progressive Mode

When your server exposes many tools (50+), embedding all type definitions in the `code` tool description becomes expensive in tokens. Progressive mode solves this by splitting into two tools:

1. **`search`** — discovers tools by keyword, returns their signatures
2. **`code`** — executes code using discovered tools

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  experimental_codeMode: {
    progressive: true,
  },
})
```

The LLM workflow becomes:

::code-group
```txt [Step 1 — Search]
LLM calls: search({ query: "user" })

→ Found 2/12 tools matching "user":
  codemode.get_user: (input: { id: string }) => Promise<unknown>; // Get user by ID
  codemode.list_users: () => Promise<unknown>; // List all users
```

```txt [Step 2 — Execute]
LLM calls: code({ code: "..." })

→ Executes code using the discovered tools
```
::

::callout{color="info" icon="i-lucide-info"}
Progressive mode adds an extra tool call but significantly reduces the initial prompt size. Only use it when you have a large number of tools — for small toolsets, standard mode is more efficient.
::

## Custom Description

Override the `code` tool description to customize LLM instructions:

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  experimental_codeMode: {
    description: `You have {{count}} tools available. Write JavaScript using the codemode object.

{{types}}

Always combine related operations into a single code block.`,
  },
})
```

The `{{types}}` placeholder is replaced with the generated TypeScript definitions. The `{{count}}` placeholder is replaced with the number of available tools.

In progressive mode, `{{types}}` is not available since types are discovered via the `search` tool.

## Security

Running LLM-generated code requires serious security measures. Code Mode implements **defense in depth** across 7 layers to ensure the sandbox cannot escape, access unauthorized resources, or exhaust host resources.

### Sandbox Isolation

LLM-generated code runs in a separate [V8 isolate](https://v8.dev/docs/embed){rel="&#x22;nofollow&#x22;"} via `secure-exec`. This is the same isolation technology used by Cloudflare Workers and similar platforms. The sandbox has:

- **No filesystem access** — cannot read, write, or list files
- **No Node.js APIs** — no `require()`, `import()`, `process`, `fs`, `child_process`, etc.
- **No environment variables** — cannot read secrets or configuration
- **No host process access** — cannot modify the parent process in any way

### Network Restrictions

The sandbox can only communicate with the internal RPC server. All other network access is blocked:

- **Port-locked** — Only the randomly-assigned RPC port is accessible. Other localhost services (databases, admin panels, other apps) are blocked.
- **Host-locked** — Only `127.0.0.1` and `localhost` are allowed. External hosts are rejected.
- **No DNS** — DNS resolution is disabled entirely.
- **No redirects** — HTTP redirects are rejected (`redirect: 'error'`), preventing SSRF via open redirects.

### RPC Authentication

Communication between the sandbox and the host uses a per-session cryptographic token:

- **256-bit token** — Generated with `crypto.randomBytes(32)` at RPC server startup.
- **Header-based auth** — Every request must include the token via `x-rpc-token` header.
- **403 on mismatch** — Requests without a valid token are rejected immediately.

This prevents other local processes from calling your MCP tools through the RPC port.

### Resource Limits

| Resource                     | Default    | Configurable          | Protection                                                                                |
| ---------------------------- | ---------- | --------------------- | ----------------------------------------------------------------------------------------- |
| **CPU time**                 | 10 seconds | `cpuTimeLimitMs`      | Sandbox is killed on timeout — prevents infinite loops                                    |
| **Wall-clock deadline**      | 60 seconds | `wallTimeLimitMs`     | Enforced on each RPC from the sandbox — stops further tool/return RPCs after the deadline |
| **Memory**                   | 64 MB      | `memoryLimit`         | V8 isolate hard limit — prevents OOM crashes                                              |
| **Result size**              | 100 KB     | `maxResultSize`       | Intelligent truncation (arrays by items, objects by keys)                                 |
| **Tool response size**       | 1 MB       | `maxToolResponseSize` | Per-call truncation before response delivery                                              |
| **Request body size**        | 1 MB       | `maxRequestBodyBytes` | HTTP 413 early rejection — prevents memory exhaustion                                     |
| **Tool calls per execution** | 200        | `maxToolCalls`        | HTTP 429 rate limit — prevents runaway loops                                              |
| **Log entries**              | 200        | No                    | Console output capped — prevents `console.log` flooding                                   |

### Input Validation

Tool names are interpolated into the sandbox code template. To prevent code injection:

- **Strict identifier regex** — Every tool name is validated against `/^[\w$]+$/` before being injected into the sandbox template.
- **Sanitization** — Names are sanitized upstream (`get-user` → `get_user`), but a second validation layer at the template level ensures defense in depth.
- **Rejection** — If a name fails validation, the execution throws immediately — no partial injection.

### Error Sanitization

Infrastructure errors (file paths, stack traces) are sanitized before being returned to the sandbox or the MCP client. Full error details are logged server-side with the `[nuxt-mcp-toolkit]` prefix for debugging.

### Summary

::callout{color="info" icon="i-lucide-shield"}
The sandbox can 

**only**

 communicate with your registered MCP tools via the authenticated RPC bridge. It cannot access the filesystem, network, environment, or any other host resources.
::

## Usage with Other Features

Code Mode is fully compatible with other module features. Your tools remain unchanged — only the way they are exposed to the LLM changes.

::code-group
```typescript [With Middleware]
// server/mcp/index.ts
export default defineMcpHandler({
  experimental_codeMode: true,
  middleware: async (event) => {
    const user = await getUser(event).catch(() => null)
    if (user) event.context.user = user
    // Soft auth — see /advanced/middleware. Use `enabled` guards to
    // hide tools from anonymous callers instead of throwing 401 here.
  },
})
```

```typescript [With Dynamic Definitions]
// server/mcp/tools/admin-tool.ts
export default defineMcpTool({
  name: 'admin-delete',
  description: 'Delete a resource (admin only)',
  enabled: event => event.context.user?.role === 'admin',
  inputSchema: {
    id: z.string(),
  },
  handler: async ({ id }) => {
    // Only visible in code mode when user is admin
  },
})
```

```typescript [With Progressive + Auth]
// server/mcp/index.ts
export default defineMcpHandler({
  experimental_codeMode: {
    progressive: true,
    cpuTimeLimitMs: 15_000,
  },
  middleware: async (event) => {
    const apiKey = getHeader(event, 'x-api-key')
    if (!apiKey) return
    const user = await getUserByApiKey(apiKey).catch(() => null)
    if (user) event.context.user = user
  },
})
```
::

[Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) runs before tool execution — your tools access `event.context` as usual. Tools with [`enabled` guards](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) are excluded from the generated type definitions and the `codemode` object.

## Tool Name Sanitization

MCP tool names (kebab-case) are automatically converted to valid JavaScript identifiers for the `codemode` object:

| MCP Name     | JavaScript Name |
| ------------ | --------------- |
| `get-user`   | `get_user`      |
| `list-todos` | `list_todos`    |
| `123-tool`   | `_123_tool`     |
| `delete`     | `delete_`       |

Reserved JavaScript words are suffixed with `_`. Names starting with a digit are prefixed with `_`.

## Cleanup

Call `disposeCodeMode()` during shutdown to release resources (V8 runtime, RPC server):

```typescript
import { disposeCodeMode } from '#imports'

// In a shutdown hook or cleanup function
disposeCodeMode()
```

## Next Steps

- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create custom MCP endpoints
- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) - Add authentication
- [Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) - Conditionally register tools
- [Evals](https://mcp-toolkit.nuxt.dev/advanced/evals) - Benchmark code mode vs standard MCP


# Request input from users with elicitation

## What is Elicitation?

Elicitation lets a server ask the connected client for additional information **mid-request**. The MCP spec defines two modes:

- **Form mode** — present a structured form to the user and validate the response against a schema you define.
- **URL mode*&#x2A; &#x2A;(spec 2025-11-25)* — redirect the user to an external page (sign-in, payment, account verification, …) and resume once they come back.

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Add MCP elicitation (form & URL)
icon: i-lucide-message-square-quote
---
Add elicitation to my Nuxt MCP server (@nuxtjs/mcp-toolkit).

- Use useMcpElicitation() inside a tool handler (auto-imported)
- Form mode: pass a Zod raw shape via `schema` and a human-readable `message`
- The shape must be flat — primitives, single-/multi-select enums only (spec restriction)
- Always check the action: 'accept' | 'decline' | 'cancel' before reading content
- URL mode: pass a `url` and `message`; client opens the URL and reports back
- Use `confirm(message)` for a quick yes/no prompt
- Use `supports('form' | 'url')` before calling to gate cleanly when the client doesn't support it
- Wrap in try/catch and check for McpElicitationError (codes: 'unsupported', 'invalid-schema', 'invalid-response')

Docs: <https://mcp-toolkit.nuxt.dev/advanced/elicitation>{rel=""nofollow""}
::

## When to Use Elicitation

| Use Case                                                       | Mode                |
| -------------------------------------------------------------- | ------------------- |
| Disambiguate input ("which project did you mean?")             | `form` with an enum |
| Confirm a destructive action before running it                 | `confirm`           |
| Collect missing required parameters interactively              | `form`              |
| Gather optional metadata (priority, tags, …) before submitting | `form`              |
| Prompt for sign-in or payment via an external page             | `url`               |
| Trigger an OAuth consent flow                                  | `url`               |

::callout{color="info" icon="i-lucide-info"}
Elicitation is 

**client-driven**

. Even when you call it server-side, the client is the one rendering the form or opening the URL. Always handle the case where the user declines or the client doesn't support the requested mode.
::

## `useMcpElicitation()`

Auto-imported. Must be called inside a tool, resource, or prompt handler.

```typescript [server/mcp/tools/release.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'create_release',
  description: 'Create a new release after asking for the channel',
  inputSchema: {
    name: z.string(),
  },
  handler: async ({ name }) => {
    const elicit = useMcpElicitation()

    const result = await elicit.form({
      message: `Pick a release channel for "${name}"`,
      schema: {
        channel: z.enum(['stable', 'beta', 'canary']).describe('Release channel'),
        notify: z.boolean().default(true).describe('Notify subscribers'),
      },
    })

    if (result.action !== 'accept') {
      return `Release cancelled (${result.action}).`
    }

    return `Created "${name}" on ${result.content.channel} (notify=${result.content.notify}).`
  },
})
```

The Zod shape is converted to the spec-restricted JSON Schema, the response is validated against the same shape, and `result.content` is fully typed.

### API

| Method                      | Description                                                                                                           |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `form({ message, schema })` | Ask for structured input. `schema` is a Zod raw shape (same format as `inputSchema`). Returns `{ action, content? }`. |
| `url({ message, url })`     | Open an external URL. Returns `{ action }`.                                                                           |
| `confirm(message)`          | Convenience yes/no prompt. Returns `boolean` (`true` only when the user accepts and confirms).                        |
| \`supports('form'           | 'url')\`                                                                                                              |

The `action` is one of `'accept' | 'decline' | 'cancel'`. The `content` field is only present when `action === 'accept'`.

## Schema Restrictions (Form Mode)

The MCP spec restricts elicitation requests to **flat objects with primitive properties** so any client can render them as a form. The toolkit enforces this at request time and throws `McpElicitationError('invalid-schema')` when you violate it.

Allowed:

- `z.string()`, `z.number()`, `z.boolean()`, `z.string().email()`, `z.number().int()`
- `z.enum([...])` — single-select dropdown
- `z.array(z.enum([...]))` — multi-select
- `.describe(...)`, `.default(...)`, `.optional()`

Not allowed:

- Nested `z.object({ ... })`
- `z.array(z.number())` or any array of non-string-enums
- `z.record(...)`, `z.tuple(...)`, `z.union(...)`, `z.discriminatedUnion(...)`

Need richer input? Split into multiple elicitation calls or take the data via the regular `inputSchema`.

## Confirm Helper

```typescript [server/mcp/tools/delete-project.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'delete_project',
  description: 'Delete a project after confirming with the user',
  inputSchema: { id: z.string() },
  handler: async ({ id }) => {
    const elicit = useMcpElicitation()

    if (!await elicit.confirm(`Permanently delete project ${id}?`)) {
      return 'Aborted.'
    }

    await deleteProject(id)
    return `Deleted ${id}.`
  },
})
```

`confirm()` builds on `form()` with a single `confirm: z.boolean()` field, so it inherits the same capability checks and decline handling.

## URL Mode

URL mode is opt-in per the spec — clients must declare `elicitation.url` in their capabilities. Use `supports('url')` to branch cleanly:

```typescript [server/mcp/tools/connect-github.ts]
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'connect_github',
  description: 'Connect the user GitHub account',
  inputSchema: {},
  handler: async () => {
    const elicit = useMcpElicitation()

    if (!elicit.supports('url')) {
      return 'Open https://app.example.com/settings/github to connect your account, then try again.'
    }

    const result = await elicit.url({
      message: 'Authorize the integration',
      url: 'https://app.example.com/oauth/github/start',
    })

    return result.action === 'accept'
      ? 'GitHub connected.'
      : `User did not complete the flow (${result.action}).`
  },
})
```

::callout{color="warning" icon="i-lucide-shield"}
URL-mode elicitation triggers a redirect on the user's machine — only use it for trusted endpoints. The MCP spec recommends pairing it with 

[origin/scheme validation](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization){rel=""nofollow""}

 on your callback.
::

## Capability Checks

Always handle the case where the client doesn't declare the elicitation capability — many clients (and self-hosted relays) advertise tools without it.

```typescript
const elicit = useMcpElicitation()

if (!elicit.supports('form')) {
  return 'This tool needs an interactive client (Cursor, Claude Desktop, …).'
}
```

When you call `form()` or `url()` against an unsupported client, the composable throws `McpElicitationError` with `code: 'unsupported'` so you can recover gracefully:

```typescript
import { McpElicitationError } from '@nuxtjs/mcp-toolkit/server'

try {
  await elicit.form({ message: '…', schema: { … } })
}
catch (err) {
  if (err instanceof McpElicitationError && err.code === 'unsupported') {
    return 'Client does not support elicitation — falling back to defaults.'
  }
  throw err
}
```

## Requirements

::callout{color="warning" icon="i-lucide-triangle-alert"}
`useMcpElicitation()` requires:

- `nitro.experimental.asyncContext` set to `true` (default since Nuxt 3.8+)
- A client that declared the `elicitation` capability during initialization
::

## Next Steps

- [Sessions](https://mcp-toolkit.nuxt.dev/advanced/sessions) — store the user's elicitation answers across subsequent tool calls.
- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) — gate which tools require elicitation based on context.
- [Dynamic definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions) — hide tools behind `enabled` guards instead of asking interactively.
- [Logging](https://mcp-toolkit.nuxt.dev/advanced/logging) — record elicitation outcomes (`accept` / `decline` / `cancel`) on the wide event.


# Authenticate MCP clients

## Overview

MCP endpoints can be secured using Bearer token authentication. This guide shows how to:

1. Generate and manage API keys for users
2. Validate tokens in MCP middleware
3. Access user context in your tools
4. Configure MCP clients with authentication

::prompt
---
actions:
  - copy
  - cursor
  - windsurf
description: Secure MCP endpoints with tokens
icon: i-lucide-shield-check
---
Add authentication to my Nuxt MCP endpoints (@nuxtjs/mcp-toolkit).

1. Choose an auth strategy: Better Auth API keys or custom token validation
2. Create server/mcp/index.ts with defineMcpHandler and a middleware function
3. In the middleware, read the token from getHeader(event, 'authorization') or getHeader(event, 'x-api-key')
4. Validate the token and set event.context.user with the authenticated user
5. Do NOT throw 401 errors — MCP clients will enter OAuth discovery mode. Use a soft approach instead
6. Access user context in tools via useEvent().context.user
7. Use the enabled guard on tools to hide them from unauthenticated users
8. Configure MCP clients to send the token in headers

Docs: <https://mcp-toolkit.nuxt.dev/examples/authentication>{rel=""nofollow""}
Middleware: <https://mcp-toolkit.nuxt.dev/advanced/middleware>{rel=""nofollow""}
::

::callout{color="warning" icon="i-lucide-triangle-alert"}
**Important:**

 MCP middleware should 

**not throw errors**

 for missing or invalid authentication. Throwing a 401 error will cause MCP clients to enter OAuth discovery mode, looking for 

`.well-known/oauth-*`

 endpoints that don't exist. Instead, use a "soft" approach that sets context when auth succeeds but allows requests to continue otherwise.
::

## Using Better Auth API Keys

If you're using [Better Auth](https://www.better-auth.com){rel="&#x22;nofollow&#x22;"}, you can leverage the built-in [API Key plugin](https://www.better-auth.com/docs/plugins/api-key){rel="&#x22;nofollow&#x22;"} for a complete solution.

### Server Configuration

Add the API Key plugin to your Better Auth configuration:

```typescript [server/utils/auth.ts]
import { betterAuth } from 'better-auth'
import { apiKey } from '@better-auth/api-key'

export const auth = betterAuth({
  // ... your existing config
  plugins: [
    apiKey({
      rateLimit: {
        enabled: false, // Disable rate limiting (if not needed)
      },
    }),
  ],
})
```

::callout{color="info" icon="i-lucide-info"}
The API Key plugin has rate limiting enabled by default. Disable it for development or configure appropriate limits for production.
::

### Client Configuration

Add the client plugin to use API key methods:

```typescript [composables/auth.ts]
import { createAuthClient } from 'better-auth/client'
import { apiKeyClient } from '@better-auth/api-key/client'

const client = createAuthClient({
  plugins: [
    apiKeyClient(),
  ],
})

// Create an API key
const { data } = await client.apiKey.create({ name: 'My MCP Key' })
console.log(data.key) // Save this - only shown once!

// List API keys
const { data: keys } = await client.apiKey.list()

// Delete an API key
await client.apiKey.delete({ keyId: 'key-id' })
```

### Helper Function

Create a helper function that validates API keys without throwing errors:

```typescript [server/utils/auth.ts]
export async function getApiKeyUser(event: H3Event) {
  const authHeader = getHeader(event, 'authorization')

  if (!authHeader?.startsWith('Bearer ')) {
    return null
  }

  const key = authHeader.slice(7)
  const result = await auth.api.verifyApiKey({ body: { key } })

  if (!result.valid || !result.key) {
    return null
  }

  const user = await db.query.user.findFirst({
    where: (users, { eq }) => eq(users.id, result.key!.referenceId),
  })

  if (!user) {
    return null
  }

  return { user, apiKey: result.key }
}
```

### MCP Handler with Authentication

Create a handler that sets user context when a valid API key is provided:

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  middleware: async (event) => {
    const result = await getApiKeyUser(event)
    if (result) {
      event.context.user = result.user
      event.context.userId = result.user.id
    }
  },
})
```

This approach:

- Sets `event.context.user` and `event.context.userId` when authentication succeeds
- Leaves context as `undefined` when no valid token is provided
- Tools must check for user context and return an error if not authenticated

### Using Context in Tools

Your tools can access the authenticated user from `event.context`. Two patterns work well:

1. **Hide the tool with `enabled`** — auth-required tools never appear in `tools/list` for anonymous callers (recommended).
2. **Return a user-friendly message** — the tool stays visible, but explains how to authenticate when called without a user. Avoid throwing `401` from a tool handler so MCP clients don't enter OAuth discovery.

```typescript [server/mcp/tools/create-todo.ts]
import { z } from 'zod'
import { useEvent } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'create_todo',
  description: 'Create a new todo for the authenticated user',
  enabled: event => !!event.context.userId,
  inputSchema: {
    title: z.string().describe('The title of the todo'),
    content: z.string().optional().describe('Optional description or content'),
  },
  handler: async ({ title, content }) => {
    const event = useEvent()
    const userId = event.context.userId as string

    const [todo] = await db.insert(schema.todos).values({
      title,
      content: content || null,
      userId,
      createdAt: new Date(),
      updatedAt: new Date(),
    }).returning()

    return `Todo created: ${todo.title}`
  },
})
```

```typescript [server/mcp/tools/list-todos.ts]
import { useEvent } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'list_todos',
  description: 'List all todos for the authenticated user',
  inputSchema: {},
  handler: async () => {
    const event = useEvent()
    const userId = event.context.userId as string | undefined

    if (!userId) {
      return 'Authentication required. Configure your MCP client with an API key (Authorization: Bearer …) and try again.'
    }

    const todos = await db.query.todos.findMany({
      where: (todos, { eq }) => eq(todos.userId, userId),
    })

    return todos
  },
})
```

::callout{color="info" icon="i-lucide-info"}
The 

`enabled`

 guard runs after middleware, so it sees the user context set above. See 

[Dynamic Definitions](https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions)

 for more patterns.
::

::callout{color="info" icon="i-lucide-info"}
Remember to enable `asyncContext` in your Nuxt config to use `useEvent()`:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    experimental: {
      asyncContext: true,
    },
  },
})
```
::

## Custom Token Validation

If you're not using Better Auth, you can implement your own token validation. Remember to use a soft approach that doesn't throw errors:

```typescript [server/utils/auth.ts]
import { createHash } from 'node:crypto'

export async function getTokenUser(event: H3Event) {
  const authHeader = getHeader(event, 'authorization')

  if (!authHeader?.startsWith('Bearer ')) {
    return null
  }

  const token = authHeader.slice(7)
  const tokenHash = createHash('sha256').update(token).digest('hex')

  // Look up the token in your database
  const apiToken = await db.query.apiTokens.findFirst({
    where: (tokens, { eq }) => eq(tokens.hash, tokenHash),
  })

  if (!apiToken) {
    return null
  }

  // Check expiration
  if (apiToken.expiresAt && apiToken.expiresAt < new Date()) {
    return null
  }

  return { userId: apiToken.userId }
}
```

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  middleware: async (event) => {
    const result = await getTokenUser(event)
    if (result) {
      event.context.userId = result.userId
    }
  },
})
```

## Configuring MCP Clients

### Cursor

Add your MCP server to `.cursor/mcp.json`:

```json [.cursor/mcp.json]
{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop configuration:

```json [claude_desktop_config.json]
{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}
```

### Other Clients

Most MCP clients support custom headers. Check your client's documentation for the exact configuration format.

## TypeScript

For type-safe context, extend the H3 event context:

```typescript [server/types.ts]
declare module 'h3' {
  interface H3EventContext {
    user?: {
      id: string
      name: string
      email: string
    }
    userId?: string
  }
}
```

## Security Best Practices

1. **Always hash tokens** - Store hashed tokens in your database, not plaintext
2. **Set expiration dates** - API keys should expire to limit exposure
3. **Implement rate limiting** - Prevent abuse with request limits per key
4. **Allow key revocation** - Users should be able to delete compromised keys
5. **Log key usage** - Track when keys are used for security auditing

## Next Steps

- [Middleware](https://mcp-toolkit.nuxt.dev/advanced/middleware) - Learn more about middleware options
- [Handlers](https://mcp-toolkit.nuxt.dev/handlers/overview) - Create custom authenticated handlers
- [TypeScript](https://mcp-toolkit.nuxt.dev/advanced/typescript) - Type-safe context definitions


# Integrate external APIs

## Fetching External Data

Here's a simple tool that fetches data from a public API:

```typescript [server/mcp/tools/get-weather.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Get current weather for a city',
  inputSchema: {
    city: z.string().describe('City name'),
  },
  cache: '15m',
  handler: async ({ city }) => {
    return await $fetch(`https://wttr.in/${city}?format=j1`)
  },
})
```

## Using Nuxt Server Utilities

To use Nuxt server utilities like `useEvent()` in your handlers, enable `asyncContext` on Nitro:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    experimental: {
      asyncContext: true,
    },
  },
})
```

Then you can access the H3 event and use Nuxt server composables:

```typescript [server/mcp/tools/get-page.ts]
import { z } from 'zod'
import { useEvent, createError } from 'h3'
import { queryCollection } from '@nuxt/content/server'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Get a documentation page',
  inputSchema: {
    path: z.string().describe('Page path'),
  },
  cache: '1h',
  handler: async ({ path }) => {
    const event = useEvent()

    const page = await queryCollection(event, 'docs')
      .where('path', '=', path)
      .first()

    if (!page) throw createError({ statusCode: 404, message: 'Page not found' })
    return page
  },
})
```

::callout{color="info" icon="i-lucide-info"}
`useEvent()`

 is auto-imported when 

`asyncContext`

 is enabled.
::

## Next Steps

- [Common Patterns](https://mcp-toolkit.nuxt.dev/examples/common-patterns) - More general examples
- [File Operations](https://mcp-toolkit.nuxt.dev/examples/file-operations) - File operation examples
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Learn more about tools


# Common Patterns

## Overview

This page demonstrates common patterns and real-world examples for using the Nuxt MCP module.

## Input Validation Tool

Validate user inputs like emails and URLs:

```typescript [server/mcp/tools/validate-input.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Validate common input formats like email and URL',
  inputSchema: {
    value: z.string().describe('Value to validate'),
    type: z.enum(['email', 'url']).describe('Type of validation'),
  },
  outputSchema: {
    isValid: z.boolean(),
    message: z.string(),
  },
  handler: async ({ value, type }) => {
    let isValid = false
    let message = ''

    if (type === 'email') {
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
      isValid = emailRegex.test(value)
      message = isValid ? 'Valid email address' : 'Invalid email format'
    }
    else if (type === 'url') {
      try {
        new URL(value)
        isValid = true
        message = 'Valid URL'
      }
      catch {
        message = 'Invalid URL format'
      }
    }

    return {
      structuredContent: { isValid, message },
    }
  },
})
```

## Generate Slug Tool

Generate URL-friendly slugs from titles:

```typescript [server/mcp/tools/generate-slug.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Generate a URL-friendly slug from a title',
  inputSchema: {
    title: z.string().describe('Title to convert to slug'),
    separator: z.enum(['-', '_']).default('-').describe('Word separator'),
  },
  outputSchema: {
    slug: z.string(),
  },
  handler: async ({ title, separator }) => {
    const slug = title
      .toLowerCase()
      .normalize('NFD')
      .replace(/[\u0300-\u036F]/g, '') // Remove accents
      .replace(/[^a-z0-9\s-]/g, '') // Remove special chars
      .trim()
      .replace(/\s+/g, separator) // Replace spaces
      .replace(new RegExp(`${separator}+`, 'g'), separator) // Remove duplicate separators

    return {
      structuredContent: { slug },
    }
  },
})
```

## Format Converter Tool

Convert between JSON and YAML formats:

```typescript [server/mcp/tools/convert-format.ts]
import { z } from 'zod'
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Convert between JSON and YAML formats',
  inputSchema: {
    content: z.string().describe('Content to convert'),
    from: z.enum(['json', 'yaml']).describe('Source format'),
    to: z.enum(['json', 'yaml']).describe('Target format'),
  },
  handler: async ({ content, from, to }) => {
    let data: unknown
    if (from === 'json') {
      data = JSON.parse(content)
    }
    else {
      data = parseYaml(content)
    }

    if (to === 'json') return JSON.stringify(data, null, 2)
    return stringifyYaml(data)
  },
})
```

## Health Check Tool

Check if an API or service is available:

```typescript [server/mcp/tools/health-check.ts]
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Check if a URL endpoint is reachable',
  inputSchema: {
    url: z.string().url().describe('URL to check'),
    timeout: z.number().default(5000).describe('Timeout in milliseconds'),
  },
  outputSchema: {
    status: z.enum(['healthy', 'unhealthy']),
    responseTime: z.number().optional(),
    statusCode: z.number().optional(),
  },
  handler: async ({ url, timeout }) => {
    const start = Date.now()

    try {
      const response = await $fetch.raw(url, {
        timeout,
        method: 'HEAD',
      })

      const responseTime = Date.now() - start

      return {
        structuredContent: {
          status: 'healthy' as const,
          responseTime,
          statusCode: response.status,
        },
      }
    }
    catch (error) {
      const responseTime = Date.now() - start

      return {
        structuredContent: {
          status: 'unhealthy' as const,
          responseTime,
        },
      }
    }
  },
})
```

## Next Steps

- [API Integration](https://mcp-toolkit.nuxt.dev/examples/api-integration) - API integration examples
- [File Operations](https://mcp-toolkit.nuxt.dev/examples/file-operations) - File operation examples
- [Prompt Examples](https://mcp-toolkit.nuxt.dev/examples/prompt-examples) - Prompt patterns
- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Learn more about tools


# File Operations

## Overview

This page demonstrates a simple file operation pattern using MCP resources.

## Read File Resource

Simple file reading resource:

```typescript [server/mcp/resources/readme.ts]
import { readFile } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'readme',
  title: 'README',
  uri: 'file:///README.md',
  metadata: {
    description: 'Project README file',
    mimeType: 'text/markdown',
  },
  handler: async (uri: URL) => {
    try {
      const filePath = fileURLToPath(uri)
      const content = await readFile(filePath, 'utf-8')

      return {
        contents: [{
          uri: uri.toString(),
          mimeType: 'text/markdown',
          text: content,
        }],
      }
    }
    catch (error) {
      return {
        contents: [{
          uri: uri.toString(),
          mimeType: 'text/plain',
          text: `Error reading file: ${error instanceof Error ? error.message : String(error)}`,
        }],
        isError: true,
      }
    }
  },
})
```

## Next Steps

- [API Integration](https://mcp-toolkit.nuxt.dev/examples/api-integration) - API integration examples
- [Common Patterns](https://mcp-toolkit.nuxt.dev/examples/common-patterns) - More general examples
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Learn more about resources


# Prompt Examples

## Overview

This page demonstrates advanced prompt patterns that can be used to standardize AI interactions in your project.

## Code Review Prompt

Generate a focused code review request:

```typescript [server/mcp/prompts/code-review.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'code-review',
  title: 'Code Review',
  description: 'Generate a code review prompt',
  inputSchema: {
    code: z.string().describe('Code to review'),
    language: z.string().describe('Programming language'),
    focus: z.enum(['performance', 'security', 'style', 'all']).default('all'),
  },
  handler: async ({ code, language, focus }) => {
    const focusText = focus === 'all'
      ? 'performance, security, and style'
      : focus

    return `Please review this ${language} code focusing on ${focusText}:\n\n\`\`\`${language}\n${code}\n\`\`\``
  },
})
```

## Documentation Prompt

Create documentation in various formats:

```typescript [server/mcp/prompts/documentation.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'documentation',
  title: 'Generate Documentation',
  description: 'Create documentation for code',
  inputSchema: {
    code: z.string().describe('Code to document'),
    style: z.enum(['jsdoc', 'tsdoc', 'markdown']).default('jsdoc'),
  },
  handler: async ({ code, style }) => {
    return style === 'markdown'
      ? `Generate markdown documentation for this code:\n\n\`\`\`\n${code}\n\`\`\``
      : `Generate ${style.toUpperCase()} documentation for this code:\n\n\`\`\`\n${code}\n\`\`\``
  },
})
```

## Email Template Prompt

Generate emails with customizable tone:

```typescript [server/mcp/prompts/email.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'email-template',
  title: 'Email Template',
  description: 'Generate email from template',
  inputSchema: {
    recipient: z.string().describe('Recipient name'),
    subject: z.string().describe('Email subject'),
    tone: z.enum(['formal', 'casual', 'friendly']).default('friendly'),
  },
  handler: async ({ recipient, subject, tone }) => {
    const greeting = tone === 'formal'
      ? 'Dear'
      : tone === 'casual'
        ? 'Hi'
        : 'Hello'

    return `Write an email:\n\nTo: ${recipient}\nSubject: ${subject}\nTone: ${tone}\n\nGreeting: ${greeting}`
  },
})
```

## Commit Message Prompt

Generate standardized commit messages:

```typescript [server/mcp/prompts/commit-message.ts]
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'commit-message',
  title: 'Commit Message',
  description: 'Generate a conventional commit message',
  inputSchema: {
    changes: z.string().describe('Description of the changes made'),
    type: z.enum(['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']).default('feat'),
    scope: z.string().optional().describe('Scope of the change (e.g., auth, api)'),
  },
  handler: async ({ changes, type, scope }) => {
    const scopeText = scope ? `(${scope})` : ''

    return `Generate a commit message following this format:

${type}${scopeText}: <description>

Changes made:
${changes}

Guidelines:
- Use imperative mood ("add" not "added")
- Keep the description under 72 characters
- Be specific and concise`
  },
})
```

## Next Steps

- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Learn more about prompts
- [API Integration](https://mcp-toolkit.nuxt.dev/examples/api-integration) - API integration examples
- [Common Patterns](https://mcp-toolkit.nuxt.dev/examples/common-patterns) - More tool examples


# Expose your Nuxt app to any LLM with MCP — Nuxt MCP Toolkit

::landing-hero
---
command: npx skills add https://mcp-toolkit.nuxt.dev
installCommand: npx nuxt add mcp
linkLabel: Get Started
linkTo: /getting-started/installation
---
#title
Expose your application to any AI

#description
Add a Model Context Protocol (MCP) server to your Nuxt application. Connect your features to AI clients with a Nitro-like Developer Experience.
::

::landing-features
#title
Make your App accessible to AI

#description
Use the Model Context Protocol to standardize how LLMs interact with your Nuxt application.

#features
  :::landing-feature-item
  ---
  description: Use familiar patterns like defineMcpTool and defineMcpResource. It
    feels just like writing API routes.
  icon: i-lucide-code-2
  title: Nitro-like API
  to: https://mcp-toolkit.nuxt.dev/tools/overview
  ---
  :::

  :::landing-feature-item
  ---
  description: Automatic discovery of tools, resources and prompts. Just create
    files in the server/mcp directory.
  icon: i-lucide-sparkles
  title: Zero Configuration
  to: https://mcp-toolkit.nuxt.dev/getting-started/installation
  ---
  :::

  :::landing-feature-item
  ---
  description: Define your tools with Zod schemas and full TypeScript inference.
    No more guessing argument types.
  icon: i-lucide-shield-check
  title: Type-Safe Tools
  to: https://mcp-toolkit.nuxt.dev/advanced/typescript
  ---
  :::

  :::landing-feature-item
  ---
  description: Built on the official MCP SDK, ensuring compatibility with all MCP
    clients like Claude, Cursor, ChatGPT and more.
  icon: i-lucide-check-circle-2
  title: Standard Compatible
  to: https://mcp-toolkit.nuxt.dev/getting-started/connection
  ---
  :::

  :::landing-feature-item
  ---
  description: Ship interactive UI widgets to AI hosts. Author Vue SFCs in
    app/mcp/ — bundled, sandboxed, and rendered inline by MCP Apps-compatible
    hosts.
  icon: i-lucide-app-window
  title: MCP Apps
  to: https://mcp-toolkit.nuxt.dev/apps/overview
  ---
  :::

  :::landing-feature-item
  ---
  description: Let LLMs write JavaScript that orchestrates tools in a secure V8
    sandbox. Cut token overhead by up to 82%.
  icon: i-lucide-terminal
  title: Code Mode
  to: https://mcp-toolkit.nuxt.dev/advanced/code-mode
  ---
  :::

  :::landing-feature-item
  ---
  description: Intercept requests to add authentication, logging and rate
    limiting. Access event context from your tools.
  icon: i-lucide-shield
  title: Middleware
  to: https://mcp-toolkit.nuxt.dev/advanced/middleware
  ---
  :::

  :::landing-feature-item
  ---
  description: "Cache tool and resource responses with Nitro. Just add cache: '1h'
    to any definition."
  icon: i-lucide-zap
  title: Built-in Cache
  to: https://mcp-toolkit.nuxt.dev/tools/errors-caching
  ---
  :::

  :::landing-feature-item
  ---
  description: Persist state across tool calls with useMcpSession(). Build
    multi-step workflows and track conversations.
  icon: i-lucide-save
  title: Sessions
  to: https://mcp-toolkit.nuxt.dev/advanced/sessions
  ---
  :::

  :::landing-feature-item
  ---
  description: Show different tools per user with enabled guards. Control
    visibility based on authentication, roles or context.
  icon: i-lucide-toggle-right
  title: Dynamic Definitions
  to: https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions
  ---
  :::

  :::landing-feature-item
  ---
  description: InstallButton component, SVG badges and deeplinks to let users add
    your MCP server to their IDE instantly.
  icon: i-lucide-download
  title: 1-Click Install
  to: https://mcp-toolkit.nuxt.dev/getting-started/connection
  ---
  :::

  :::landing-feature-item
  ---
  description: Create separate MCP endpoints with their own tools, resources and
    configuration. Organize by domain or version.
  icon: i-lucide-server
  title: Multiple Handlers
  to: https://mcp-toolkit.nuxt.dev/handlers/overview
  ---
  :::

  :::landing-feature-item
  ---
  description: Verify LLMs call the right tools with the AI SDK and Evalite. Catch
    regressions before they reach production.
  icon: i-lucide-flask-conical
  title: Evals
  to: https://mcp-toolkit.nuxt.dev/advanced/evals
  ---
  :::

  :::landing-feature-item
  ---
  description: Let AI assistants help you build, review and troubleshoot your MCP
    server with the Agent Skills specification.
  icon: i-lucide-wand-2
  title: Agent Skills
  to: https://mcp-toolkit.nuxt.dev/getting-started/agent-skills
  ---
  :::

  :::landing-feature-item
  ---
  description: Organize tools, resources and prompts into groups with tags.
    Auto-inferred from subdirectories or set explicitly.
  icon: i-lucide-tags
  title: Groups & Tags
  to: https://mcp-toolkit.nuxt.dev/tools/groups-organization#groups-and-tags
  ---
  :::

  :::landing-feature-item
  ---
  description: Debug your MCP server in real-time with the built-in inspector.
    View tools, resources, prompts, connections and logs.
  icon: i-lucide-bug
  title: DevTools Integrated
  to: https://mcp-toolkit.nuxt.dev/getting-started/inspector
  ---
  :::

  :::landing-feature-cta
  ---
  icon: i-lucide-arrow-right
  label: Get Started
  to: https://mcp-toolkit.nuxt.dev/getting-started/installation
  ---
  #title
  Start building now
  :::
::

::landing-code
#title
Just Write Code

#description
Define tools, resources and prompts using standard TypeScript files. No complex configuration or boilerplate required.

#tools
```ts
// server/mcp/tools/weather.ts
import { z } from 'zod'

export default defineMcpTool({
  description: 'Get current weather for a location',
  inputSchema: {
    city: z.string().describe('City name'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius')
  },
  annotations: { readOnlyHint: true },
  cache: '1h',
  handler: async ({ city, unit }) => {
    const data = await fetchWeather(city)
    return { temperature: data.temp, unit, city }
  }
})
```

#resources
```ts
// server/mcp/resources/readme.ts
export default defineMcpResource({
  file: 'README.md',
  description: 'The project documentation',
  annotations: {
    audience: ['user', 'assistant'],
    lastModified: new Date().toISOString(),
  }
})
```

#prompts
```ts
// server/mcp/prompts/summarize.ts
import { z } from 'zod'

export default defineMcpPrompt({
  description: 'Summarize a text',
  inputSchema: {
    text: z.string().describe('Text to summarize'),
    format: z.enum(['bullet-points', 'paragraph']).default('paragraph')
  },
  handler: async ({ text, format }) =>
    `Summarize this text as ${format}:\n\n${text}`
})
```
::

::landing-dev-tools
---
darkImage: /mcp-devtools-dark.png
imageAlt: Nuxt MCP DevTools
lightImage: /mcp-devtools-light.png
---
#title
Built-in Inspector

#description
Debug your MCP server in real-time. View registered tools, resources, and prompts, and monitor client connections and request logs.
::

::landing-cta
---
links:
  - label: Get Started
    to: /getting-started/installation
    icon: i-lucide-arrow-right
    trailing: true
    color: neutral
    size: xl
  - label: Star on GitHub
    to: https://github.com/nuxt-modules/mcp-toolkit
    icon: i-lucide-github
    trailing: true
    color: neutral
    variant: ghost
    size: xl
---
#title
Ready to build your first MCP Server?

#description
Get started in minutes with our comprehensive guide and examples.
::