---
title: "Handlers"
description: "Create custom MCP endpoints with their own tools, resources, and prompts."
canonical_url: "https://mcp-toolkit.nuxt.dev/handlers/overview"
---
# Handlers

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

## What are Handlers?

Handlers allow you to create **multiple MCP endpoints** in a single Nuxt application. Each handler has its own route, name, version, and can include its own set of tools, resources, and prompts.

<prompt :actions="["copy","cursor","windsurf"]" description="Create a custom MCP handler and endpoint" icon="i-lucide-server">

Create a custom MCP handler with its own endpoint and tools using @nuxtjs/mcp-toolkit.

- Create a .ts file at the root of server/mcp/ (e.g. server/mcp/admin.ts) — files in subdirectories like tools/, resources/, prompts/ are definitions, not handlers
- Use defineMcpHandler (auto-imported) with name, route, tools, resources, and prompts
- Set the route explicitly (e.g. route: '/mcp/admin')
- Define tools inline with defineMcpTool or import shared tools
- Override the default handler by creating server/mcp/index.ts with defineMcpHandler
- Add middleware for handler-specific authentication or logging
- Set version and browserRedirect per handler

Docs: [https://mcp-toolkit.nuxt.dev/handlers/overview](https://mcp-toolkit.nuxt.dev/handlers/overview)

</prompt>

This is useful when you want to:

- Separate different MCP functionalities into different endpoints
- Create versioned MCP APIs
- Organize tools/resources by domain or feature

## Guides

<card-group>
<card color="neutral" icon="i-lucide-network" title="Multi-handler organization" to="https://mcp-toolkit.nuxt.dev/handlers/organization">

Folder convention to attribute tools, resources, and prompts to MCP routes — plus the `getMcp*` escape hatch.

</card>

<card color="neutral" icon="i-lucide-toggle-left" title="Default & custom handlers" to="https://mcp-toolkit.nuxt.dev/handlers/default-and-custom">

Override `/mcp` via `server/mcp/index.ts`, or expose new endpoints with `defineMcpHandler`.

</card>

<card color="neutral" icon="i-lucide-sliders-horizontal" title="Structure & options" to="https://mcp-toolkit.nuxt.dev/handlers/structure-and-options">

Every `defineMcpHandler` field — `name`, `route`, `middleware`, `tools`, `experimental_codeMode`.

</card>

<card color="neutral" icon="i-lucide-share-2" title="Sharing & practices" to="https://mcp-toolkit.nuxt.dev/handlers/sharing-practices">

Cross-handler tool sharing, file layout, and use cases.

</card>
</card-group>

---

- [Default & custom](https://mcp-toolkit.nuxt.dev/handlers/default-and-custom)
- [Structure & options](https://mcp-toolkit.nuxt.dev/handlers/structure-and-options)
- [Examples & routing](https://mcp-toolkit.nuxt.dev/handlers/examples-routing)
- [Sharing & practices](https://mcp-toolkit.nuxt.dev/handlers/sharing-practices)
- [Multi-handler organization](https://mcp-toolkit.nuxt.dev/handlers/organization)


## Sitemap

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