Handlers

Structure & options

Required fields and every defineMcpHandler option, including tools, resources, and prompts.

Handler Structure

A handler definition consists of:

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

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

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

export default defineMcpHandler({
  name: 'handler-name',
  version: '1.0.0',              // Handler version
  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.

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.

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

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

`route` (optional)

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

This option is only used for custom handlers. For the default handler override (index.ts), use mcp.route in nuxt.config.ts instead.

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.

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.

server/mcp/custom.ts

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

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

See the Middleware guide for detailed documentation and examples.

`experimental_codeMode` (optional)

Enable Code Mode to let LLMs orchestrate multiple tool calls in a single JavaScript execution. Pass true for defaults or an options object:

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.

See the Code Mode guide for full documentation, security details, and configuration options.

`tools` (optional)

Array of tool definitions specific to this handler, or a function that returns tools dynamically based on request context:

import { defineMcpTool, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

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

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

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

export default defineMcpHandler({
  name: 'custom',
  middleware: async (event) => {
    event.context.user = await getUser(event)
  },
  tools: async (event) => {
    const base = [publicTool]
    if (event.context.user?.role === 'admin') {
      base.push(adminTool)
    }
    return base
  },
})

See the Dynamic Definitions guide for details on auth-based filtering and the enabled guard.

`resources` (optional)

Array of resource definitions specific to this handler.

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

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

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

`prompts` (optional)

Array of prompt definitions specific to this handler.

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

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

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

Edit this pageorReport an issue

Default & custom handlers

Override the default `/mcp` handler and add custom defineMcpHandler endpoints.

Examples & routing

Full handler examples, multiple handlers, routes, and default vs custom comparison.