Handlers
Sharing & practices
Cross-handler tool sharing, file layout, use cases, and next steps.
Use Cases
1. Feature Separation
Separate different features into different handlers:
server/mcp/user-management.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'users',
tools: [getUserTool, createUserTool, updateUserTool],
})
server/mcp/content-management.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'content',
tools: [createPostTool, updatePostTool, deletePostTool],
})
2. Versioned APIs
Create versioned handlers:
server/mcp/api-v1.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'api-v1',
version: '1.0.0',
route: '/api/v1/mcp',
tools: [ ... ],
})
server/mcp/api-v2.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'api-v2',
version: '2.0.0',
route: '/api/v2/mcp',
tools: [ ... ],
})
3. Domain-Specific Handlers
Organize by domain:
server/mcp/ecommerce.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'ecommerce',
tools: [addToCartTool, checkoutTool, getProductsTool],
})
server/mcp/analytics.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'analytics',
tools: [getStatsTool, generateReportTool],
})
Sharing Tools Between Handlers
You can share tool definitions between handlers by exporting them from a separate file:
server/mcp/shared-tools.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export const sharedTool = defineMcpTool({
name: 'shared-tool',
description: 'A shared tool',
inputSchema: {
input: z.string(),
},
handler: async ({ input }) => `Shared: ${input}`,
})
server/mcp/handler1.ts
import { sharedTool } from './shared-tools'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'handler1',
tools: [sharedTool],
})
server/mcp/handler2.ts
import { sharedTool } from './shared-tools'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
name: 'handler2',
tools: [sharedTool],
})
File Organization
Organize handlers in your server/mcp/ directory:
server/
└── mcp/
├── index.ts # Default handler override (optional)
├── migration.ts # Custom handler
├── api-handler.ts # Custom handler
├── admin.ts # Custom handler
├── shared-tools.ts # Shared tool definitions
├── tools/
│ └── # Tools for default handler
├── resources/
│ └── # Resources for default handler
└── prompts/
└── # Prompts for default handler
The
index.ts file is special - it overrides the default handler configuration instead of creating a new custom handler.Best Practices
- Use descriptive names: Make handler names clear and specific
- Group related functionality: Put related tools/resources together
- Version your handlers: Use semantic versioning for handler versions
- Document your handlers: Add comments explaining what each handler does
- Keep handlers focused: Each handler should have a clear, single purpose
Next Steps
- Code Mode - Orchestrate tools with LLM-generated JavaScript
- Middleware - Add authentication and logging
- Dynamic Definitions - Conditionally register definitions
- Configuration - Configure the default handler
- Tools - Create tools for your handlers
- Examples - See more handler examples