mcp-setup

name: mcp-setup description: Set up the Momentum CMS MCP server plugin and generate Claude Code MCP config for AI tool integration. Use when connecting Claude Code (or any MCP client) to a Momentum CMS instance. argument-hint: [base-url] (default: http://localhost:4200)

MCP Setup for Momentum CMS

Set up the MCP (Model Context Protocol) server plugin so AI tools like Claude Code can read, query, and manage CMS content through standard MCP tools.

Arguments

• $ARGUMENTS - Optional base URL of the running CMS (default: http://localhost:4200)

What This Does

1. Wires the @momentumcms/plugins/mcp plugin into the app's momentum.config.ts
2. Creates an API key for MCP authentication
3. Generates .mcp.json at the project root for Claude Code auto-discovery

Step 1: Wire the Plugin

Add the MCP plugin to the app's momentum.config.ts:

// Add import
import { mcpPlugin } from '@momentumcms/plugins/mcp';

// Create instance (after other plugin instances)
export const mcp = mcpPlugin({
    path: '/mcp',
    apiKeyRequired: true,
    tools: {
        read: true, // find, get, search, count (default: true)
        write: false, // create, update, delete (default: false — opt-in for safety)
        globals: true, // list, get, update globals (default: true)
    },
    // Optional: restrict which collections are exposed
    // allowedCollections: ['articles', 'pages', 'categories'],
    // deniedCollections: ['internal-logs'],
});

// Add to plugins array
const config = defineMomentumConfig({
    // ...existing config
    plugins: [
        // ...existing plugins
        mcp,
    ],
});

Plugin Config Options

Security Notes

• Auth collections (users, sessions, accounts) are always excluded regardless of allow/deny lists
• Password fields are always stripped from schema responses
• Query limit is clamped to 100, depth to 3
• Write tools are off by default — enable explicitly with tools.write: true

Step 2: Restart the Dev Server

nx serve example-angular  # or example-analog

The schema auto-syncs on startup. No migrations needed.

Step 3: Create an API Key

Once the server is running, create an API key via the Admin UI or API:

Via API (recommended for automation)

# Sign in first
COOKIES=$(curl -s -c - http://localhost:4200/api/auth/sign-in/email \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@test.com","password":"Test1234!"}' | grep -o 'better-auth.session_token=[^;]*')

# Create API key
curl -s http://localhost:4200/api/auth/api-keys \
  -H 'Content-Type: application/json' \
  -H "Cookie: $COOKIES" \
  -d '{"name":"Claude Code MCP","role":"admin"}' | jq .key

Via Admin UI

1. Navigate to /admin and sign in
2. Go to Settings > API Keys
3. Create a new key with name "Claude Code MCP" and role "admin"
4. Copy the key (shown only once)

Step 4: Generate .mcp.json

Create .mcp.json at the project root for Claude Code auto-discovery:

{
    "mcpServers": {
        "momentum-cms": {
            "type": "http",
            "url": "http://localhost:4200/api/mcp",
            "headers": {
                "X-API-Key": "mcms_YOUR_API_KEY_HERE"
            }
        }
    }
}

Replace mcms_YOUR_API_KEY_HERE with the actual API key from Step 3.

Add .mcp.json to .gitignore — it contains secrets:

# MCP config (contains API keys)
.mcp.json

Step 5: Verify

Test that Claude Code can discover the MCP tools:

# Quick test — list collections (uses .mcp.json auto-discovery)
claude -p "Use the list_collections tool to list all CMS collections" --output-format text

# Or with an explicit config file (useful for CI)
claude -p "List all CMS collections via the list_collections tool" \
  --mcp-config .mcp.json \
  --strict-mcp-config \
  --output-format text

# Interactive — start Claude Code with MCP
claude
# Then ask: "What collections are available in the CMS?"

Available MCP Tools

Once configured, Claude Code (and any MCP client) gets these tools:

Schema Tools (always enabled)

• list_collections — List all accessible collections with slugs, labels, field counts
• get_collection_schema — Get detailed field schema for a collection

Read Tools (default: enabled)

• find_documents — Query with where, sort, pagination, depth
• get_document — Get single document by ID
• search_documents — Full-text search
• count_documents — Count with optional where filter

Write Tools (default: disabled)

• create_document — Create new document
• update_document — Partial update by ID
• delete_document — Delete by ID

Global Tools (default: enabled)

• list_globals — List all globals with metadata
• get_global — Read a global document
• update_global — Update a global (requires tools.write: true)

Resources (momentum:// URIs)

• momentum://collections — Collection list
• momentum://collections/{slug}/schema — Collection schema
• momentum://globals — Globals list
• momentum://globals/{slug} — Global document data

Prompts

• create_content — Generate content creation prompt with schema context
• translate_content — Generate translation prompt with document data

Troubleshooting