Boundary MCP server configuration reference
Use this reference when configuring the Boundary MCP server at startup or from the command line.
Environment variables
Use the following environment variables to configure the server at startup.
| Variable | Description | Default |
|---|---|---|
BOUNDARY_ADDR | Boundary controller address, for example https://cluster.boundary.hashicorp.cloud:9200. In local mode, a per-request BOUNDARY_ADDR header overrides this value. In remote mode, this variable (or --boundary-addr) is required at startup and the header is ignored. | "" |
BOUNDARY_TOKEN | Boundary API token. In local mode, used as a fallback when a request carries no BOUNDARY_TOKEN header. The header takes precedence when present. In remote mode, this variable is ignored and the BOUNDARY_TOKEN header is required on every request. | "" |
BOUNDARY_MCP_ADDR | Listen address for the MCP HTTP server. Overridden by the --addr flag. | 127.0.0.1:0 |
BOUNDARY_MCP_TLS_CERT | Path to a PEM certificate file. Must be set together with BOUNDARY_MCP_TLS_KEY. When both are set, the server enables TLS with a minimum version of TLS 1.3. | "" |
BOUNDARY_MCP_TLS_KEY | Path to a PEM private key file. Must be set together with BOUNDARY_MCP_TLS_CERT. Setting only one of the two causes startup to fail. | "" |
When you set neither BOUNDARY_MCP_TLS_CERT nor BOUNDARY_MCP_TLS_KEY, the server serves plain HTTP and logs a warning at startup if the listen address is not a loopback address.
CLI flags
Use the following flags when starting the server from the command line.
| Flag | Description | Default |
|---|---|---|
--mode | Deployment topology. local runs the server on the operator's machine and permits the connect toolset to be enabled. remote disables the process-environment token fallback and never registers connect. | local |
--addr | Listen address for the MCP HTTP server, for example 127.0.0.1:8080. Overrides BOUNDARY_MCP_ADDR. | 127.0.0.1:0 |
--boundary-addr | Boundary controller address. Required in remote mode (or set BOUNDARY_ADDR). In local mode, used when a request has no BOUNDARY_ADDR header. Falls back to the BOUNDARY_ADDR environment variable. | "" |
--token-revalidation-interval | Minimum interval between controller revalidations of a session token on tools/call. Set to 0 to revalidate on every call. Negative values are rejected. | 30s |
--toolsets | Comma-separated toolset names or a keyword (default, read-only, all). Mutually exclusive with --tools. | default |
--tools | Comma-separated individual tool names. Bypasses toolset grouping. Mutually exclusive with --toolsets. Naming a local-only tool such as connect_session with --mode remote is a startup error. | "" |
--log-level | Logging verbosity. Accepted values: trace, debug, info, warn, error, fatal, panic. | info |
--log-format | Logging output format. Accepted values: text, json. | text |
--log-file | Write logs to this file instead of stderr. | "" |
Subcommands
| Subcommand | Description |
|---|---|
list-tools | Print every tool in the registry grouped by toolset, with the deployment modes each is available in. |
version | Print the server version and exit. |
HTTP headers
Clients can pass the following HTTP headers on each request. The headers apply in both local and remote mode, but their behavior differs depending on the mode.
| Header | Description |
|---|---|
BOUNDARY_TOKEN | Boundary API token for the requesting user. Required in remote mode. |
BOUNDARY_ADDR | Boundary controller address. In local mode, overrides the server's configured address for that request. In remote mode, the address is fixed at startup using --boundary-addr or the BOUNDARY_ADDR environment variable. The server does not start without one, and the header is ignored. |
x-correlation-id | Optional UUID forwarded to Boundary so that MCP audit logs can be joined with controller audit events. If the client supplies a valid UUID, the server reuses it. If the value is invalid, the server replaces it with a generated UUID. |
Toolsets
A toolset is a named group of related tools. Use the --toolsets flag to enable one or more toolsets by name, or use a keyword to enable a predefined combination.
Keywords
| Keyword | Toolsets enabled |
|---|---|
default | targets, sessions |
read-only | All read toolsets (no admin toolsets), including connect in local mode |
all | All toolsets, including admin and connect in local mode. connect is never registered in remote mode. |
Available toolsets
| Toolset | Description |
|---|---|
targets | List and read targets |
targets-admin | Create, update, and delete targets; manage credential and host source associations |
sessions | List and read sessions, and cancel sessions (cancel_session) |
users | List and read users |
users-admin | Create, update, and delete users; manage account associations |
workers | List and read workers |
workers-admin | Update and delete workers |
scopes | List and read scopes |
scopes-admin | Create, update, and delete scopes |
accounts | List and read accounts |
accounts-admin | Create, update, and delete accounts |
authmethods | List and read auth methods |
authmethods-admin | Create (password and secret-free ldap types only), update, and delete auth methods |
groups | List and read groups |
groups-admin | Create, update, and delete groups; manage members |
roles | List and read roles |
roles-admin | Create, update, and delete roles; manage grants and principals |
hosts | List and read hosts |
hosts-admin | Create, update, and delete hosts |
hostsets | List and read host sets |
hostsets-admin | Create, update, and delete host sets; manage hosts |
hostcatalogs | List and read host catalogs |
hostcatalogs-admin | Create, update, and delete host catalogs |
credentials | List and read credentials |
credentials-admin | Update and delete credentials |
credentialstores | List and read credential stores |
credentialstores-admin | Create (static stores only), update, and delete credential stores |
credentiallibraries | List and read credential libraries |
credentiallibraries-admin | Create, update, and delete credential libraries |
managedgroups | List and read managed groups |
managedgroups-admin | Create, update, and delete managed groups |
sessionrecordings | List and read session recordings |
storagebuckets | List and read storage buckets |
storagebuckets-admin | Create, update, and delete storage buckets |
aliases | List and read aliases |
aliases-admin | Create, update, and delete aliases |
policies | List and read policies |
policies-admin | Create, update, and delete policies |
connect | Establish a local proxy session to a target using connect_session. Supports SSH and RDP targets only. TCP targets are rejected. Available in local mode only. |
For details on which operations are not supported due to secret-handling restrictions, refer to the Boundary MCP server overview.