--- title: "Building an MCP Server for Nuxt" description: "How we built the Nuxt MCP server to enable AI assistants to access our documentation through structured data and composable tools." canonical_url: https://nuxt.com/blog/building-nuxt-mcp last_updated: 2026-04-15 --- # Building an MCP Server for Nuxt > How we built the Nuxt MCP server to enable AI assistants to access our documentation through structured data and composable tools. AI assistants are becoming an increasingly important part of the developer experience. To help them provide accurate, up-to-date information about Nuxt, we built an MCP server that exposes our documentation, blog posts, and deployment guides in a structured way. Here's how we did it with the [Nuxt MCP Toolkit](https://mcp-toolkit.nuxt.dev), and how you can build your own. Want to test the Nuxt MCP server? Jump to the [Nuxt MCP Server Documentation](/docs/4.x/guide/ai/mcp). ## What is MCP and why did we build it? The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to securely access data and tools. Think of it as an API specifically designed for AI assistants: rather than returning HTML or generic JSON, it provides structured, semantic data that LLMs can easily understand and use. MCP defines three main primitives: - **Resources**: Allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a URI. - **Tools**: Enable AI models to interact with external systems and perform operations (like searching or API calls) - **Prompts**: Reusable prompt templates with arguments that can be invoked by users ### Why MCP over RAG? We've observed that AI assistants using MCP servers provide **significantly better responses** than traditional RAG (Retrieval-Augmented Generation) approaches: - **Structured data in, structured data out**: Tools accept well-defined parameters and return typed data that prevents hallucinations - **Composable tools**: AI assistants can chain tools together, using the output of one tool as input for another (e.g., search for a topic, then fetch the full content) - **Faster and more accurate**: No need to process and chunk large documents at query time - **Always up-to-date**: Direct access to your content layer without reindexing - **Context-aware navigation**: The AI can intelligently navigate relationships between content Both [Nuxt](https://nuxt.com/mcp) and [Nuxt UI](https://ui.nuxt.com/mcp) now have MCP servers with similar architectures, making it easier for AI assistants to help developers with these frameworks. ## Technical architecture Our MCP server is built directly into nuxt.com using the [Nuxt MCP Toolkit](https://mcp-toolkit.nuxt.dev) module. The module provides automatic discovery of tools, resources, and prompts from your server directory: ```text nuxt.com/ ├── server/ │ └── mcp/ │ ├── tools/ │ │ ├── list-documentation-pages.ts │ │ ├── get-documentation-page.ts │ │ └── ... │ ├── resources/ │ │ ├── nuxt-documentation-pages.ts │ │ └── ... │ └── prompts/ │ ├── find-documentation-for-topic.ts │ └── ... └── nuxt.config.ts ``` The architecture is straightforward: you define your tools, resources, and prompts as individual files, and the module automatically registers them and exposes an HTTP endpoint for MCP clients to connect. No manual server setup, no transport configuration, just create files in the right directories and they're ready to use. ## Implementation deep dive ### Module setup Getting started is as simple as adding the module to your Nuxt config: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxtjs/mcp-toolkit'], mcp: { name: 'Nuxt', } }) ``` That's it. The module will automatically scan your `server/mcp/` directory and register everything it finds. ### Tools: Operations for AI models Tools enable language models to interact with external systems by accepting parameters and performing operations. Here's how we implemented our `list_documentation_pages` tool: ```ts [server/mcp/tools/list-documentation-pages.ts] import { z } from 'zod' import { queryCollection } from '@nuxt/content/server' export default defineMcpTool({ description: `Lists all available Nuxt documentation pages with their categories and basic information. WHEN TO USE: Use this tool when you need to EXPLORE or SEARCH for documentation about a topic but don't know the exact page path. WHEN NOT TO USE: If you already know the specific page path, use get_documentation_page directly instead.`, inputSchema: { version: z.enum(['3.x', '4.x', 'all']).optional().default('4.x').describe('Documentation version to fetch') }, cache: '1h', async handler({ version }) { const event = useEvent() const allDocs = await queryCollection(event, 'docsv4') .select('title', 'path', 'description') .all() return jsonResult(allDocs.map(doc => ({ title: doc.title, path: doc.path, description: doc.description, url: `https://nuxt.com${doc.path}` }))) } }) ``` Notice a few key things: - **defineMcpTool** is auto-imported, no need to import it manually - **inputSchema** uses Zod for parameter validation - **cache: '1h'** enables built-in response caching - **jsonResult()** is a helper that formats the response correctly The tool name is automatically derived from the filename (`list-documentation-pages.ts` becomes `list_documentation_pages`). ### Resources: Context for language models Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a URI. The simplest way to expose a file is using the `file` property, which automatically handles URI generation, MIME type detection, and file reading: ```ts [server/mcp/resources/readme.ts] export default defineMcpResource({ name: 'readme', description: 'Project README file', file: 'README.md' // Relative to project root }) ``` For dynamic resources, you can use a custom handler: ```ts [server/mcp/resources/nuxt-documentation-pages.ts] import { queryCollection } from '@nuxt/content/server' export default defineMcpResource({ uri: 'resource://nuxt-com/documentation-pages', description: 'Complete list of available Nuxt documentation pages (defaults to v4.x)', cache: '1h', async handler(uri: URL) { const event = useEvent() const allDocs = await queryCollection(event, 'docsv4') .select('title', 'path', 'description') .all() const result = allDocs.map(doc => ({ title: doc.title, path: doc.path, description: doc.description, version: '4.x', url: `https://nuxt.com${doc.path}` })) return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] } } }) ``` Unlike tools, which are model-controlled, resources are application-driven, the host application determines how to incorporate them based on user needs, such as through UI elements for explicit selection or automatic context inclusion. ### Prompts: Reusable templates Prompts are reusable templates with arguments that users can invoke. They return a conversation format that guides the AI through specific workflows: ```ts [server/mcp/prompts/find-documentation-for-topic.ts] import { z } from 'zod' import { queryCollection } from '@nuxt/content/server' export default defineMcpPrompt({ description: 'Find the best Nuxt documentation for a specific topic or feature', inputSchema: { topic: z.string().describe('Describe what you want to learn about'), version: z.enum(['3.x', '4.x']).optional().describe('Documentation version to search') }, async handler({ topic, version = '4.x' }) { const event = useEvent() const docsVersion = version === '4.x' ? 'docsv4' : 'docsv3' const allDocs = await queryCollection(event, docsVersion) .select('title', 'path', 'description') .all() const allPages = allDocs?.map(doc => ({ title: doc.title, path: doc.path, description: doc.description, url: `https://nuxt.com${doc.path}` })) || [] return { messages: [{ role: 'user' as const, content: { type: 'text' as const, text: `Help me find the best Nuxt documentation for this topic: "${topic}". Here are all available documentation pages: ${JSON.stringify(allPages, null, 2)}` } }] } } }) ``` Prompts differ from tools in that they are user-invoked and return conversation messages, while tools are model-controlled and return structured data. ### Built-in helpers The module provides several auto-imported helpers to simplify common patterns: - **defineMcpTool**, **defineMcpResource**, **defineMcpPrompt**: Define your MCP primitives - **jsonResult(data)**: Format a JSON response for tools - **errorResult(message)**: Return an error response from tools ### Using Nuxt server utilities To use Nuxt server utilities like `useEvent()` in your handlers, enable `asyncContext` in your Nuxt config: ```ts [nuxt.config.ts] export default defineNuxtConfig({ experimental: { asyncContext: true } }) ``` Then you can access the H3 event and use Nuxt server composables like `queryCollection` from [Nuxt Content](https://content.nuxt.com). ## Building your own MCP server Ready to build an MCP server for your own application? With the Nuxt MCP Toolkit, it takes just a few minutes. ### 1. Install the module ```bash [Terminal] npx nuxi module add mcp-toolkit ``` ### 2. Configure the module Add basic configuration to your Nuxt config: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxtjs/mcp-toolkit'], mcp: { name: 'my-app' } }) ``` ### 3. Create your first tool Create a file in `server/mcp/tools/`: ```ts [server/mcp/tools/search.ts] import { z } from 'zod' export default defineMcpTool({ description: 'Search through my content', inputSchema: { query: z.string().describe('Search query') }, async handler({ query }) { // Your search logic here const results = await searchContent(query) return jsonResult(results) } }) ``` That's it! Your MCP server is now accessible at `https://your-domain.com/mcp`. ### 4. Add resources and prompts (optional) You can also add resources and prompts following the same pattern: ```ts [server/mcp/resources/readme.ts] export default defineMcpResource({ name: 'readme', description: 'Project README file', file: 'README.md' }) ``` For more advanced configuration options, check out the [Nuxt MCP Toolkit documentation](https://mcp-toolkit.nuxt.dev). ## Get started with the Nuxt MCP server Ready to experience the power of MCP with Nuxt? Our server is already live and provides access to all Nuxt documentation, blog posts, and deployment guides. ### Quick install for Cursor The easiest way to get started is with Cursor's one-click installation: ### Other AI assistants The Nuxt MCP server works with Claude Desktop, Windsurf, Visual Studio Code, ChatGPT, and many other MCP-compatible AI assistants. For complete setup instructions for all platforms, check out our [MCP documentation](/docs/4.x/guide/ai/mcp). We encourage you to build MCP servers for your own applications. Whether it's documentation, API references, or domain-specific knowledge, MCP makes it easy for AI assistants to provide accurate, helpful information to your users. The complete source code for our MCP server is available on [GitHub](https://github.com/nuxt/nuxt.com) in the [`server/mcp/`](https://github.com/nuxt/nuxt.com/tree/main/server/mcp) directory. Feel free to use it as inspiration for your own implementation!