Run the Boundary MCP server

You can run the Boundary MCP server using a pre-built binary or a locally built Docker image. After the server is running, refer to Configure MCP clients for the Boundary MCP server to connect your MCP client.

Public preview

Public preview functionality is stable, but possibly incomplete and subject to change. We strongly discourage using preview features in production deployments of Boundary.

You can run the server in two ways, depending on your environment:

Binary: Run a pre-built binary downloaded from the HashiCorp releases page.
Docker: Build a container image locally from the downloaded source archive and run the server over the Streamable HTTP transport on localhost:8080.

Requirements

A running HCP Boundary cluster or Boundary Enterprise deployment.
A Boundary token with permissions for the resources you want to manage. Refer to Permissions in Boundary for more information.
An MCP client that supports the Streamable HTTP transport. Verified clients include Visual Studio Code, Cursor, Claude Desktop, Amazon Q Developer, and IBM Bob.
To use the connect toolset, an SSH or RDP target configured for credential injection. The connect toolset does not support other target types, such as TCP targets.

Run from the binary

Download and run the pre-built binary when you want to run the server directly without Docker.

Install the binary

Download the binary for your operating system and architecture from the HashiCorp releases page.
Move the binary to a directory in your PATH and make it executable. For example, on Linux or macOS:
```
$ mv boundary-mcp-server /usr/local/bin/
$ chmod +x /usr/local/bin/boundary-mcp-server
```
Verify the installation:
```
$ boundary-mcp-server version
```

Start the server

Run the following command to start the server. By default, the server listens on a random port, so use the --addr flag to set the address that your MCP client connects to:
```
$ boundary-mcp-server --addr 127.0.0.1:8080
```
The server runs in the foreground. Leave the terminal open while you use the server, or run the command as a background process.
In a separate terminal, confirm the server is running:
```
$ curl http://127.0.0.1:8080/healthz
```

To supply your Boundary address and token, refer to Configure MCP clients for the Boundary MCP server.

Run with Docker

Use Docker when you prefer a containerized deployment. The Docker method builds the image locally from the downloaded source archive. The server listens on the port you configure with BOUNDARY_MCP_ADDR.

Requirements

Build and run the server

Download the source archive for your target version from the HashiCorp releases page and extract it:
```
$ tar -xzf boundary-mcp-server_<version>.tar.gz
$ cd boundary-mcp-server_<version>
```
Build the Docker image:
```
$ make docker-build
```

Run the server, replacing <<BOUNDARY_ADDR_HERE>> with your Boundary controller address, for example https://cluster.boundary.hashicorp.cloud:9200:

$ docker run -p 127.0.0.1:8080:8080 --rm \
    -e BOUNDARY_MCP_ADDR=0.0.0.0:8080 \
    -e BOUNDARY_ADDR=<<BOUNDARY_ADDR_HERE>> \
    boundary-mcp-server:<version>

Confirm the server is running:
```
$ curl http://localhost:8080/healthz
```

The connect toolset does not work inside a container. The connect_session tool binds a proxy to 127.0.0.1 inside the container's network namespace, so the address it returns is unreachable from your machine. To use connect_session, run the binary directly on your workstation instead.

More information

Next steps

Configure MCP clients for the Boundary MCP server