---
title: "Default & custom handlers"
description: "Override the default `/mcp` handler and add custom defineMcpHandler endpoints."
canonical_url: "https://mcp-toolkit.nuxt.dev/handlers/default-and-custom"
---
# Default & custom handlers

> Override the default `/mcp` handler and add custom defineMcpHandler endpoints.

## Default Handler

By default, the module creates a single MCP endpoint at `/mcp` (or your configured route) that includes all tools, resources, and prompts from the `server/mcp/` directory.

### Overriding the Default Handler

You can override the default handler's configuration by creating an `index.ts` file in `server/mcp/`:

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  version: '2.0.0',
  browserRedirect: '/docs',
  // If tools/resources/prompts not specified, uses global definitions
})
```

This allows you to customize:

- `version` - Override the server version
- `browserRedirect` - Override the browser redirect URL
- `name` - Override the server name (optional)
- `tools`, `resources`, `prompts` - Use specific definitions instead of global ones
- `middleware` - Add request interception for auth, logging, etc. ([learn more](https://mcp-toolkit.nuxt.dev/advanced/middleware))

<callout color="info" icon="i-lucide-info">

The `route` property is **ignored** for the default handler. To change the route, use `mcp.route` in your `nuxt.config.ts`.

</callout>

#### Example: Custom Version and Redirect

```typescript [server/mcp/index.ts]
export default defineMcpHandler({
  name: 'My Documentation MCP',
  version: '1.2.0',
  browserRedirect: '/getting-started',
})
```

#### Example: Limiting Exposed Tools

```typescript [server/mcp/index.ts]
import { myTool, anotherTool } from './tools/my-tools'

export default defineMcpHandler({
  // Only expose specific tools instead of all tools in server/mcp/tools/
  tools: [myTool, anotherTool],
})
```

To let **clients** pick a subset per connection (without a custom handler), they send `X-MCP-Tools`. See [Limit available tools](https://mcp-toolkit.nuxt.dev/getting-started/connection#limit-available-tools).

## Custom Handlers

Create custom handlers using `defineMcpHandler`:

```typescript [server/mcp/migration.ts]
import { z } from 'zod'
import { defineMcpTool, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const migrationTool = defineMcpTool({
  name: 'migrate-v3-to-v4',
  title: 'Migrate v3 to v4',
  description: 'Migrate code from version 3 to version 4',
  inputSchema: {
    code: z.string().describe('The code to migrate'),
  },
  handler: async ({ code }) => {
    return code.replace(/v3/g, 'v4')
  },
})

export default defineMcpHandler({
  name: 'migration',
  version: '0.1.0',
  route: '/mcp/migration',
  tools: [migrationTool],
  browserRedirect: '/',
})
```


## Sitemap

See the full [sitemap](https://mcp-toolkit.nuxt.dev/sitemap.md) for all pages.