Handlers
Examples & routing
Full handler examples, multiple handlers, routes, and default vs custom comparison.
Complete Example
Here's a complete example of a custom handler:
server/mcp/api-handler.ts
import { z } from 'zod'
import { defineMcpTool, defineMcpResource, defineMcpPrompt, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
const getUserTool = defineMcpTool({
name: 'get-user',
description: 'Get user information',
inputSchema: {
userId: z.string(),
},
handler: async ({ userId }) => {
const user = await db.users.find(userId)
return user
},
})
const createUserTool = defineMcpTool({
name: 'create-user',
description: 'Create a new user',
inputSchema: {
name: z.string(),
email: z.string().email(),
},
handler: async ({ name, email }) => {
const user = await db.users.create({ name, email })
return `User created: ${user.id}`
},
})
// Define resources for this handler
const userResource = defineMcpResource({
name: 'user',
uri: 'api://users/{id}',
handler: async (uri, variables) => {
const id = variables.id as string
const user = await db.users.find(id)
return {
contents: [{
uri: uri.toString(),
mimeType: 'application/json',
text: JSON.stringify(user),
}],
}
},
})
// Define prompts for this handler
const userPrompt = defineMcpPrompt({
name: 'user-help',
description: 'Get help with user operations',
handler: async () => {
return {
messages: [{
role: 'user',
content: {
type: 'text',
text: 'How can I manage users?',
},
}],
}
},
})
// Export the handler
export default defineMcpHandler({
name: 'api',
version: '1.0.0',
route: '/mcp/api',
tools: [getUserTool, createUserTool],
resources: [userResource],
prompts: [userPrompt],
browserRedirect: '/docs/api',
})
Multiple Handlers
You can create multiple handlers in your application:
server/
└── mcp/
├── migration.ts # Migration handler
├── api-handler.ts # API handler
├── admin-handler.ts # Admin handler
├── tools/
│ └── echo.ts # Default handler tools
├── resources/
│ └── readme.ts # Default handler resources
└── prompts/
└── greeting.ts # Default handler prompts
Each handler file should export a default handler definition:
server/mcp/migration.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'migration',
tools: [ ... ],
})
server/mcp/api-handler.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'api',
tools: [ ... ],
})
Handler Routes
The handler's name determines where it will be mounted. By default, handlers are accessible at /mcp/:name where :name is the handler's name:
- Handler with
name: 'migration'→ mounted at/mcp/migration - Handler with
name: 'api'→ mounted at/mcp/api - Handler with
name: 'admin'→ mounted at/mcp/admin
You can also specify a custom route to override the default:
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'api',
route: '/api/mcp/v1', // Custom route instead of /mcp/api
})
Default vs Custom Handlers
| Feature | Default Handler | Default Handler Override (index.ts) | Custom Handler |
|---|---|---|---|
| Route | /mcp (via config) | /mcp (via config) | /mcp/:name (or custom route) |
| Tools | From server/mcp/tools/ | Custom or global | Defined in handler |
| Resources | From server/mcp/resources/ | Custom or global | Defined in handler |
| Prompts | From server/mcp/prompts/ | Custom or global | Defined in handler |
| Name | From config | Custom or config | Handler name (required) |
| Version | From config | Custom or config | Handler version |