MCP Server

Let AI agents work inside Primo workspaces safely with the official primo-mcp server.

primo-mcp is the official Model Context Protocol server for Primo. It gives AI coding agents — Claude Code, Claude Desktop, Cursor, VS Code / Copilot, Codex, OpenCode, and more — live access to Primo’s docs, schemas, and validators to help them create and check block and page files.

The MCP server is optional. It’s most useful when an agent is editing files in a Primo workspace export (a directory created by primo new or primo pull). Without it, primo validate and primo build still work.

What It Does

An agent can call the MCP server to:

• Validate a change against Primo’s schema and report errors
• Return validated scaffolds for new blocks and page types; the agent saves the returned files
• Convert field values to the format Primo expects
• Read a relevant section of Primo’s documentation
• Build a preview using the running local dev server

Installation

npm install -g primo-cli

primo-cli depends on primo-mcp, but a dependency installation does not always expose a global primo-mcp executable. The wiring command uses a detected executable or falls back to npx -y primo-mcp. For the direct command used in manual examples, install it explicitly with npm install -g primo-mcp.

Connect your agent

Each MCP client stores server configuration differently. primo mcp install detects the clients on your machine and merges the Primo entry into each one, so you don’t hand-edit JSON per client:

primo mcp install

primo mcp install --client cursor --client vscode   # target specific clients
primo mcp install --all                             # every known client
primo mcp install --dry-run                         # show the paths, write nothing
primo mcp list                                      # what's detected, and where
primo mcp print --client opencode                   # emit a snippet to paste yourself

MCP servers are loaded when a client starts. Restart your client after wiring (and reload the window for editor extensions) so it picks up the new server.

Supported clients

Client	Where the primo entry goes
Claude Code	.mcp.json (project), or claude mcp add --scope user
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json
VS Code / Copilot	.vscode/mcp.json
Codex	~/.codex/config.toml or .codex/config.toml
OpenCode	opencode.json
Gemini CLI	~/.gemini/settings.json
Cline	The Cline MCP settings file
Windsurf	~/.codeium/windsurf/mcp_config.json
Continue	.continue/mcpServers/mcp.json
Zed	~/.config/zed/settings.json
JetBrains AI Assistant	No safe on-disk file — primo mcp install prints what to paste

Run primo mcp list to see the exact resolved path for your machine, and primo mcp print --client <name> for any client’s snippet.

What install changes

install merges only the primo server entry. It never rewrites the rest of your config:

• Existing settings, sibling servers, tables, and comments are preserved.
• Every write is backed up (<file>.bak-<timestamp>) and atomic.
• Re-running is idempotent — an already-wired client is left untouched.
• --dry-run writes nothing. A conflicting primo entry is left as-is unless you pass --force.
• Files that can’t be edited safely (JSONC with comments, TOML defined inline or with dotted keys) are reported rather than guessed — primo mcp print emits the snippet instead.

Wire clients during primo init

primo init detects your MCP clients and offers to wire them, so a new workspace has Primo tools available before the first agent session:

primo init            # prompts with a checklist of detected clients
primo init --yes      # wire detected clients without prompting
primo init --no-mcp   # skip wiring

When run without a terminal (for example in CI), primo init prints a hint instead of prompting or writing.

Configure manually

Claude Code

Register primo-mcp with the Claude Code CLI:

claude mcp add --transport stdio primo -- primo-mcp

By default this adds the server to your current project. Use --scope user to add it globally, or --scope project to commit the config to .mcp.json so your team picks it up.

Manual config (fallback): add to .mcp.json (project) or ~/.claude.json (user):

{
  "mcpServers": {
    "primo": {
      "type": "stdio",
      "command": "primo-mcp"
    }
  }
}

Other clients

For any other client, primo mcp print --client <name> emits the exact snippet and target path. Paste it into that client’s MCP configuration and restart the client. You can also browse the MCP client directory.

Available Tools

Tool	What the agent can use it for
list_docs	Discover available docs sections
get_docs	Read a specific docs section
validate_block	After editing any file in a blocks/<name>/ folder
validate_page	After editing a pages/*.yaml or page-types/*/config.yaml
validate_site	Check site/head.svelte (does not validate the static footer fragment)
get_dev_status	Check whether the running dev server imported edits, and inspect dropped-field warnings
resolve_field_value	Convert a raw value to the format Primo expects
scaffold_block	Creating a new block from scratch
scaffold_page_type	Creating a new page type from scratch
build_preview	Verifying a change rendered visually

The server provides instructions asking agents to validate edits. It does not watch files or guarantee that every client follows those instructions; verify the tool results before accepting an edit.

Example workflow to request

Ask your agent to follow these steps. Connecting MCP makes the tools available; the agent must call them and use their results. Scaffolding tools return file contents for the agent to save.

1. Discover. Agent calls list_docs, then get_docs for the section it needs.
2. Scaffold. Agent calls scaffold_block or scaffold_page_type to produce a known-valid skeleton.
3. Edit. Agent edits files in the workspace.
4. Validate. Agent calls validate_block / validate_page / validate_site after each edit and addresses every error before moving on.
5. Check import and preview. Agent calls get_dev_status after saving, addresses dropped-field warnings, then calls build_preview against the already-running dev server and opens the returned URL. The tools do not start primo dev for you.

Workspace layout and validation rules

The validators assume the standard workspace layout:

sites/my-site/
├── site.yaml
├── site/
│   ├── head.svelte
│   └── foot.html
├── blocks/
│   └── <block-name>/
│       ├── config.yaml
│       ├── component.svelte
│       ├── fields.yaml
│       └── content.yaml
├── page-types/
│   └── <page-type>/
│       ├── config.yaml
│       ├── fields.yaml
│       ├── content.yaml
│       ├── layout.yaml
│       ├── head.svelte
│       └── foot.html
└── pages/
    └── <page-slug>.yaml

Keep these rules in mind:

• Folder names are stable keys. Renaming blocks/hero/ to blocks/banner/ breaks every page that references hero. Changing a display name in the CMS keeps the stable folder key; update references if you rename the folder itself.
• site/head.svelte is injected into <svelte:head>. Do not wrap its contents in <svelte:head> yourself — the validator rejects this.
• Each field type expects a particular value format. Image fields are { url, alt }, links are { url, label }, icons are SVG strings. Call resolve_field_value when in doubt.

Without an Agent

You can also drive the same validators from primo validate:

primo validate                     # every site, from the workspace root
primo validate -d sites/my-site    # one site

This catches the same class of errors as the MCP validators, just at the workspace level instead of file by file.

Next Steps

Local Development

Run the CMS and sync files while you (or an agent) edit

Field Types

Look up field types and the value formats the MCP validates