A Nuxt MCP server doesn't have to be a separate service. QuasarUI's MCP Server, the endpoint that lets Cursor, Claude Code and other AI clients search and paste Quasar Components, is a route inside the same Nuxt app that serves the website. It shares the database, the user accounts and the deploy. This post walks through how it's built: the module underneath, how a tool is defined, how Access Keys are checked, how Paid Components stay paid, and what we'd do differently.
If you want to use the server rather than read about its insides, the guide to Quasar Components in AI editors covers setup and prompts.
MCP (Model Context Protocol) is a standard way for an AI client to call tools on a server. Ours has five tools, all read-only:
| Tool | Returns |
|---|---|
list_blocks | Every Block with its Component counts and page URL |
list_components | The Components of one Block, each marked free or paid |
search_components | Up to 20 matches for a plain-language query |
get_component | A Component's Vue source |
get_setup_guide | How to set up Quasar and paste a Component |
Free Components work without an account. Paid Components need an Access Key from an account that holds All Access or Blocks Pro.
We didn't write the protocol layer. The @nuxtjs/mcp-toolkit module (version 0.24 at the time of writing) wraps the official MCP TypeScript SDK and plugs it into Nitro, Nuxt's server engine. Setup is a module entry and some metadata:
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxtjs/mcp-toolkit'],
mcp: {
name: 'QuasarUI',
description: 'Copy-paste Quasar (Vue 3) UI Components: list Blocks, search Components and fetch their source.',
instructions: 'Find Components with search_components, or list_blocks then list_components. ...',
},
})The module serves the endpoint at /mcp and loads definitions from server/mcp/. Each file in server/mcp/tools/ is one tool, and server/mcp/index.ts configures the handler itself:
server/
mcp/
index.ts # handler config + auth middleware
tools/
get-component.ts
get-setup-guide.ts
list-blocks.ts
list-components.ts
search-components.ts
utils/
mcp-catalogue.ts # the logic the tools call
mcp-request.ts # Access Key checkHere is get_component in full:
// server/mcp/tools/get-component.ts
import { z } from 'zod'
export default defineMcpTool({
name: 'get_component',
description: 'Get a Component\'s full Vue SFC source by slug. Free Components return their source to anyone; a Paid Component without access returns an upgrade message with the pricing URL instead.',
inputSchema: {
slug: z.string().describe('Component slug from list_components or search_components, e.g. buttons-01'),
},
annotations: { readOnlyHint: true },
handler: ({ slug }) => mcpComponent(useEvent(), slug, mcpRequestAccess()),
})A few things we learned writing these:
.describe() on each input names where the value comes from (from list_components or search_components), which steers the model to call tools in the right order.mcpComponent throws createError({ statusCode: 404, message: 'No Component "x". search_components or list_components gives Component slugs.' }), the client gets a tool result flagged as an error with that text, not a failed HTTP request. The model reads the hint and tries again with a real slug.server/utils/, where the website's API routes can share it and tests can reach it.The handler calls useEvent() to get the current request without passing it around. That's Nitro's async context, and it needs a flag in nuxt.config.ts:
nitro: {
experimental: { asyncContext: true },
}MCP over HTTP can keep a session per client, or treat every request on its own. The toolkit defaults to stateless: each POST gets a fresh server and transport, the response is plain JSON, and a GET returns 405. We kept that default. There is nothing to remember between calls (every tool is a read), so any server instance can answer any request, which is what you want on a serverless host.
server/mcp/index.ts is three lines:
export default defineMcpHandler({
middleware: authenticateMcpRequest,
})The middleware runs before the MCP handler on every request, and throwing from it answers with that HTTP status:
// server/utils/mcp-request.ts (shortened)
async function mcpCallerAccess(event: H3Event): Promise<Access> {
const authorization = getRequestHeader(event, 'authorization')
if (authorization === undefined) return NO_ACCESS
const owner = await findAccessKeyOwner(bearerToken(authorization))
if (!owner) throw invalidAccessKey(event) // 401 + WWW-Authenticate
await enforceMcpKeyRateLimit(event, owner.accessKey.id)
return accessForUser(owner.user)
}
export async function authenticateMcpRequest(event: H3Event) {
await enforceMcpRateLimit(event)
event.context.mcpAccess = await mcpCallerAccess(event)
}The rule that matters: no header means anonymous, a bad header means 401. It's tempting to fall back to Free Components when a key fails. We don't, because a mistyped or revoked key would then look like "the server works but my Paid Components are gone", which is much harder to debug than an error.
The keys themselves:
quasarui_ plus 32 random bytes in base64url. The database stores only its SHA-256 hash and a short display prefix, so the full key is shown once, at creation.Every HTTP request to /mcp counts, including the handshake a client sends when it connects: 60 a minute per IP address, and 60 a minute per Access Key. The address limit runs first, before the key is even looked up, so someone guessing keys spends their address's budget.
The counters live in the same SQLite database as everything else, in a single upsert statement so concurrent requests can't race a read-then-write. If the counter update fails, the request goes through: a throttling outage shouldn't take the MCP Server down with it.
Access is decided by one function shared with the website:
export function canReadComponentSource(component: Pick<ComponentInfo, 'block' | 'slug'>, access: Access) {
return isComponentFree(component) || canSeePaidComponents(access)
}access is computed from Purchases in our own database on every request, not from a cache or from the payment provider, so a refunded Purchase stops returning Paid Components on the next call.
The less obvious part is search. search_components scores matches against the Component source too, including Paid source: asking for "pricing toggle" should find the pricing Component that has a toggle in its code. That's safe because a search result only ever holds the slug, title, Block, access and URL. Matching inside Paid source reveals that a word occurs, never the code. get_component is the only tool that returns source, and for a Paid Component without access it returns the preview link and how to unlock it instead.
The Components are .vue files in the repo. Nitro's serverAssets bundles them into the server build, and the server reads them through storage:
nitro: {
serverAssets: [
{
baseName: 'catalogue',
dir: fileURLToPath(new URL('./catalogue/blocks', import.meta.url)),
pattern: '**/*.vue',
},
],
}const catalogueAssets = () => useStorage('assets:catalogue')The catalogue is fixed per build, so a server instance reads it once and keeps the promise. If that read fails, the promise is dropped so the next request tries again; in development every call reads fresh, so edited files show up.
Our HTTP tests connect with the MCP SDK's own client and StreamableHTTPClientTransport, the same way an editor does, and assert on what a model would see: the five tool names, the Block count, the Free source, the upgrade message for a Paid slug, the 401 for a bad key. Each test sends a fresh x-forwarded-for address so the rate limit doesn't leak between tests.
useEvent() keeps tool files short, but it depends on an experimental Nitro flag and on AsyncLocalStorage support in the runtime. Passing the event explicitly would be more portable.Do I need a separate server for MCP in Nuxt? No. A module such as @nuxtjs/mcp-toolkit serves it from a Nitro route in your existing app.
Does a Nuxt MCP server work with nuxt generate? No. MCP needs a running server; a static build has none.
How do I add auth to a Nuxt MCP server? Use the handler's middleware: read the Authorization header, throw a 401 for a bad key, and put the caller's access on event.context for the tools to read.
To try the result, the MCP Server documentation has the setup for Claude Code, Claude Desktop and Cursor, with and without an Access Key, plus the tool list and limits described here.