Guardian CLI tool

Send an auth token

Send your MCP server's auth token to the server under test with guardian test or guardian scan, using --header-env (recommended) or --header.

If your MCP server needs a token, usually in an Authorization header, the CLI sends it with each request to that server. It works for guardian test and guardian scan.

This is your MCP server's token, not your Guardian sign-in (that's guardian login). Use a dedicated, least-privilege token, not a production or admin credential: the server receives it, and the test calls tools with that token's permissions.

--header-env Authorization=MCP_TOKEN puts only the variable's name on the command line, so it's safe in shell history, the process list, CI logs, scripts and bug reports. The CLI reads the value from its own environment when it runs.

The variable holds the whole header value, for example Bearer YOUR_TOKEN. Set it without the value reaching your shell history. When it asks, type Bearer and then your token:

# bash or zsh: nothing is shown or saved to history
read -rs MCP_TOKEN && export MCP_TOKEN
# PowerShell 7.1 or later
$env:MCP_TOKEN = Read-Host -MaskInput

For Windows PowerShell 5.1, see Send a secret header.

Then run a test or a scan:

guardian test --target-url https://HOST/mcp --allow-target HOST --header-env Authorization=MCP_TOKEN
guardian scan --target-url https://HOST/mcp --header-env Authorization=MCP_TOKEN
  • Locally, export the variable for the session, or load it from a password manager or keychain.
  • In CI, use the CI system's secret store. Never commit the token.
  • The CLI reads the value only from its own environment. It doesn't load .env files itself.
  • Variable names starting with GUARDIAN_, in any case, are refused, so a Guardian variable can't be used as a target header. Never put your Guardian token in a header. guardian scan refuses one; guardian test can't tell.

In GitHub Actions, pass the secret with step-level env::

- name: Scan the MCP server
  env:
    MCP_TOKEN: Bearer ${{ secrets.MCP_TOKEN }}
    GUARDIAN_TOKEN: ${{ secrets.GUARDIAN_TOKEN }}
  run: guardian scan --target-url https://HOST/mcp --header-env Authorization=MCP_TOKEN --yes

Directly on the command line

With --header, the value sits on the command line. It's saved in your shell history, other users on the machine can see it in the process list, and it gets copied into CI job definitions and logs. Don't use it for a real token.

It's fine for a throwaway token against a local mock server:

guardian test --target-url http://127.0.0.1:8765/mcp --header "Authorization: Bearer YOUR_TOKEN"

What the CLI does with the header

  • guardian test sends it only to the --target-url, on every request of the run, and doesn't follow redirects. Values are never printed (stdout, stderr or --out) or uploaded to Guardian.
  • guardian scan sends the header values to Guardian, whose cloud uses them to connect to your server. They're not stored with the run, and the CLI never prints them. Scan refuses loopback and private hosts, so test a local server with guardian test.
  • Use https for any server that isn't on your own machine. Over http the token crosses the network unencrypted, and guardian test gives no warning.
  • Header names the CLI sets itself are refused, such as User-Agent.

More detail: Send a secret header.