MCP CLI

Umbraco MCP Server — CLI Guide

Umbraco MCP servers built with @umbraco-cms/mcp-server-sdk run as CLI tools. You start the server with auth credentials and configuration flags, and it runs as an MCP server over stdio. Claude Code (or any MCP client) then connects and the LLM can call tools in an authenticated state.

How It Works

1. You run the CLI with auth credentials and optional configuration flags
2. The server authenticates against your Umbraco instance using OAuth client credentials
3. It starts an MCP server listening on stdin/stdout
4. Claude Code connects via MCP protocol and the LLM can call tools

The LLM never handles authentication — the CLI does that. The LLM just sees the tools and calls them.

Starting the Server

Via npx (published package)

npx @umbraco-cms/mcp-dev \
  --umbraco-client-id="your-client-id" \
  --umbraco-client-secret="your-secret" \
  --umbraco-base-url="https://localhost:44391"

Via built project

node dist/index.js \
  --umbraco-client-id="your-client-id" \
  --umbraco-client-secret="your-secret" \
  --umbraco-base-url="https://localhost:44391"

Via environment variables

UMBRACO_CLIENT_ID="your-client-id" \
UMBRACO_CLIENT_SECRET="your-secret" \
UMBRACO_BASE_URL="https://localhost:44391" \
node dist/index.js

Or use a .env file (loaded automatically) or specify a custom path with --env /path/to/.env.

CLI arguments take precedence over environment variables, which take precedence over .env file values.

Configuring Claude Code

Add the server to Claude Code's MCP configuration:

{
  "mcpServers": {
    "umbraco": {
      "command": "npx",
      "args": [
        "@umbraco-cms/mcp-dev",
        "--umbraco-client-id=your-client-id",
        "--umbraco-client-secret=your-secret",
        "--umbraco-base-url=https://localhost:44391"
      ]
    }
  }
}

For a locally built server:

{
  "mcpServers": {
    "umbraco": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "UMBRACO_CLIENT_ID": "your-client-id",
        "UMBRACO_CLIENT_SECRET": "your-secret",
        "UMBRACO_BASE_URL": "https://localhost:44391"
      }
    }
  }
}

Runtime Modes

Dry-run mode

node dist/index.js --umbraco-dry-run
# or: UMBRACO_DRY_RUN=true

• Read-only tools (queries) execute normally and return real data
• Mutation tools (create, update, delete) return a preview of what would happen without calling the Umbraco API
• Input validation still runs, so the LLM gets validation feedback
• Use this for safe exploration — the LLM can try mutation tools without risk

Readonly mode

node dist/index.js --umbraco-readonly
# or: UMBRACO_READONLY=true

• Mutation tools are completely removed from the server — the LLM won't see them at all
• Only tools annotated with readOnlyHint: true are registered
• Use this when you want zero risk of data modification (e.g. auditing, reporting)

Tool Filtering

Control which tools are exposed to the LLM. All accept comma-separated values.

Available slices: read, list, create, update, delete, search, tree, publish, move, copy.

Filters combine: slice filters apply within collection filters. Exclude takes precedence over include.

Example — read-only content browsing:

UMBRACO_INCLUDE_SLICES=read,list,search \
UMBRACO_INCLUDE_TOOL_COLLECTIONS=content,media \
node dist/index.js

Introspection Commands

These flags print output and exit immediately — they do not start the MCP server.

Introspection respects all filtering configuration. If you set UMBRACO_READONLY=true, UMBRACO_INCLUDE_SLICES, UMBRACO_INCLUDE_TOOL_COLLECTIONS, or any other filtering env var / CLI flag, the introspection output only shows tools that pass those filters. This means --list-tools shows exactly what the LLM would see at runtime.

If auth credentials and a running Umbraco instance are available, introspection authenticates and fetches the current user so that tool listing also respects authorization policies. Without auth, collections that require a user are skipped and only unrestricted tools are listed.

# See all tools
node dist/index.js --list-tools

# Get schema for a specific tool
node dist/index.js --describe-tool get-content-by-id

# Generate documentation
node dist/index.js --generate-context > CONTEXT.md

# See only what the LLM sees with filtering active
UMBRACO_READONLY=true node dist/index.js --list-tools
UMBRACO_INCLUDE_SLICES=read,list node dist/index.js --list-tools

Local Development Testing

See local-dev-testing.md for SDK contributor guidance on testing CLI commands locally, linking SDK builds, and integrating handleCliCommands.

Input Sanitization

The SDK automatically validates all string inputs before tool handlers run:

• Rejects control characters, path traversal (../), embedded query params, percent-encoded strings
• Validates UUID format where expected
• Returns ProblemDetails (RFC 7807) with clear error messages

The LLM receives these validation errors and can self-correct and retry. No configuration needed.

Auth Setup

The CLI requires OAuth client credentials to authenticate against Umbraco. These are created in the Umbraco backoffice under Settings > Users as an "API user":