How-to: set up your AI assistant

Goal: let Claude Code, Cursor, VS Code or any MCP client answer Mapo questions from the real documentation and the real configuration of your app, instead of guessing.

Time: about two minutes.

What you get

Grounded answers ("MapoList takes endpoint and detail-base") instead of plausible inventions, plus the canonical recipe for whatever you are building.

1. Check the server is there

Nothing to install for the HTTP endpoint: mapomodule registers @mapomodule/mcp in development. Start your app and look at the log:

pnpm dev

[@nuxtjs/mcp-toolkit] ✔ /mcp enabled with 10 tools, 5 resources, 5 prompts, 1 handler

The Mapo endpoint is at http://localhost:3000/mcp/mapo, and the mapo:mcp line of the startup log prints it. Like every server route, it sits under the app's app.baseURL: an app served under /backoffice/ answers at /backoffice/mcp/mapo. Behind a proxy, use the address you open the app with, for example http://localhost/backoffice/mcp/mapo.

If you do not want it at all:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxt/ui", "mapomodule"],
  mapo: { mcp: false },
});

2. Choose a transport

There are two ways to reach the same tools, and they answer different needs:

Transport	Works when	Knows
stdio (mapo-mcp)	always, even with no dev server	Mapo docs, recipes and APIs
HTTP (/mcp/mapo)	while pnpm dev is running	the same, plus your app's own configuration

In practice stdio is enough: the two tools that need the running app (mapo_inspect_app, mapo_doctor) are forwarded to it automatically when it is up. Configure HTTP as well if your client supports it and you want to skip the extra hop.

3. Expose the mapo-mcp binary

The MCP package is installed as a dependency of mapomodule, and package managers only link the binaries of direct dependencies. Add it explicitly:

pnpm add -D @mapomodule/mcp@next   # @next: Mapo v2 is in beta

Now npx mapo-mcp serve runs the local copy — no download, no version drift with the Mapo you actually use.

4. Configure your editor

Claude Code

Create .mcp.json in the project root:

{
  "mcpServers": {
    "mapo": {
      "command": "npx",
      "args": ["mapo-mcp", "serve"]
    }
  }
}

Restart Claude Code and check with /mcp that the mapo server is connected.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "mapo": {
      "command": "npx",
      "args": ["mapo-mcp", "serve"]
    }
  }
}

VS Code (Copilot Chat, agent mode)

.vscode/mcp.json:

{
  "servers": {
    "mapo": {
      "type": "stdio",
      "command": "npx",
      "args": ["mapo-mcp", "serve"]
    }
  }
}

Any client, over HTTP

Point it at http://localhost:3000/mcp/mapo (Streamable HTTP). In Claude Code:

{
  "mcpServers": {
    "mapo": {
      "type": "http",
      "url": "http://localhost:3000/mcp/mapo"
    }
  }
}

For clients that only speak stdio, keep the mapo-mcp entry above.

Apps on another port, behind a proxy or under a base URL

The examples above assume the app answers at http://localhost:3000/. When it does not, take the endpoint from the mapo:mcp line of the startup log, or build it from the address you open the app with plus mcp/mapo. An app served by a proxy on port 80 under /backoffice/ answers at http://localhost/backoffice/mcp/mapo.

• Over HTTP, use that URL as the url.
• Over stdio, pass it to the CLI so the live tools are forwarded there: "args": ["mapo-mcp", "serve", "--app", "http://localhost/backoffice/mcp/mapo"], or set MAPO_MCP_APP_URL.

5. Verify

Ask the assistant something Mapo-specific and watch it call the tools:

"How do I build a list of articles with filters and bulk actions?"

Expect it to call mapo_search_docs or mapo_list_recipes, land on howto/crud-list.md, then check the component contract with mapo_component_api({ name: "MapoList" }) before writing code.

Manual check without an assistant:

curl -s -X POST http://localhost:3000/mcp/mapo \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

6. Get better answers

Ask like a developer, not like a search engine. "How do I paginate a list?" beats "pagination". The ranker demotes prop tables for task-shaped questions and promotes them when you ask about an API surface ("what props does MapoDetail accept").

Start from the overview and the recipes. mapo_list_recipes with no argument opens with what Mapo is and lists what it already does, before you design something Mapo ships out of the box. Clients that attach MCP resources can add mapo://overview, the whole Concepts page.

Use the slash-commands. If your client supports MCP prompts, /mapo-crud-page, /mapo-custom-field, /mapo-debug-form, /mapo-migrate-v1 and /mapo-theme drive the assistant through the right sequence of tools instead of letting it improvise one.

Let it scaffold. mapo_scaffold writes code that matches the framework's patterns, and only when you ask: it shows the files first, and write: true never replaces anything without overwrite: true. Restart the dev server after new pages appear — Nuxt's server-side router needs it before a new route answers.

Point it at your backend. With mapo.mcp.backend.schemaUrl set to your OpenAPI schema, mapo_backend_schema maps a serializer straight to field descriptors — including the endpoint of each relation — and hands the result to mapo_scaffold. Three calls from "the API has an Article model" to a working detail page.

Add a project rule. Some clients ignore the server's instructions. A line in your project's agent instructions goes a long way: AGENTS.md (read by GitHub Copilot, Codex and Cursor), CLAUDE.md for Claude Code (a single @AGENTS.md line imports the same file), or .cursor/rules:

This project uses Mapo. Before writing Mapo code, consult the `mapo_*` MCP tools:
`mapo_list_recipes` / `mapo_search_docs` / `mapo_get_doc` for how-to, and
`mapo_component_api` / `mapo_list_field_types` / `mapo_composable_api` for exact
APIs. Never invent component props or form field types.

Troubleshooting

The tools do not show up Check the client actually started the server (/mcp in Claude Code, the MCP panel in Cursor/VS Code), and that npx mapo-mcp serve runs from the project root. If it does not, step 3 was skipped: the binary only exists once @mapomodule/mcp is a direct dependency.

/mcp/mapo returns 404 The dev server is not running, or the app is a production build, or mapo.mcp is false.

/mcp/mapo redirects, or the live tools say the app is not answering Clients follow the redirect as a GET and report Method not allowed. Use POST for MCP requests. The app has an app.baseURL, or runs behind a proxy: the endpoint is under the base URL, as the startup log prints it. See Apps on another port, behind a proxy or under a base URL.

Answers reference APIs that do not exist Verify the tools were actually called. Models that answer from memory are the problem the project rule above solves.

See also

• @mapomodule/mcp — module reference and configuration
• MCP Toolkit — the underlying Nuxt module