---
title: "Configure the module"
description: "Configure the Nuxt MCP module to fit your needs."
canonical_url: "https://mcp-toolkit.nuxt.dev/getting-started/configuration"
---
# Configure the module

> Configure the Nuxt MCP module to fit your needs.

## Basic Configuration

Add the module to your `nuxt.config.ts`:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'My MCP Server',
  },
})
```

The module works with sensible defaults, so minimal configuration is required.

## Configuration Options

All available configuration options:

<field-group>
<field name="enabled" type="boolean">

Default: `true`

Enable or disable the MCP server.

</field>

<field name="route" type="string">

Default: `'/mcp'`

The HTTP route where the MCP server will be accessible.

</field>

<field name="browserRedirect" type="string">

Default: `'/'`

URL to redirect browsers when they access the MCP endpoint.

</field>

<field name="name" type="string">

Default: `''`

The name of your MCP server (used in the MCP protocol handshake).

</field>

<field name="version" type="string">

Default: `'1.0.0'`

The version of your MCP server (semantic versioning).

</field>

<field name="description" type="string">

Optional. A human-readable description of the server, sent as part of `serverInfo` during initialization. Clients display it in their UI (server lists, tooltips, install prompts).

</field>

<field name="instructions" type="string">

Optional. Operational instructions injected by clients into the model's system prompt. Use this to guide LLMs on workflows, tool relationships, or constraints — not to identify the server (use `description` for that).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  mcp: {
    description: 'Read and update todos for the current user.',
    instructions: 'Always call list-todos before create-todo. Group results by status.',
  },
})
```

See the [MCP lifecycle spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization).

</field>

<field name="icons" type="McpIcon[]">

Optional. Icons for the server, displayed by clients in their UI. Each entry needs `src` and `mimeType`, with optional `sizes` and `theme`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  mcp: {
    icons: [
      { src: 'https://example.com/icon-light.png', mimeType: 'image/png', sizes: ['64x64'], theme: 'light' },
      { src: 'https://example.com/icon-dark.png', mimeType: 'image/png', sizes: ['64x64'], theme: 'dark' },
    ],
  },
})
```

</field>

<field name="dir" type="string">

Default: `'mcp'`

Base directory for MCP definitions (relative to `server/`). The module expects:

- `{dir}/tools/` - Tool definitions
- `{dir}/resources/` - Resource definitions
- `{dir}/prompts/` - Prompt definitions
- `{dir}/handlers/<name>/` - Optional named handler folders ([organization](https://mcp-toolkit.nuxt.dev/handlers/organization))

</field>

<field name="appsDir" type="string">

Default: `'mcp'`

Base directory for [MCP Apps](https://mcp-toolkit.nuxt.dev/apps/overview) `.vue` files (relative to Nuxt's `app/` directory). Scanned across layers. Defaults to `app/mcp/`. The MCP Apps pipeline only runs when this directory exists.

</field>

<field name="defaultHandlerStrategy" type="'orphans' | 'all'">

Default: `'orphans'`

Controls which auto-discovered definitions land on the default `/mcp` route when [named handlers](https://mcp-toolkit.nuxt.dev/handlers/organization) exist:

- `'orphans'` — only definitions not attached to any named handler (no folder attribution). When no folder handler exists, every definition is an orphan, so this naturally falls back to "expose everything" — zero-effort back-compat.
- `'all'` — every discovered definition, including those attributed to named handlers. Useful when you want a "kitchen sink" route in addition to specialized ones.

</field>

<field name="autoImports" type="boolean">

Default: `true`

Auto-import MCP helpers (`defineMcpTool`, `defineMcpResource`, `defineMcpHandler`, `defineMcpApp`, …), types (`McpRequestExtra`, …), composables (`useMcpSession`, `useMcpServer`, `useMcpLogger`, `useMcpElicitation`), and the `InstallButton` component. Set to `false` to disable all auto-imports and require explicit imports from `@nuxtjs/mcp-toolkit/server`.

</field>

<field name="llms" type="boolean">

Default: `true`

Advertise this MCP server in `/llms.txt` when [`nuxt-llms`](https://github.com/nuxt-content/nuxt-llms) is registered. Adds an `## MCP Server` section pointing at your endpoint so agents that discover your site through `llms.txt` can connect without any extra configuration. No-op when `nuxt-llms` isn't installed. See [llms.txt discovery](https://mcp-toolkit.nuxt.dev/advanced/llms-txt).

</field>

<field name="logging" type="boolean">

Optional. Server-side observability for every MCP request via [evlog](https://evlog.dev), an **optional peer dependency**.

- `undefined` (default) — auto-detect: on if the `evlog/nuxt` module is registered, off otherwise.
- `true` — assert `evlog/nuxt` is registered; throw at build otherwise.
- `false` — opt out entirely.

When active, every MCP request emits a wide event tagged with `mcp.transport`, `mcp.method`, `mcp.tool`, `mcp.session_id`, `mcp.request_id`, etc. Use [`useMcpLogger()`](https://mcp-toolkit.nuxt.dev/advanced/logging) to push extra fields and discrete events.

</field>

<field name="sessions" type="boolean | object">

Default: `false`

Enable [MCP session management](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) (stateful transport). When enabled, the server assigns session IDs via the `MCP-Session-Id` header and maintains state across requests, enabling SSE streaming, server-to-client notifications, and session continuity. Sessions need the **Node** Nitro server; on Cloudflare Workers every request is served statelessly and this option has no effect.

Pass `true` for defaults or an object with:

- `enabled` - Enable or disable sessions
- `maxDuration` - Session timeout in milliseconds (default: `1800000` / 30 minutes)
- `maxSessions` - Maximum concurrent sessions before new session creation returns `503` (default: `1000`)

</field>

<field name="security" type="object">

Optional. Hardens [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#security) requests.

- `allowedOrigins` — `undefined` (default): allow requests with no `Origin` header (typical for same-origin and CLI); otherwise require `Origin` to match the server origin (scheme + host + port). Use the literal `'*'` in config to disable Origin checks (explicit opt-out). `string[]` — allow only listed origins (each entry is normalized to an origin URL).

Cross-site browser clients must send an allowed `Origin` or receive **403**.

</field>
</field-group>

## Common Configuration Scenarios

### Custom Route

Change the MCP endpoint route:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    route: '/api/mcp', // Custom route
  },
})
```

### Custom Directory

Use a different directory for MCP definitions:

```typescript [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/`
- `server/my-mcp/resources/`
- `server/my-mcp/prompts/`

### Browser Redirect

Redirect browsers to a custom URL:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    browserRedirect: '/docs/mcp', // Redirect browsers to documentation
  },
})
```

### Streamable HTTP security (`allowedOrigins`)

When browsers call your MCP endpoint from another site, they send an `Origin` header. By default the module requires that origin to match your app. Allow a SPA on another host (or disable checks only in controlled environments):

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    security: {
      allowedOrigins: ['https://my-app.vercel.app'],
      // allowedOrigins: '*' // explicit opt-out — use with care
    },
  },
})
```

### Session Management

Enable stateful sessions to support SSE streaming, server-to-client notifications, and per-session state:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    sessions: true,
  },
})
```

With sessions enabled, the server assigns an `MCP-Session-Id` during initialization. Clients include this ID in subsequent requests, allowing the server to maintain state across the session lifecycle.

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

See the [Sessions guide](https://mcp-toolkit.nuxt.dev/advanced/sessions) for the full `useMcpSession()` API, use cases, and examples.

</callout>

### Disable Auto-Imports

If you prefer explicit imports over auto-imports:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    autoImports: false,
  },
})
```

With auto-imports disabled, import helpers and types explicitly:

```typescript [server/mcp/tools/echo.ts]
import { z } from 'zod'
import { defineMcpTool, type McpRequestExtra } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Echo back a message',
  inputSchema: { message: z.string() },
  handler: async ({ message }, extra: McpRequestExtra) => {
    return `Echo: ${message}`
  },
})
```

### Disable the Module

Temporarily disable the MCP server:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    enabled: false, // Disable the MCP server
  },
})
```

## Runtime Configuration

Access configuration at runtime:

```typescript [server/api/config.ts]
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event).mcp

  return {
    name: config.name,
    version: config.version,
    route: config.route,
  }
})
```

## Next Steps

- [Tools](https://mcp-toolkit.nuxt.dev/tools/overview) - Learn how to create tools
- [Resources](https://mcp-toolkit.nuxt.dev/resources/overview) - Create resources
- [Prompts](https://mcp-toolkit.nuxt.dev/prompts/overview) - Create prompts
- [Sessions](https://mcp-toolkit.nuxt.dev/advanced/sessions) - Per-session state with `useMcpSession()`
- [Custom Paths](https://mcp-toolkit.nuxt.dev/advanced/custom-paths) - Advanced path configuration


## Sitemap

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