mcp-cli
/mcp-cli
Guide for configuring and running Umbraco MCP servers via the CLI. Use when the user wants to set up an MCP server for Claude Code, configure auth, filtering, dry-run, readonly mode, or use introspection commands to understand available tools.
- Author
- umbraco ↗
- Repository
- Umbraco-MCP-Base ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Guide for configuring and running Umbraco MCP servers via the CLI. Use when the user wants to set up an MCP server for Claude Code, configure auth, filtering, dry-run, readonly mode, or use introspection commands to understand available tools.
Original author description
Guide for configuring and running Umbraco MCP servers via the CLI. Use when the user wants to set up an MCP server for Claude Code, configure auth, filtering, dry-run, readonly mode, or use introspection commands to understand available tools.
How it works
- How It Works
- Starting the Server
- Configuring Claude Code
- Runtime Modes
- Tool Filtering
- Introspection Commands
- Local Development Testing
- Input Sanitization
- Auth Setup
SKILL.md preview
---
name: mcp-cli
description: Guide for configuring and running Umbraco MCP servers via the CLI. Use when the user wants to set up an MCP server for Claude Code, configure auth, filtering, dry-run, readonly mode, or use introspection commands to understand available tools.
---
# 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)
```bash
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
```bash
node dist/index.js \
--umbraco-client-id="your-client-id" \
--umbraco-client-secret="your-secret" \
--umbraco-base-url="https://localhost:44391"
```
### Via environment variables
```bash
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:
```json
{
"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:
```json
{
"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
```bash
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
```bash
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.
| Flag | Env Var | Effect |
|------|---------|--------|
| `--umbraco-tool-modes` | `UMBRACO_TOOL_MODES` | Enable named groups of collections |
| `--umbraco-include-slices` | `UMBRACO_INCLUDE_SLICES` | Only expose tools with these slices |
| `--umbraco-exclude-slices` | `UMBRACO_EXCLUDE_SLICES` | Hide tools with these slices |
| `--umbraco-include-tool-collections` | `UMBRACO_INCLUDE_TOOL_COLLECTIONS` | Only expose these collections |
| `--umbraco-exclude-tool-collections` | `UMBRACO_EXCLUDE_TOOL_COLLECTIONS` | Hide these collections |
| `--umbraco-include-tools` | `UMBRACO_INCLUDE_TOOLS` | Only expose these specific tools |
| `--umbraco-exclude-tools` | `UMBRACO_EXCLUDE_TOOLS` | Hide these specific tools |
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:**
```bash
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.
| Flag | Purpose |
|------|---------|
| `--list-tools` | Print ASCII table of all tools (name, collection, slices, annotations) |
| `--describe-tool <name>` | Print full JSON schema and metadata for a specific tool |
| `--generate-context` | Output structured CONTEXT.md documenting all tools (pipe to file) |
```bash
# 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](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":
| Flag | Env Var | Purpose |
|------|---------|---------|
| `--umbraco-client-id` | `UMBRACO_CLIENT_ID` | OAuth client ID from API user |
| `--umbraco-client-secret` | `UMBRACO_CLIENT_SECRET` | OAuth client secret |
| `--umbraco-base-url` | `UMBRACO_BASE_URL` | Umbraco instance URL |
| `--env` | _(n/a)_ | Path to custom .env file |
Files in this package (2)
- SKILL.md 7 KB
- local-dev-testing.md 3 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · umbraco/Umbraco-MCP-Base | 100 | MIT |
| github/awesome-copilot | 100 | MIT |
| umbraco/Umbraco-MCP-Base | 100 | MIT |
| enjoydigital/umbraco.community.schemeweaver | 100 | MIT |
| sandbaseai/sandbase-skills | 90 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 286f680ceff8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100umb-cms-dev-cli
Guide for running and debugging this Umbraco MCP server via the CLI. Use when the user wants to list tools, call tools, configure filtering, dry-run, readonly mode, or debug configuration. - 100umb-cms-mcp-setup
Guide for installing and configuring the Umbraco MCP server (@umbraco-cms/mcp-dev) as a live MCP connection in an AI client. Use when the user wants to set up, connect, install, or troubleshoot the MCP server itself (as opposed to running it standalone via the CLI). - 100mcp-testing
Load MCP eval testing patterns using @umbraco-cms/mcp-server-sdk/evals. Use when writing LLM-based acceptance tests for MCP tools. - 100mcp-patterns
Load MCP development patterns and best practices for building tools with the @umbraco-cms/mcp-server-sdk. Use when starting tool development or needing pattern reference. - 100schemeweaver-setup
Connect Claude Code to an Umbraco site running SchemeWeaver and prove the connection works end to end. Use when the user wants to install or set up the SchemeWeaver plugin or MCP server, wire Claude up to their Umbraco site, create the Umbraco API user or client credentials it… - 100cli-builder
Build or refactor agent-facing CLI tools with non-interactive commands, stable --help and --json contracts, idempotent operations, and --dry-run previews. Use for CLI design, agent-friction refactors, output/exit-code debugging, or automation safety. Do not use for GUI/TUI…