mcp-cli
/mcp-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.
- Author
- umbraco ↗
- Repository
- Umbraco-MCP-Base ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
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 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.
Original author description
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.
How it works
- Quick Reference
- Authentication
- Starting the Server
- Tool Filtering
- Runtime Modes
- Introspection Commands
- Input Sanitization
SKILL.md preview
---
name: mcp-cli
description: 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.
---
# Umbraco MCP Server — CLI Guide
This MCP server runs as a CLI tool over stdio. The CLI handles authentication and configuration, then exposes tools that talk directly to the Umbraco Management API.
## Quick Reference
```bash
# List all tools
node dist/index.js --list-tools
# Describe a specific tool's schema
node dist/index.js --describe-tool <tool-name>
# Call a tool directly (requires auth via .env)
node dist/index.js --call <tool-name> --call-args '{"key":"value"}'
# Call a tool with a large/complex payload from a file (avoids shell/argv size limits)
node dist/index.js --call <tool-name> --call-args-file ./payload.json
# Generate context documentation
node dist/index.js --generate-context > CONTEXT.md
# Debug resolved configuration
node dist/index.js --debug-config
```
## Authentication
**Never pass secrets as CLI arguments.** Use a `.env` file or the MCP config `env` block.
| Env Var | Required | Description |
|---------|----------|-------------|
| `UMBRACO_CLIENT_ID` | Yes | OAuth client ID from Umbraco API user |
| `UMBRACO_CLIENT_SECRET` | Yes | OAuth client secret |
| `UMBRACO_BASE_URL` | Yes | Umbraco instance URL |
Create a `.env` file:
```
UMBRACO_CLIENT_ID=your-client-id
UMBRACO_CLIENT_SECRET=your-secret
UMBRACO_BASE_URL=https://localhost:44391
```
Introspection commands (`--list-tools`, `--describe-tool`, `--generate-context`) do not require auth.
## Starting the Server
```bash
# With .env file (recommended)
node dist/index.js
# Custom .env path
node dist/index.js --env /path/to/.env
```
### Claude Code Configuration
Use the `env` block for credentials:
```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"
}
}
}
}
```
## Tool Filtering
| Flag | Env Var | Description |
|------|---------|-------------|
| `--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`.
Exclude takes precedence over include. Filters combine.
## Runtime Modes
### Readonly mode
```bash
node dist/index.js --umbraco-readonly
```
Mutation tools are completely removed — the LLM won't see them at all.
### Dry-run mode
```bash
node dist/index.js --umbraco-dry-run
```
Read tools execute normally. Mutation tools return a preview without calling the API.
## Introspection Commands
These print output and exit immediately — they do not start the MCP server.
| Flag | Description |
|------|-------------|
| `--list-tools` | Print ASCII table of all tools |
| `--describe-tool <name>` | Print full JSON schema for a tool |
| `--generate-context` | Output CONTEXT.md documenting all tools |
| `--debug-config` | Print resolved config (secrets masked) |
| `--call <name>` | Call a tool directly, print JSON result |
| `--call-args <json>` | JSON arguments for `--call` (default: `{}`) |
| `--call-args-file <path>` | Path to a file with JSON arguments for `--call` — use instead of `--call-args` for large/complex payloads (no shell size limits, safe for multiline JSON and non-ASCII). Cannot be combined with `--call-args`. |
Introspection respects all filtering. `--list-tools` with `UMBRACO_READONLY=true` shows exactly what the LLM would see.
## Input Sanitization
The SDK 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 clear error messages for agent self-correction
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 6d7c6fef7eee (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. - 100run-e2e-tests
Run the end-to-end integration test suite for the CodeScene MCP Server. Use when you need to verify that all MCP tools work correctly against the real CLI and server infrastructure. - 100ac-tools-dry-run
Runs a delegated command or prompt in dry-run mode by setting session status, preserving read-only behavior, and resetting state after execution. Triggers on keywords: dry run, simulate, preview changes, safe mode