NuxtMCP Toolkit
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
})

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

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.

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.

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.

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

export default defineMcpHandler({
  name: 'admin',
  icons: [
    { src: 'https://example.com/admin.png', mimeType: 'image/png', sizes: ['64x64'] },
  ],
})
description, instructions, and icons are part of the MCP lifecycle spec. 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.

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)

Accepts three shapes — pick whichever matches your use case:

// 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,
})
See multi-handler organization for the folder convention, and getMcpTools for ad-hoc filtering. Per-tool enabled() guards apply automatically — see Dynamic Definitions.

resources (optional)

Same shapes as tools: omit for folder-convention auto-attribution, pass an array, or pass event => getMcpResources({ event, ... }).

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: omit for folder-convention auto-attribution, pass an array, or pass event => getMcpPrompts({ event, ... }).

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

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

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

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.

Copyright © 2026