Manage MCP

Complete skill for managing Model Context Protocol (MCP) servers in Nuxt applications. Setup, create, customize with middleware and handlers, review, and troubleshoot.

When to Use

• Setup: "Setup an MCP server in my Nuxt app"
• Create: "Create a tool to calculate BMI" / "Add a resource to read the README"
• Customize: "Add authentication to my MCP server" / "Create middleware for rate limiting"
• Review: "Review my MCP implementation" / "Check for best practices"
• Troubleshoot: "My auto-imports aren't working" / "Cannot connect to endpoint"
• Test: "Create tests for my MCP tools"

Setup MCP Server

Installation

Automatic (recommended):

npx nuxt module add mcp-toolkit

Manual:

pnpm add -D @nuxtjs/mcp-toolkit zod

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'My MCP Server',
  },
})

Directory Structure

server/mcp/
├── tools/           # Actions AI can perform
│   ├── admin/       # Subdirectory → group: 'admin'
│   └── content/     # Subdirectory → group: 'content'
├── resources/       # Data AI can read
└── prompts/         # Message templates

Verification

1. Start: pnpm dev
2. Check: http://localhost:3000/mcp (should redirect)
3. Open DevTools (Shift+Alt+D) → MCP tab

Create Tools

Tools are functions AI assistants can call.

Basic Structure

import { z } from 'zod'

export default defineMcpTool({
  description: 'What the tool does',
  inputSchema: {
    param: z.string().describe('Parameter description'),
  },
  handler: async ({ param }) => {
    return 'Result' // or return { foo: 'bar' } for JSON; full CallToolResult still supported
  },
})

Input Patterns

// Required
name: z.string().describe('User name')

// Optional with default
limit: z.number().default(10).describe('Max results')

// Enum
format: z.enum(['json', 'xml']).describe('Format')

// Array
tags: z.array(z.string()).describe('Tags')

Error Handling

if (!param) {
  throw createError({ statusCode: 400, message: 'Error: param required' })
}

Annotations

Behavioral hints that help MCP clients decide when to prompt for confirmation:

export default defineMcpTool({
  annotations: {
    readOnlyHint: true,     // Only reads data, no side effects
    destructiveHint: false,  // Does not delete or destroy data
    idempotentHint: false,   // Multiple calls may have different effects
    openWorldHint: false,    // No external API calls
  },
  // ...
})

Common patterns: read-only tools → readOnlyHint: true, create → idempotentHint: false, update → idempotentHint: true, delete → destructiveHint: true, idempotentHint: true.

Input Examples

Type-safe usage examples that help AI models fill in parameters correctly:

export default defineMcpTool({
  inputSchema: {
    title: z.string().describe('Todo title'),
    content: z.string().optional().describe('Description'),
  },
  inputExamples: [
    { title: 'Buy groceries', content: 'Milk, eggs, bread' },
    { title: 'Fix login bug' },
  ],
  // ...
})

Groups and Tags

Organize tools with group and tags for filtering and progressive discovery:

export default defineMcpTool({
  group: 'admin',
  tags: ['destructive', 'user-management'],
  description: 'Delete a user account',
  // ...
})

Groups are auto-inferred from subdirectories: server/mcp/tools/admin/delete-user.ts → group: 'admin'. Explicit group takes precedence.

Caching

export default defineMcpTool({
  cache: '5m',  // 5 minutes
  // ...
})

See detailed examples →

Create Resources

Resources expose read-only data.

File Resource

import { readFile } from 'node:fs/promises'

export default defineMcpResource({
  description: 'Read a file',
  uri: 'file:///README.md',
  mimeType: 'text/markdown',
  handler: async (uri: URL) => {
    const content = await readFile('README.md', 'utf-8')
    return {
      contents: [{
        uri: uri.toString(),
        text: content,
        mimeType: 'text/markdown',
      }],
    }
  },
})

API Resource

export default defineMcpResource({
  description: 'Fetch API data',
  uri: 'api:///users',
  mimeType: 'application/json',
  cache: '5m',
  handler: async (uri: URL) => {
    const data = await $fetch('https://api.example.com/users')
    return {
      contents: [{
        uri: uri.toString(),
        text: JSON.stringify(data, null, 2),
        mimeType: 'application/json',
      }],
    }
  },
})

Dynamic Resource