CLI Reference

Complete command reference for the mcpctl CLI.

Global Flags

These flags are accepted by every mcpctl command and must appear before the subcommand name.

Flag	Description	Default
`--config <path>`	Path to the mcpctl config file.	`~/.config/mcpctl/config.yaml`
`--server <url>`	Override the trust service URL for this invocation.	Value from config file
`-v`, `--verbose`	Enable verbose output, including HTTP request details and scanner debug information.	Off
`--no-color`	Disable color and ANSI escape codes in output. Useful for CI environments and log files.	Off

Commands

Command	Description
`mcpctl scan [path\|artifact]`	Scan locally configured MCP servers, a specific project directory, or a named artifact (npm package, git URL, or container image). Accepts `--format sarif`, `--json`, `--deep`, and `--no-import` flags.
`mcpctl login`	Authenticate with the Truvant trust service via your configured identity provider. Stores a token in the system keychain.
`mcpctl logout`	Remove the stored authentication token and sign out of the trust service.
`mcpctl install`	Install the mcpctl agent on this machine and register it with the trust service. Configures the shim and starts the agent service.
`mcpctl start`	Start the mcpctl agent service if it is not already running.
`mcpctl stop`	Stop the mcpctl agent service. Policy enforcement is suspended while the agent is stopped.
`mcpctl restart`	Restart the mcpctl agent service. Useful after configuration changes.
`mcpctl uninstall`	Remove the mcpctl agent, shim, and all associated configuration from this machine. Prompts for confirmation before proceeding.
`mcpctl upgrade`	Download and install the latest version of mcpctl from the distribution registry, then restart the agent service.
`mcpctl status`	Display the current agent status, active policy role, trust service connectivity, and a summary of recent scan results.
`mcpctl diag`	Collect a diagnostic bundle (logs, config, scan history, connectivity checks) and upload it to a secure S3 location for support review. Prints a retrieval URL on completion.
`mcpctl version`	Print the mcpctl version, build commit, and Go runtime version.

Configuration

Config file

mcpctl reads its configuration from ~/.config/mcpctl/config.yaml by default. The file is created with defaults on first run. Override the path with --config or the MCPCTL_CONFIG environment variable.

# ~/.config/mcpctl/config.yaml

cli:
  registry_url: https://registry.truvant.ai
  cache_dir: ~/.cache/mcpctl

policy:
  default_min_score: 70

scanner:
  timeout: 5m
  enabled_scanners:
    - mcp
    - sast
    - secrets
    - sca

Environment variables

All configuration values can be overridden with environment variables. The variable name is derived from the config key by uppercasing it and prefixing with MCPCTL_, replacing . with _.

Variable	Description	Default
`MCPCTL_CLI_REGISTRY_URL`	Override the CLI distribution registry URL.	`https://registry.truvant.ai`
`MCPCTL_POLICY_DEFAULT_MIN_SCORE`	Minimum trust score (0–100) required for an artifact to be allowed. Artifacts scoring below this threshold are blocked in Enforce mode.	`70`
`MCPCTL_SCANNER_TIMEOUT`	Maximum wall-clock time for a single scan run. Accepts Go duration strings (`5m`, `10m`, `1h`).	`5m`

Key file locations

Path	Description
`~/.config/mcpctl/config.yaml`	Primary configuration file. Managed by mcpctl; hand-editing is supported.
`~/.config/mcpctl/signals/`	Directory where the agent writes MDE-compatible signal files for SIEM integration. Configurable via `MCPCTL_SIGNALS_DIR`.
`~/.cache/mcpctl/`	Local scan cache, artifact database, and trust score cache. Safe to delete; will be repopulated on next run.

API Reference

The Truvant Trust Intelligence Service exposes a REST API at https://trust.truvant.ai/api/v1/. All authenticated endpoints require a Bearer token in the Authorization header, obtained via mcpctl login.

Endpoints

Method	Path	Description
`GET`	`/health`	Liveness check. Returns `200 OK` if the service is running. No authentication required.
`GET`	`/ready`	Readiness check. Returns `200 OK` when the service is ready to handle requests, including database connectivity. No authentication required.
`GET`	`/api/v1/trust/{endpoint}`	Fetch the trust score and signal breakdown for a remote MCP endpoint. `{endpoint}` is the URL-encoded hostname or full endpoint URL.
`GET`	`/api/v1/trust/{endpoint}/status`	Return the current analysis status for an endpoint (`pending`, `complete`, `failed`).
`POST`	`/api/v1/trust/batch`	Submit a list of endpoints for bulk trust score retrieval. Returns scores for all endpoints in a single response.
`GET`	`/api/v1/trust/{endpoint}/tools`	Retrieve the tool schema manifest for a remote endpoint, including per-tool risk ratings (L1–L4).
`GET`	`/api/v1/events`	List trust events (cert changes, auth changes, posture regressions, blocked commands) for your organization. Supports `?host=`, `?type=`, and `?since=` query parameters.

Example: Get trust score

# Retrieve the trust score for mcp.slack.com
curl -s \
  -H "Authorization: Bearer $(mcpctl token)" \
  "https://trust.truvant.ai/api/v1/trust/mcp.slack.com" \
  | jq .

Response

A successful response returns a JSON object with the trust score, signal breakdown, and tool risk summary. Scores range from 0 (untrusted) to 100 (fully trusted).

{
  "endpoint": "mcp.slack.com",
  "trust_score": 92,
  "publisher": {
    "verified": true,
    "organization": "Slack Technologies, LLC",
    "domain_age_days": 4021
  },
  "tls": {
    "grade": "A+",
    "cert_valid": true,
    "hsts": true,
    "protocol": "TLS 1.3"
  },
  "tools": {
    "total": 14,
    "l1_minimal": 8,
    "l2_moderate": 5,
    "l3_elevated": 1,
    "l4_critical": 0
  },
  "analysis_status": "complete",
  "analyzed_at": "2026-03-26T10:00:00Z"
}

Asynchronous analysis When an endpoint is submitted for the first time, the API returns 202 Accepted with "analysis_status": "pending". Poll /api/v1/trust/{endpoint}/status until the status transitions to complete, then re-fetch the full trust score.