How to build an MCP server with Nuxt

The Model Context Protocol (MCP) lets AI assistants call functions, read data, and use prompt templates from your application. With the Nuxt MCP Toolkit (@nuxtjs/mcp-toolkit), you can add an MCP server directly to your Nuxt app and expose your application's features to tools like Cursor, VS Code, and Claude Desktop. The module handles protocol details, input validation, and auto-discovery so you can focus on building what your MCP server does.

This guide walks you through installing the module, creating tools, resources, and prompt templates, connecting your IDE, debugging with the built-in MCP Inspector, and adding authentication to protect your endpoints.

Before you begin, make sure you have:

• A Nuxt 3.x or 4.x project.
• Node.js 18 or higher.
• The zod package installed in your project.

If you're working with an AI coding agent like Claude Code or Cursor, you can scaffold the starter project and hand off implementation with this prompt:

You are an expert at creating MCP servers.

I'm using the Nuxt MCP starter from nuxt-modules/mcp-toolkit (apps/mcp-starter). Scaffold it with npx giget@latest gh:nuxt-modules/mcp-toolkit/apps/mcp-starter my-app, then pnpm install and pnpm dev.

The documentation can be found at https://mcp-toolkit.nuxt.dev. Use the 'site:' operator when calling your Web Search tool, so you only discover information from the docs.

Tools, resources, and prompts go under server/mcp/. Use defineMcpTool, defineMcpResource, and defineMcpPrompt from @nuxtjs/mcp-toolkit/server, with Zod for schemas — same style as the existing files.

Once my project is ready, ask me what I want this MCP server to do, then please help me implement it.

Add the agent skill to teach your AI coding agent about the toolkit:

npx skills add https://mcp-toolkit.nuxt.dev

Use the add-mcp CLI to add the documentation MCP to your agent:

npx add-mcp https://mcp-toolkit.nuxt.dev/mcp

The Nuxt MCP Toolkit adds an HTTP endpoint (by default at /mcp) to your Nuxt application. AI clients connect to this endpoint using the MCP protocol. The module scans your server/mcp/ directory for tool, resource, and prompt definitions, then registers them automatically. When an AI assistant sends a request, the module validates inputs with Zod, runs your handler, and returns the result.

Your project structure looks like this after setup:

your-project/
├── server/
│   └── mcp/
│       ├── tools/         # Functions that AI assistants can call
│       ├── resources/     # Read-only data for AI context
│       └── prompts/       # Reusable prompt templates
├── nuxt.config.ts
└── package.json

Files placed in these directories are discovered and registered without any manual wiring.

Run the automatic installer, which adds the package and updates your Nuxt config:

npx nuxt module add mcp-toolkit

If you prefer manual setup, install @nuxtjs/mcp-toolkit and its peer dependency zod:

pnpm add @nuxtjs/mcp-toolkit zod

Then add the module to your nuxt.config.ts:

1
export default defineNuxtConfig({
2
  modules: ['@nuxtjs/mcp-toolkit'],
3
})

The module works with defaults that cover most cases. To customize the server name, endpoint route, or file directory, pass options under the mcp key:

1
export default defineNuxtConfig({
2
  modules: ['@nuxtjs/mcp-toolkit'],
3
  mcp: {
4
    name: 'My MCP Server',
5
    route: '/mcp',
6
    dir: 'mcp',
7
  },
8
})

Here's what each option does:

Tools are functions that AI assistants can call to perform actions or retrieve information. Each tool validates its input with Zod and returns a result.

Create a file in server/mcp/tools/:

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

The name and title fields are optional. If you omit them, the module generates both from the filename. A file named list-users.ts becomes name: 'list-users' and title: 'List Users'.

Your handler receives the validated input object and can return a string, number, boolean, object, or a full CallToolResult. For error cases, throw an error with createError from h3:

1
import { z } from 'zod'
2
import { createError } from 'h3'
3
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
4

5
export default defineMcpTool({
6
  description: 'Look up a user by ID',
7
  inputSchema: {
8
    userId: z.string().describe('The user ID to look up'),
9
  },
10
  handler: async ({ userId }) => {
11
    const user = await db.query.users.findFirst({
12
      where: (users, { eq }) => eq(users.id, userId),
13
    })
14

15
    if (!user) {
16
      throw createError({ statusCode: 404, message: 'User not found' })
17
    }
18

19
    return { name: user.name, email: user.email }
20
  },
21
})

Resources expose read-only data that AI assistants can use as context. Unlike tools, resources are application-driven: the host application (or user) decides when to include resource content in a conversation, not the AI model.

The quickest way to expose a file is with the file property:

1
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'
2

3
export default defineMcpResource({
4
  name: 'readme',
5
  description: 'Project README file',
6
  file: 'README.md',
7
})

The module handles URI generation, MIME type detection, and file reading automatically.

For custom data sources, define a uri and handler manually:

1
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'
2

3
export default defineMcpResource({
4
  name: 'db-schema',
5
  description: 'Database schema definition',
6
  uri: 'app://schema/database',
7
  mimeType: 'application/json',
8
  handler: async (uri) => {
9
    const schema = await getDbSchema()
10
    return {
11
      contents: [{
12
        uri: uri.toString(),
13
        text: JSON.stringify(schema, null, 2),
14
        mimeType: 'application/json',
15
      }],
16
    }
17
  },
18
})

Use resources for files, configs, database schemas, and logs. Use tools when the AI needs to perform an action or modify state.

Prompts are reusable message templates that appear in your IDE when you type / in the chat. They standardize how you interact with AI assistants for common tasks.

import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'review-code',
  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 focusArea = focus === 'all'
      ? 'performance, security, and style'
      : focus

    return `Please review this ${language} code focusing on ${focusArea}:\n\n\`\`\`${language}\n${code}\n\`\`\``
  },
})

Handlers can return a plain string (auto-wrapped as a user message) or a full GetPromptResult with a messages array for multi-turn conversations. Prompt arguments must be strings since the MCP protocol requires it.

Start your Nuxt dev server, then connect your AI assistant to the MCP endpoint.

Use the add-mcp CLI to add your MCP to Claude Code, OpenCode, and more.

npx add-mcp http://localhost:3000/mcp

Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "my-nuxt-app": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Add the server to .vscode/mcp.json in your project:

{
  "servers": {
    "my-nuxt-app": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Replace my-nuxt-app with your project name and update the URL if you changed the route or port.

The module includes an integration with the MCP Inspector, a visual debugging tool built into Nuxt DevTools. To use it:

1. Enable DevTools in your Nuxt config:

1
export default defineNuxtConfig({
2
  modules: ['@nuxtjs/mcp-toolkit'],
3
  devtools: { enabled: true },
4
})

1. Open Nuxt DevTools and navigate to the MCP Inspector tab under the Server section.
2. Click Launch Inspector to browse your tools, resources, and prompts, test them with custom parameters, and view request/response history.

The inspector connects to your MCP server automatically with the correct configuration.

To secure your MCP endpoints, add Bearer token validation through the module's middleware system.

import { getHeader } from 'h3'

export default defineMcpHandler({
  middleware: async (event) => {
    const authHeader = getHeader(event, 'authorization')

    if (!authHeader?.startsWith('Bearer ')) {
      return
    }

    const token = authHeader.slice(7)
    const user = await validateToken(token)

    if (user) {
      event.context.user = user
      event.context.userId = user.id
    }
  },
})

MCP middleware should not throw errors when authentication is missing or invalid. Throwing a 401 causes MCP clients to enter OAuth discovery mode, looking for .well-known/oauth-* endpoints that don't exist. Instead, set context when auth succeeds and let requests continue otherwise. Your tools can then check for user context:

1
import { useEvent, createError } from 'h3'
2
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
3

4
export default defineMcpTool({
5
  description: 'List todos for the authenticated user',
6
  inputSchema: {},
7
  handler: async () => {
8
    const event = useEvent()
9
    const userId = event.context.userId as string
10

11
    if (!userId) {
12
      throw createError({
13
        statusCode: 401,
14
        message: 'Authentication required. Provide a valid API key.',
15
      })
16
    }
17

18
    return await db.query.todos.findMany({
19
      where: (todos, { eq }) => eq(todos.userId, userId),
20
    })
21
  },
22
})

To use useEvent() inside tool handlers, enable asyncContext in your Nuxt config:

1
export default defineNuxtConfig({
2
  nitro: {
3
    experimental: {
4
      asyncContext: true,
5
    },
6
  },
7
})
8

Configure MCP clients to send the token in request headers (e.g., Cursor):

{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

If you visit the MCP endpoint in a browser, you'll be redirected to the browserRedirect URL (by default /). MCP endpoints are designed for programmatic access by AI clients, not browsers. Use the MCP Inspector or your IDE to interact with the server.

Confirm that autoImports isn't set to false in your MCP config. If you've disabled auto-imports, import helpers explicitly:

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

Make sure your tool files are in the correct directory (server/mcp/tools/ by default) and that each file has a default export using defineMcpTool. Restart your dev server after adding new files.

Enable asyncContext in your Nitro configuration. Without it, useEvent() won't have access to the current request context inside async handlers.

• Nuxt MCP Toolkit documentation
• Model Context Protocol specification
• Vercel Functions documentation
• Nuxt deployment guide