> ## Documentation Index
> Fetch the complete documentation index at: https://self-5d39fc87.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

<CodeGroup>
  ```bash Local server (Python) theme={null}
  npx mcp-watchtower scan --server "python my_server.py"
  ```

  ```bash Local server (Node.js) theme={null}
  npx mcp-watchtower scan --server "node dist/server.js"
  ```

  ```bash Local server (uvx) theme={null}
  npx mcp-watchtower scan --server "uvx my-published-server"
  ```

  ```bash Remote endpoint theme={null}
  npx mcp-watchtower scan --remote "https://api.example.com/mcp"
  ```

  ```bash Remote endpoint with auth theme={null}
  npx mcp-watchtower scan \
    --remote "https://api.example.com/mcp" \
    --auth-token "$MCP_TOKEN"
  ```

  ```bash Remote with custom name theme={null}
  npx mcp-watchtower scan \
    --remote "https://api.example.com/mcp" \
    --auth-token "$MCP_TOKEN" \
    --name prod-api
  ```

  ```bash Manifest file theme={null}
  npx mcp-watchtower scan --manifest ./tools.json
  ```

  ```bash JSON output theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --json
  ```

  ```bash Platform mode theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --platform
  ```

  ```bash Custom tool threshold theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --max-tools 15
  ```

  ```bash Default full scan theme={null}
  npx mcp-watchtower scan --server "node dist/server.js"
  ```

  ```bash Syntactic-only scan theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --syntactic
  ```

  ```bash Semantic-only scan theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --semantic
  ```

  ```bash Full scan with custom threshold theme={null}
  npx mcp-watchtower scan --manifest ./tools.json --threshold 0.8
  ```

  ```bash Stdin pipe theme={null}
  cat exported-tools.json | npx mcp-watchtower scan --name my-server
  ```
</CodeGroup>

## JSON output

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

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Static analysis" icon="shield-check" href="/guides/static-analysis">
    See how to use the default static checks in local development, CI, manifest workflows, and multi-server platforms.
  </Card>

  <Card title="Semantic workflow" icon="radar" href="/guides/semantic-analysis">
    Learn how the semantic corpus is built and how `--semantic` uses it during scans.
  </Card>
</CardGroup>