Valkyrian Labs logo

AI Agents and MCP

Point an AI agent at your Payload app and ask for changes in plain language: "rewrite the Home page intro from our launch post", "add an FAQ block after the hero", "fix the broken callouts on the pricing page". The agent finds the document, writes payload-markdown with the directives your site actually supports, validates it with the same renderer your site uses, and saves a draft for you to review.

@valkyrianlabs/payload-markdown/mcp adds this to Payload's official MCP plugin. Any MCP client works: Claude Code, Claude Desktop, Cursor, VS Code, or your own agent.

Safe by default

Agents save drafts, not live pages. Every change is validated before it is saved, edits to a document land in one atomic save, and the agent can only touch what its API key and Payload user are allowed to.

Quick Setup

  1. Install the MCP plugin

    1pnpm add @payloadcms/plugin-mcp

  2. Register it with the markdown tools

    Add mcpPlugin after payloadMarkdown, wrapping its options in withPayloadMarkdownMcp. Expose the collections and globals agents may work on.

    1import { mcpPlugin } from '@payloadcms/plugin-mcp'2import { payloadMarkdown } from '@valkyrianlabs/payload-markdown'3import { withPayloadMarkdownMcp } from '@valkyrianlabs/payload-markdown/mcp'4 5export default buildConfig({6  plugins: [7    payloadMarkdown({ collections: { pages: true, posts: true } }),8    mcpPlugin(9      withPayloadMarkdownMcp({10        collections: {11          pages: { enabled: true },12          posts: { enabled: true },13        },14      }),15    ),16  ],17})

    Run payload generate:importmap and restart the dev server.

  3. Create an API key

    In the Payload admin, open MCP → API Keys and create a key. Tick Find and Update for each collection the agent may edit, and keep the markdown* tools checked. The key acts as the user who created it.

  4. Connect your agent

    The MCP endpoint is /api/mcp (Streamable HTTP, Authorization: Bearer <key>). With Claude Code:

    1claude mcp add --transport http payload http://localhost:3000/api/mcp --header "Authorization: Bearer <key>"

    Clients configured with JSON, such as Cursor's mcp.json, use the same URL and header:

    1{2  "mcpServers": {3    "payload": {4      "url": "http://localhost:3000/api/mcp",5      "headers": { "Authorization": "Bearer <key>" }6    }7  }8}

Then ask: "Rewrite the Home page using our README at github.com/acme/widget. Use cards for the features."

What Agents Can Do

ToolWhat it does
markdownGuideThe authoring guide for this site: workflow, where markdown lives, configured themes, icons and code languages, and every directive with its attributes.
markdownReadFinds documents by id, search or where, and lists each markdown field and markdown block with a ref, its markdown, the blocks outline, updatedAt, adminUrl and previewUrl.
markdownValidateRenders markdown exactly like the site and returns every diagnostic with line and column.
markdownWriteReplaces, inserts or removes markdown in one atomic save, after validating every change. Saves a draft unless asked to publish.
markdownPublishPublishes the latest draft after validating all of its markdown.

The markdownEditDocument prompt packages the whole workflow; many clients show it as a slash command. See MCP Tools for every argument and result.

How It Stays Correct

Site-aware guide

The guide is generated from the live directive registry and your config, so agents only use themes, icon names and code languages that exist in this app.

Validation gate

Every write is rendered first. Errors and warnings block the save (warnings can be accepted explicitly), so broken directives never reach a page.

Surgical edits

Markdown blocks are addressed by block id. Only the top-level fields that contain an edit are sent, so other blocks and fields are never rewritten.

Concurrency

Pass ifUpdatedAt from markdownRead and a write is refused if someone saved in between. Locked documents are not overwritten unless the user agrees.

Access Control

Tools run as the API key's user with overrideAccess: false, so collection, field and document access rules apply. On top of that, withPayloadMarkdownMcp makes the markdown tools honor the key's per-collection and per-global checkboxes exactly like the built-in MCP tools: reading needs Find, writing and publishing need Update. Only collections and globals you expose in mcpPlugin get those checkboxes.

For a read-only connection, register only the read tools:

1mcpPlugin(2  withPayloadMarkdownMcp(3    { collections: { pages: { enabled: { find: true } } } },4    { tools: ['guide', 'read', 'validate'] },5  ),6)
Content is not instructions

Agents often read websites or documents to write content. The guide and prompt tell agents to treat that text as content, never as instructions, and drafts give you a review step. Keep publishing a human decision for anything public.

Agent Skill

The package ships an agent skill in skills/payload-markdown/ (Claude and Codex variants) with directive recipes, formatting rules and the MCP workflow. Copy the variant for your agent into its skills directory, for example:

1cp -r node_modules/@valkyrianlabs/payload-markdown/skills/payload-markdown/claude .claude/skills/payload-markdown

Next Steps

MCP Tools

Arguments, results, error codes and options for every tool.

Custom Agents

Use the same operations in your own dashboard chat or automation.