入门指南

配置模块

配置 Nuxt MCP 模块以满足您的需求。

配置选项

所有可用的配置选项：

enabled

boolean

默认值：true启用或禁用 MCP 服务器。

route

string

默认值：'/mcp'MCP 服务器可访问的 HTTP 路由。

browserRedirect

string

默认值：'/'当浏览器访问 MCP 端点时重定向的 URL。

name

string

默认值：''您的 MCP 服务器名称（用于 MCP 协议握手）。

version

string

默认值：'1.0.0'您的 MCP 服务器版本（语义化版本控制）。

description

string

可选。一个人类可读的服务器描述，会在初始化期间作为 serverInfo 的一部分发送。客户端会在其 UI 中显示它（服务器列表、工具提示、安装提示）。

instructions

string

可选。由客户端注入到模型系统提示中的操作说明。请用它来引导 LLM 的工作流程、工具关系或约束——不要用它来标识服务器（请使用 description）。

nuxt.config.ts

export default defineNuxtConfig({
  mcp: {
    description: '读取并更新当前用户的待办事项。',
    instructions: '始终先调用 list-todos 再调用 create-todo。按状态对结果分组。',
  },
})

参见 MCP 生命周期规范。

icons

McpIcon[]

可选。服务器图标，会由客户端在其 UI 中展示。每一项都需要 src 和 mimeType，并可选提供 sizes 和 theme：

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' },
    ],
  },
})

dir

string

默认值：'mcp'MCP 定义的基础目录（相对于 server/）。该模块期望：

{dir}/tools/ - 工具定义
{dir}/resources/ - 资源定义
{dir}/prompts/ - 提示词定义
{dir}/handlers/<name>/ - 可选的命名处理器文件夹（组织方式）

appsDir

string

默认值：'mcp'MCP Apps.vue 文件的基础目录（相对于 Nuxt 的 app/ 目录）。会跨层扫描。默认是 app/mcp/。仅当该目录存在时，MCP Apps 流水线才会运行。

defaultHandlerStrategy

'orphans' | 'all'

默认值：'orphans'当存在命名处理器时，控制哪些自动发现的定义会落到默认的 /mcp 路由上：

'orphans' — 仅包含未附加到任何命名处理器的定义（没有文件夹归属）。当不存在文件夹处理器时，每个定义都是“孤儿”，因此这会自然退回到“公开全部”——零成本向后兼容。
'all' — 所有发现的定义，包括归属于命名处理器的定义。当您希望除了专门路由外，再提供一个“万能”路由时很有用。

autoImports

boolean

默认值：true自动导入 MCP 辅助函数（defineMcpTool、defineMcpResource、defineMcpHandler、defineMcpApp，……）、类型（McpRequestExtra，……）、组合式函数（useMcpSession、useMcpServer、useMcpLogger、useMcpElicitation），以及 InstallButton 组件。设为 false 可禁用所有自动导入，并要求从 @nuxtjs/mcp-toolkit/server 显式导入。

logging

boolean

可选。通过 evlog 对每个 MCP 请求提供服务端可观测性，这是一个可选的 peer dependency。

undefined（默认）— 自动检测：如果注册了 evlog/nuxt 模块则开启，否则关闭。
true — 要求已注册 evlog/nuxt；否则在构建时报错。
false — 完全不启用。

启用后，每个 MCP 请求都会发出一个带有 mcp.transport、mcp.method、mcp.tool、mcp.session_id、mcp.request_id 等标签的宽事件。使用 useMcpLogger() 来推送额外字段和离散事件。

sessions

boolean | object

默认值：false启用 MCP 会话管理（有状态传输）。启用后，服务器通过 MCP-Session-Id 标头分配会话 ID，并在请求之间保持状态，从而支持 SSE 流式传输、服务器到客户端通知以及会话连续性。传入 true 使用默认值，或传入包含以下内容的对象：

enabled - 启用或禁用会话
maxDuration - 会话超时时间，单位为毫秒（默认：1800000 / 30 分钟）
maxSessions - 在创建新会话返回 503 之前允许的最大并发会话数（默认：1000）。仅在 Node Nitro 服务器上强制执行；Cloudflare Workers 使用本模块中的 agents/mcp 路径，该路径不应用此限制。

security

object

可选。为 Streamable HTTP 请求加固安全性。

allowedOrigins — undefined（默认）：允许没有 Origin 标头的请求（通常用于同源和 CLI）；否则要求 Origin 与服务器源（协议 + 主机 + 端口）匹配。在配置中使用字面量 '*' 可禁用 Origin 检查（显式放弃）。string[] — 仅允许列出的来源（每一项都会规范化为来源 URL）。

跨站浏览器客户端必须发送允许的 Origin，否则将收到 403。

常见配置场景

自定义路由

更改 MCP 端点路由：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    route: '/api/mcp', // 自定义路由
  },
})

自定义目录

为 MCP 定义使用不同的目录：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    dir: 'my-mcp', // 在 server/my-mcp/ 中查找，而不是 server/mcp/
  },
})

这将在以下位置查找定义：

server/my-mcp/tools/
server/my-mcp/resources/
server/my-mcp/prompts/

浏览器重定向

将浏览器重定向到自定义 URL：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    browserRedirect: '/docs/mcp', // 将浏览器重定向到文档页面
  },
})

Streamable HTTP 安全性 (`allowedOrigins`)

当浏览器从其他站点调用您的 MCP 端点时，会发送 Origin 标头。默认情况下，该模块要求该来源与您的应用匹配。允许来自另一主机的 SPA（或仅在受控环境中禁用检查）：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    security: {
      allowedOrigins: ['https://my-app.vercel.app'],
      // allowedOrigins: '*' // 显式放弃——谨慎使用
    },
  },
})

会话管理

启用有状态会话以支持 SSE 流式传输、服务器到客户端的通知以及会话级状态：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    sessions: true,
  },
})

启用会话后，服务器将在初始化期间分配一个 MCP-Session-Id。客户端在后续请求中包含此 ID，使服务器能够在整个会话生命周期中保持状态。

请参阅会话指南了解完整的 useMcpSession() API、用例和示例。

禁用自动导入

如果您更喜欢显式导入而非自动导入：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    autoImports: false,
  },
})

禁用自动导入后，请显式导入辅助函数和类型：

server/mcp/tools/echo.ts

import { z } from 'zod'
import { defineMcpTool, type McpRequestExtra } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: '回显一条消息',
  inputSchema: { message: z.string() },
  handler: async ({ message }, extra: McpRequestExtra) => {
    return `Echo: ${message}`
  },
})

禁用模块

临时禁用 MCP 服务器：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    enabled: false, // 禁用 MCP 服务器
  },
})

运行时配置

在运行时访问配置：

server/api/config.ts

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event).mcp

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

后续步骤

Tools - 了解如何创建工具
Resources - 创建资源
Prompts - 创建提示词
Sessions - 使用 useMcpSession() 进行按会话状态管理
Custom Paths - 高级路径配置

Edit this pageorReport an issue

安装

在你的项目中安装并配置 Nuxt MCP 模块。

Inspector

集成到 Nuxt DevTools 中的可视化调试工具。