CLI Reference

Commands

pmcp dev <file> [flags]

Start protomcp in development mode with hot reload.

# Python
pmcp dev tools.py
pmcp dev tools.py --transport http --port 8080

# TypeScript
pmcp dev tools.ts
pmcp dev tools.ts --transport http --port 8080

Hot reload is enabled: when <file> changes on disk, protomcp reloads the tool process and notifies the MCP host.

pmcp run <file> [flags]

Start protomcp in production mode without hot reload.

# Python
pmcp run tools.py
pmcp run tools.py --transport http --host 0.0.0.0 --port 8080

# TypeScript
pmcp run tools.ts
pmcp run tools.ts --transport http --host 0.0.0.0 --port 8080

pmcp validate <file> [flags]

Validate tool definitions without starting the server. Spawns the tool process, collects tool definitions, validates them, and exits.

# Basic validation
pmcp validate tools.py

# Strict mode (enforces description length, generic name detection)
pmcp validate tools.py --strict

# JSON output
pmcp validate tools.py --format json

Flag	Default	Description
--strict	false	Enable strict validation (min 10 char descriptions, generic name detection)
--format	text	Output format: text or json

Validation checks:

• Tool name format: must match ^[a-zA-Z_][a-zA-Z0-9_]*$
• No duplicate tool names
• All tools have descriptions
• Input schema is valid JSON Schema
• Strict mode: description at least 10 characters, no generic names like “tool1”

pmcp test <subcommand> [flags]

Test tool definitions and tool calls.

pmcp test list <file>

List all tools defined in the file.

pmcp test list tools.py
pmcp test list tools.py --format json

pmcp test call <file> <tool_name> [flags]

Call a specific tool with arguments.

pmcp test call tools.py add --args '{"a": 1, "b": 2}'
pmcp test call tools.py greet --args '{"name": "World"}' --format json

Flag	Default	Description
--args	'{}'	JSON string of arguments to pass to the tool
--trace	true	Show trace output (--trace=false to disable)
--format	text	Output format: text or json

pmcp test scenario <file>

Run a test scenario file against the tools.

pmcp test scenario tests/scenario.yaml

pmcp playground <file> [flags]

Launch an interactive playground for testing tools in the browser.

pmcp playground tools.py
pmcp playground tools.py --port 3000
pmcp playground tools.ts --host 0.0.0.0 --port 3000

Flag	Default	Description
--port	8080	Port to bind the playground server to
--host	localhost	Host/address to bind the playground server to

---

Flags

--auth <scheme:ENV_VAR>

Repeatable. Configure authentication for the HTTP transport (--transport http). Skipped for stdio.

Scheme	Header	Format
token	Authorization	Bearer <value>
apikey	X-API-Key	<value>

# Require Bearer token
pmcp run tools.py --transport http --auth token:MY_TOKEN

# Require API key
pmcp run tools.py --transport http --auth apikey:SERVICE_KEY

# Multiple (all must pass)
pmcp run tools.py --transport http --auth token:MY_TOKEN --auth apikey:SERVICE_KEY

The environment variable must be set at startup. See Authentication for details.

--transport <value>

Default: stdio

The transport to use for the MCP host connection.

Value	Description
stdio	Read/write on stdin/stdout. Used when the MCP client spawns protomcp as a subprocess.
http	Streamable HTTP transport. MCP client connects over HTTP.

# Python
pmcp dev tools.py --transport http

# TypeScript
pmcp dev tools.ts --transport http

--host <value>

Default: localhost

Host/address to bind the HTTP server to. Used with --transport http.

# Python
pmcp run tools.py --transport http --host 0.0.0.0

# TypeScript
pmcp run tools.ts --transport http --host 0.0.0.0

--port <value>

Default: 8080

Port to bind the HTTP server to. Used with --transport http.

# Python
pmcp run tools.py --transport http --port 9000

# TypeScript
pmcp run tools.ts --transport http --port 9000

--hot-reload <value>

Default: (graceful reload)

Controls the hot reload strategy. Only applies in dev mode.

Value	Description
immediate	Kill and restart the tool process on every file change.
(omitted)	Send a ReloadRequest to the running process (graceful).

# Python
pmcp dev tools.py --hot-reload immediate

# TypeScript
pmcp dev tools.ts --hot-reload immediate

--call-timeout <duration>

Default: 5m

Maximum time to wait for a tool call to complete. Uses Go duration syntax.

# Python
pmcp run tools.py --call-timeout 30s
pmcp run tools.py --call-timeout 10m

# TypeScript
pmcp run tools.ts --call-timeout 30s
pmcp run tools.ts --call-timeout 10m

--log-level <value>

Default: info

Logging verbosity.

Value	Description
debug	All log messages including internal state
info	Normal operational messages
warn	Warnings and errors only
error	Errors only

# Python
pmcp dev tools.py --log-level debug

# TypeScript
pmcp dev tools.ts --log-level debug

--socket <path>

Default: $XDG_RUNTIME_DIR/pmcp/<pid>.sock or $TMPDIR/protomcp/<pid>.sock

Path for the unix socket used to communicate with the tool process.

# Python
pmcp dev tools.py --socket /tmp/mytools.sock

# TypeScript
pmcp dev tools.ts --socket /tmp/mytools.sock

--runtime <command>

Override the runtime used to execute the tool file. By default, protomcp detects the runtime from the file extension.

# Override Python version
pmcp dev tools.py --runtime python3.12

# Override TypeScript runtime
pmcp dev tools.ts --runtime bun

--trace

Default: true

Enable or disable trace output. Trace output shows detailed timing and protocol information.

# Disable trace output
pmcp dev tools.py --trace=false

--args <json>

Only for test call. JSON string of arguments to pass to the tool being called.

pmcp test call tools.py add --args '{"a": 1, "b": 2}'

---

Runtime detection

When --runtime is not set, protomcp picks the runtime based on file extension:

Extension	Default command	Override env var
.py	python3	PROTOMCP_PYTHON
.ts	npx tsx	PROTOMCP_NODE
.js	node	PROTOMCP_NODE
.go	go run	—
.rs	cargo run	—
other	run directly	—

# Use a specific Python version
PROTOMCP_PYTHON=python3.12 pmcp dev tools.py

# Use bun instead of node for TypeScript
PROTOMCP_NODE=bun pmcp dev tools.ts

uv detection

When running .py files, if uv is on PATH and a pyproject.toml exists near the file, protomcp uses uv run python <file> instead of python3.