Getting Started

Configure the module

Configure the Nuxt MCP module to fit your needs.

Basic Configuration

Add the module to your nuxt.config.ts:

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:

enabled

boolean

Default: trueEnable or disable the MCP server.

route

string

Default: '/mcp'The HTTP route where the MCP server will be accessible.

browserRedirect

string

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

name

string

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

version

string

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

description

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).

instructions

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).

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.

icons

McpIcon[]

Optional. Icons for the server, displayed by clients in their UI. Each entry needs src and mimeType, with optional sizes and theme:

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' },
    ],
  },
})

dir

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)

appsDir

string

Default: 'mcp'Base directory for MCP Apps.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.

defaultHandlerStrategy

'orphans' | 'all'

Default: 'orphans'Controls which auto-discovered definitions land on the default /mcp route when named handlers 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.

autoImports

boolean

Default: trueAuto-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.

logging

boolean

Optional. Server-side observability for every MCP request via evlog, 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() to push extra fields and discrete events.

sessions

boolean | object

Default: falseEnable MCP session management (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.

security

object

Optional. Hardens Streamable HTTP 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:

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:

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:

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):

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:

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.

See the Sessions guide for the full useMcpSession() API, use cases, and examples.

Disable Auto-Imports

If you prefer explicit imports over auto-imports:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    autoImports: false,
  },
})

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

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:

nuxt.config.ts

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

Runtime Configuration

Access configuration at runtime:

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 - Learn how to create tools
Resources - Create resources
Prompts - Create prompts
Sessions - Per-session state with useMcpSession()
Custom Paths - Advanced path configuration

Edit this pageorReport an issue

Installation

Install and configure the Nuxt MCP module in your project.

Inspector

Visual debugging tool integrated into Nuxt DevTools.