CLI reference

Compact reference for the mcp-watchtower CLI: input modes, all scan flags, JSON output, and exit code behavior.

scan is the only command most developers need. Use it with a local server, a remote MCP endpoint, a manifest file, or stdin.

By default, scan runs both the deterministic static checks and the deeper semantic analysis pass. Use --syntactic for only the deterministic checks or --semantic for only the semantic layer.

Synopsis

npx mcp-watchtower scan [options]

Input modes

Mode	Flag	Use it when
Local server	--server "<command>"	You want Watchtower to start your MCP server over stdio
Remote endpoint	--remote "<url>"	Your MCP server is already exposed over HTTP
Manifest file	--manifest ./tools.json	You already export tool definitions during build or CI
Stdin	no input flag	You want to pipe a tools JSON document directly into the scan

You must provide exactly one explicit input source. --server, --remote, and --manifest are mutually exclusive.

Manifest and stdin accept:

1. a raw tool array
2. { "tools": [...] }
3. { "result": { "tools": [...] } }

Flags

Flag	Short	Meaning
--server <command>	-s	Start a local MCP server process over stdio
--remote <url>	-r	Connect to a remote MCP endpoint
--auth-token <token>	-t	Optional bearer token for protected --remote endpoints
--manifest <path>	-m	Read tools from a local JSON file
--name <name>	-n	Override the server label shown in the report
--json	-j	Emit machine-readable JSON instead of human-readable output
--platform	-p	Elevate duplicate tool names to critical in shared tool namespaces
--max-tools <number>	—	Set a custom tool count threshold
--syntactic	—	Run only deterministic syntactic/static checks
--semantic	—	Run only semantic overlap detection and deep semantic parameter analysis
--threshold <number>	—	Set the semantic similarity threshold (0-1, default: 0.75) when semantic analysis runs

Examples

Local server (Python)

npx mcp-watchtower scan --server "python my_server.py"

npx mcp-watchtower scan --server "node dist/server.js"

npx mcp-watchtower scan --server "uvx my-published-server"

npx mcp-watchtower scan --remote "https://api.example.com/mcp"

npx mcp-watchtower scan \
  --remote "https://api.example.com/mcp" \
  --auth-token "$MCP_TOKEN"

npx mcp-watchtower scan \
  --remote "https://api.example.com/mcp" \
  --auth-token "$MCP_TOKEN" \
  --name prod-api

npx mcp-watchtower scan --manifest ./tools.json

npx mcp-watchtower scan --server "node dist/server.js" --json

npx mcp-watchtower scan --server "node dist/server.js" --platform

npx mcp-watchtower scan --server "node dist/server.js" --max-tools 15

npx mcp-watchtower scan --server "node dist/server.js"

npx mcp-watchtower scan --server "node dist/server.js" --syntactic

npx mcp-watchtower scan --server "node dist/server.js" --semantic

npx mcp-watchtower scan --manifest ./tools.json --threshold 0.8

cat exported-tools.json | npx mcp-watchtower scan --name my-server

JSON output

With --json, Watchtower writes a single JSON object to stdout.

{
  "server": "my-server",
  "toolCount": 12,
  "findings": [],
  "semanticFindings": [],
  "passedAt": "2024-11-15T09:32:00.123Z"
}

• findings contains static-analysis results
• semanticFindings is populated in the default full scan and in --semantic mode, including both corpus-overlap findings and semantic parameter-conflict findings

Exit codes

Code	Meaning
0	No critical static findings
1	A critical static finding was found, or the command itself failed

Semantic findings do not change the exit code.

Related pages

Static analysis

See how to use the default static checks in local development, CI, manifest workflows, and multi-server platforms.

Semantic workflow

Learn how the semantic corpus is built and how --semantic uses it during scans.