NuxtMCP Toolkit
Getting Started

Configuration

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).
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
autoImports
boolean
Default: trueAuto-import MCP helpers (defineMcpTool, defineMcpResource, etc.), types (McpToolExtra, …), composables (useMcpSession, useMcpServer), and the InstallButton component. Set to false to disable all auto-imports and require explicit imports from @nuxtjs/mcp-toolkit/server.
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 resumability.Pass true for defaults or an object with:
  • enabled - Enable or disable sessions
  • maxDuration - Session timeout in milliseconds (default: 1800000 / 30 minutes)

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

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 McpToolExtra } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Echo back a message',
  inputSchema: { message: z.string() },
  handler: async ({ message }, extra: McpToolExtra) => {
    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

Installation

Install and configure the Nuxt MCP module in your project.

MCP Inspector

Visual debugging tool integrated into Nuxt DevTools

Copyright © 2026