# Connect a HashiCorp Vault MCP Server to Teleport

Teleport can provide secure access to MCP servers via Teleport Application Service.

In this guide, you will:

1. Configure your HashiCorp Vault service for access by the MCP server.
2. Run the HashiCorp Vault MCP Server.
3. Enroll the MCP server into your Teleport cluster and connect to it.

## How it works

The [HashiCorp Vault MCP server](https://github.com/hashicorp/vault-mcp-server) uses a service token to access HashiCorp Vault and runs on a local endpoint reachable by the Teleport Application Service. Teleport proxies all client requests to the server, which interacts with HashiCorp Vault using the permissions granted by the policy bound to the token.

## Prerequisites

- A running Teleport (v18.3.0 or higher) cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/ver/19.x/get-started/deploy-community.md).

- The `tsh` client.

  Installing `tsh` client

  1. Determine the version of your Teleport cluster. The `tsh` client must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tsh` client:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tsh` client:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tsh` client to your %PATH%
     NOTE: Do not place the `tsh` client in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tsh` client. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/ver/19.x/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* Access to your Vault instance and sufficient privileges to manage policies.
* A host to run the MCP server that is reachable by the Teleport Application Service.
* A running Teleport Application Service. If you have not yet done this, follow the [Getting Started guide](https://goteleport.com/docs/ver/19.x/enroll-resources/mcp-access/getting-started.md).
* A Teleport user with sufficient permissions (e.g. role `mcp-user`) to access MCP servers.

## Step 1/3. Create a policy in Vault

First, create a policy file:

```
$ cat > mcp-readonly.hcl <<EOF
# Read/list all secrets and metadata stored in the KV v2 engine at "secret/"
path "secret/data/*" {
  capabilities = ["read", "list"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}
EOF
```

This example grants read-only access to all secrets stored under the `secret/` KV v2 engine. You can tighten or expand these paths depending on your needs.

To load the policy into Vault:

```
$ vault policy write mcp-readonly mcp-readonly.hcl
```

Once the policy created, generate a Vault token that the MCP server will use:

```
$ vault token create -policy="mcp-readonly" -display-name="teleport-mcp-service" -ttl=720h
```

Copy the result token for use in the next step.

## Step 2/3. Run the Vault MCP server

The Vault MCP Server can be run either as a compiled binary or via the official Docker image:

**vault-mcp-server binary**

To start the MCP server in streamable-HTTP mode:

```
$ export TRANSPORT_MODE=http
$ export TRANSPORT_HOST=MCP_HOST # or listen to a network that is reachable by Teleport
$ export VAULT_ADDR=VAULT_ADDR
$ export VAULT_TOKEN=VAULT_TOKEN
$ ./vault-mcp-server
```

Replace MCP\_HOST with the hostname of the host machine running the MCP server. The host must be reachable by the Teleport Application Service.

**docker**

To start the MCP server in streamable-HTTP mode:

```
$ docker run -d -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e VAULT_ADDR=VAULT_ADDR \
  -e VAULT_TOKEN=VAULT_TOKEN \
  --name vault-teleport-mcp hashicorp/vault-mcp-server
```

After starting, the Vault MCP Server exposes a streamable-HTTP endpoint at `http://MCP_HOST:8080/mcp`.

## Step 3/3. Connect via Teleport

You can register an MCP application in Teleport by defining it in your Teleport Application Service configuration, or by using dynamic registration with `tctl` or Terraform:

**Static configuration**

Replace MCP\_HOST with the host running the Vault MCP server:

```
app_service:
  enabled: "yes"
  apps:
  - name: "vault-mcp"
    uri: "mcp+http://MCP_HOST:8080/mcp"
    labels:
      env: dev
      service: vault

```

Restart the Application Service.

**tctl**

Create an `app` resource definition file named `app-vault-mcp.yaml`. Replace MCP\_HOST with the host running the Vault MCP server:

```
# app-vault-mcp.yaml
kind: app
version: v3
metadata:
  name: vault-mcp
  labels:
    env: dev
    service: vault
spec:
  uri: "mcp+http://MCP_HOST:8080/mcp"

```

Create the `app` resource with:

```
$ tctl create -f app-vault-mcp.yaml
```

**Terraform**

Create a `teleport_app` resource in terraform. Replace MCP\_HOST with the host running the Vault MCP server:

```
resource "teleport_app" "vault" {
  version = "v3"
  metadata = {
    name = "vault"
    labels = {
      "teleport.dev/origin" = "dynamic"
      "env"                 = "dev"
      "service"             = "vault"
    }
  }

  spec = {
    uri = "mcp+http://MCP_HOST:8080/mcp"
  }
}

```

Apply the configuration:

```
$ terraform apply
```

To grant access to the MCP server and all its tools, assign the preset `mcp-user` role to your Teleport user.

Optionally, you can limit which MCP tools the user can access by adjusting the `mcp.tools` list in their role. For example:

```
kind: role
version: v8
metadata:
  name: vault-mcp-readonly
spec:
  allow:
    app_labels:
      'service': 'vault'
    mcp:
      tools:
      - ^(get|list)_.*$

```

Now wait until the application appears in `tsh mcp ls`, then configure your MCP clients to access the MCP server, for example:

```
$ tsh mcp config vault-mcp --client-config claude
```

After configuring your MCP client, you will find Vault-related tools from `teleport-mcp-vault-mcp`. You can now use these tools to interact with Vault via Teleport in your MCP clients:

![Vault Claude](/docs/assets/images/vault-claude-a95914a054cf012da48fbbb01d3cddc0.png)

## Next steps

- Review [Enroll a Streamable-HTTP MCP Server](https://goteleport.com/docs/ver/19.x/enroll-resources/mcp-access/enrolling-mcp-servers/streamable-http.md).
- See the [dynamic registration](https://goteleport.com/docs/ver/19.x/enroll-resources/mcp-access/dynamic-registration.md) guide.
- Learn more about [vault-mcp-server](https://github.com/hashicorp/vault-mcp-server).
- Connect your [MCP clients](https://goteleport.com/docs/ver/19.x/connect-your-client/model-context-protocol/mcp-access.md).