NAME¶

bugwarden - MCP server for Bugzilla with operator-controlled security guards

SYNOPSIS¶

bugwarden --bugzilla-server <BUGZILLA_SERVER> [--transport <TRANSPORT>] [--host <HOST>] [--port <PORT>] [--allowed-hosts <HOST>] [--api-key-header <API_KEY_HEADER>] [--api-key <API_KEY>] [--api-key-file <API_KEY_FILE>] [--use-auth-header] [--read-only] [--policy <POLICY>] [--audit-config <AUDIT_CONFIG>] [--insecure-no-auth] [-h|--help] [-V|--version]

DESCRIPTION¶

MCP server for Bugzilla with operator-controlled security guards

OPTIONS¶

--bugzilla-server <BUGZILLA_SERVER>

Base URL of the Bugzilla server (e.g., `https://bugzilla.example.com`). Environment variable BUGZILLA_SERVER is used if the argument is not provided

--transport <TRANSPORT> [default: http]

Transport for the MCP server: 'http' (default) or 'stdio'. Environment variable MCP_TRANSPORT can also be used

Possible values:

--host <HOST> [default: 127.0.0.1]

Host address for the MCP server to listen on (http transport only). Defaults to 127.0.0.1 or the MCP_HOST environment variable

--port <PORT> [default: 8000]

Port for the MCP server to listen on (http transport only). Defaults to 8000 or the MCP_PORT environment variable

--allowed-hosts <HOST>

Hostname or 'host:port' authority accepted in an inbound Host header (http transport only). Repeat the flag, or separate entries with commas; environment variable MCP_ALLOWED_HOSTS can also be used. Empty entries are dropped, so `MCP_ALLOWED_HOSTS=` is an unset (like `BUGZILLA_API_KEY_FILE=`); without a host, Host validation stays off and any Host header is served. An entry that is not a hostname or host:port (for example '*', a URL, or a space-containing typo) is a startup error

--api-key-header <API_KEY_HEADER> [default: ApiKey]

HTTP header for clients to send the Bugzilla API key. Defaults to 'ApiKey' or the MCP_API_KEY_HEADER environment variable. Not consulted in server-held key mode (--api-key-file over http)

--api-key <API_KEY>

Bugzilla API key. Required for --transport stdio (no HTTP headers exist there) unless --api-key-file provides it. Environment variable BUGZILLA_API_KEY can also be used. Ignored for --transport http (clients send the key per-request via the API key header; use --api-key-file for a server-held key)

--api-key-file <API_KEY_FILE>

Path to a file holding the Bugzilla API key (e.g. a container secret or systemd LoadCredential path). Mutually exclusive with --api-key. Over http this selects server-held key mode: every request is served with this key and the per-request API key header is not consulted. An empty value counts as absent, like --api-key (so `BUGZILLA_API_KEY_FILE=` is an unset, not an error)

--use-auth-header

Use 'Authorization: Bearer' header instead of the api_key query parameter (required for some Bugzilla instances). Environment variable BUGZILLA_USE_AUTH_HEADER=true can also be used

--read-only

Disables all tools which modify the state of a bug. Environment variable MCP_READ_ONLY=true can also be used. Can only tighten the guard policy, never loosen it

--policy <POLICY>

Path to the guard policy TOML file. Environment variable BUGWARDEN_POLICY can also be used. Without it an allow-all default policy is used

--audit-config <AUDIT_CONFIG>

Path to the audit configuration TOML file (see examples/audit.toml). Environment variable BUGWARDEN_AUDIT_CONFIG can also be used. The exact value `none` disables the audit file (OTLP-only when an endpoint is set). Without it, and with no OTLP endpoint, no audit stream is written. An endpoint with no file decision, or `none` with no endpoint, is a startup error

--insecure-no-auth

Serve the http transport without bearer authentication. Only for a trusted, isolated network: every caller that reaches the port gets the full write scope. Command line only, with no environment variable, so no ambient value can turn authentication off. Tokens are never taken from the command line either (argv is world-readable): set BUGWARDEN_HTTP_TOKEN / BUGWARDEN_HTTP_READ_TOKEN in the environment

-h, --help

Print help (see a summary with '-h')

-V, --version

Print version

EXIT STATUS¶

0

Clean shutdown.

1

Startup or runtime failure: a missing or malformed http bearer token, an unreadable policy or audit configuration, a key misconfiguration, an unparsable --allowed-hosts list, an OTLP collector that will not take records, a Bugzilla client or transport error.

2

Command-line usage error.

ENVIRONMENT¶

Most variables are the fallback for one option; a command-line argument always wins over the environment, and the built-in default applies when neither is given. The two bearer tokens are the exception: they have no option at all and are read from the environment only, because argv is world-readable.

BUGZILLA_SERVER

Fallback for --bugzilla-server.

MCP_TRANSPORT

Fallback for --transport.

MCP_HOST

Fallback for --host.

MCP_PORT

Fallback for --port.

MCP_ALLOWED_HOSTS

Fallback for --allowed-hosts.

MCP_API_KEY_HEADER

Fallback for --api-key-header.

BUGZILLA_API_KEY

Fallback for --api-key.

BUGZILLA_API_KEY_FILE

Fallback for --api-key-file.

BUGZILLA_USE_AUTH_HEADER

Fallback for --use-auth-header.

MCP_READ_ONLY

Fallback for --read-only.

BUGWARDEN_POLICY

Fallback for --policy.

BUGWARDEN_AUDIT_CONFIG

Fallback for --audit-config.

BUGWARDEN_HTTP_TOKEN

Bearer token granting the write scope over the http transport: every tool the guard policy serves. Environment only - there is no command-line flag, because argv is world-readable. At least 32 printable non-space ASCII characters.

BUGWARDEN_HTTP_READ_TOKEN

Bearer token granting the read scope over the http transport: the read tools only. Same rules, and it must differ from BUGWARDEN_HTTP_TOKEN. Either token may be set alone; over http, setting neither is a startup error unless --insecure-no-auth is given.

OTEL_EXPORTER_OTLP_ENDPOINT

Base URL of an OpenTelemetry collector (bugwarden appends /v1/logs). Environment only. Unset or empty turns export off. Must be paired with --audit-config / BUGWARDEN_AUDIT_CONFIG (a file, or the exact value none). An endpoint with no file decision is a startup error.

OTEL_EXPORTER_OTLP_HEADERS

Headers added to every export request, key=value separated by commas. Credential material (I12): environment only, never logged.

OTEL_EXPORTER_OTLP_PROTOCOL

The one accepted value is http/protobuf; anything else is a startup error. Not consulted while export is off.

OTEL_SERVICE_NAME

service.name on exported records. Defaults to bugwarden.

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

Logs-specific endpoint; overrides OTEL_EXPORTER_OTLP_ENDPOINT and is used as given (write the whole URL including /v1/logs).

OTEL_EXPORTER_OTLP_LOGS_HEADERS

Logs-specific headers; overrides OTEL_EXPORTER_OTLP_HEADERS. Same secrecy.

OTEL_EXPORTER_OTLP_LOGS_PROTOCOL

Logs-specific protocol; overrides OTEL_EXPORTER_OTLP_PROTOCOL.

FILES¶

/etc/bugwarden/policy.toml

Worked example guard policy as installed by distribution packages; the source tree and release archives ship it as examples/policy.toml. The server reads a policy only when one is named with --policy or BUGWARDEN_POLICY; without one the built-in allow-all default policy applies.

/etc/bugwarden/audit.toml

Worked example audit configuration; the source tree ships it as examples/audit.toml. Without --audit-config or BUGWARDEN_AUDIT_CONFIG and with no OTLP endpoint, no audit stream is written. The exact value none disables the file so a collector can be the only sink.

EXAMPLES¶

Serve a local MCP client over stdio, the server reading the Bugzilla API key from a file:

bugwarden --transport stdio \


    --bugzilla-server https://bugzilla.example.com \


    --api-key-file ~/.config/bugwarden/api-key \


    --policy /etc/bugwarden/policy.toml

Listen on HTTP (the default transport, 127.0.0.1:8000), each client presenting a bearer token to this server and its own key in the API key header. The token is minted once and kept - a value generated inline would start a server no client could present a credential to:

export BUGWARDEN_HTTP_TOKEN="$(cat /etc/bugwarden/http-token)"
bugwarden --bugzilla-server https://bugzilla.example.com \


    --policy /etc/bugwarden/policy.toml

Listen on HTTP with a server-held key (container secret, systemd LoadCredential): every request is served with this key and the per-request key header is not consulted, so the bearer token is the only thing a client presents:

export BUGWARDEN_HTTP_TOKEN="$(cat /etc/bugwarden/http-token)"
bugwarden --bugzilla-server https://bugzilla.example.com \


    --api-key-file /run/secrets/bugzilla-api-key \


    --policy /etc/bugwarden/policy.toml