NuxtMCP Toolkit
Advanced Topics

Custom Paths

Customize where the module looks for MCP definitions.

Default Path Structure

By default, the module looks for definitions in:

server/
└── mcp/
    ├── tools/
    │   └── # Tool definitions
    ├── resources/
    │   └── # Resource definitions
    └── prompts/
        └── # Prompt definitions

Changing the Base Directory

Change the base directory using the dir configuration option:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    dir: 'my-mcp', // Look in server/my-mcp/ instead of server/mcp/
  },
})

This will look for definitions in:

server/
└── my-mcp/
    ├── tools/
    │   └── # Tool definitions
    ├── resources/
    │   └── # Resource definitions
    └── prompts/
        └── # Prompt definitions

Extending Paths with Hooks

For more advanced use cases, use the mcp:definitions:paths hook to add additional directories to scan. This is useful when you want to share definitions across multiple modules or layers.

Using the Hook in nuxt.config.ts

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Add additional paths for tools
      paths.tools.push('shared/tools')

      // Add additional paths for resources
      paths.resources.push('shared/resources')

      // Add additional paths for prompts
      paths.prompts.push('shared/prompts')
    },
  },
})

Using the Hook in a Custom Module

my-module.ts
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('mcp:definitions:paths', (paths) => {
      // Add additional paths for tools
      paths.tools.push('shared/tools')

      // Add additional paths for resources
      paths.resources.push('shared/resources')

      // Add additional paths for prompts
      paths.prompts.push('shared/prompts')
    })
  },
})

Path Structure

The paths object has the following structure:

{
  tools: string[]      // Array of tool directory paths
  resources: string[]  // Array of resource directory paths
  prompts: string[]    // Array of prompt directory paths
  handlers: string[]   // Array of handler directory paths
}

All paths are relative to the server/ directory of each Nuxt layer.

Example: Shared Definitions

Share definitions across multiple Nuxt layers:

project/
├── shared/
│   ├── tools/
│   │   └── common-tool.ts
│   └── resources/
│       └── common-resource.ts
└── apps/
    ├── web/
    │   └── server/
    │       └── mcp/
    │           └── tools/
    │               └── web-tool.ts
    └── api/
        └── server/
            └── mcp/
                └── tools/
                    └── api-tool.ts

Configure the hook to include shared definitions:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Include shared tools from project root
      paths.tools.push('../../shared/tools')
      paths.resources.push('../../shared/resources')
      paths.prompts.push('../../shared/prompts')
    },
  },
})

Example: Multiple Source Directories

Scan multiple directories for definitions:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    dir: 'mcp', // Default directory
  },
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Add additional tool directories
      paths.tools.push('legacy-tools')
      paths.tools.push('new-tools')

      // Add additional resource directories
      paths.resources.push('external-resources')
    },
  },
})

This will scan:

  • server/mcp/tools/ (default)
  • server/legacy-tools/
  • server/new-tools/
  • server/mcp/resources/ (default)
  • server/external-resources/

Example: Layer-Specific Paths

In a Nuxt layer setup, configure paths per layer:

layers/api/nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  hooks: {
    'mcp:definitions:paths'(paths) {
      // Only include API-specific tools
      paths.tools = ['api/tools']
      paths.resources = ['api/resources']
    },
  },
})

Path Resolution

Paths are resolved relative to:

  1. The server/ directory of the current Nuxt layer
  2. The project root (for absolute paths)
// Relative to server/
paths.tools.push('custom/tools')

// Absolute from project root
paths.tools.push('/absolute/path/to/tools')

Best Practices

  1. Use descriptive directory names: Make it clear what each directory contains
  2. Keep paths organized: Group related definitions together
  3. Document custom paths: Add comments explaining why custom paths are used
  4. Test path resolution: Ensure paths resolve correctly in all environments
  5. Consider layer structure: Use layers for complex multi-app setups

Next Steps

Handlers

Create custom MCP endpoints with their own tools, resources, and prompts.

Middleware

Intercept MCP requests to add authentication, logging, analytics, and more.

Copyright © 2026