Skip to main content

Connect a HashiCorp Vault MCP server to Teleport

Report an issue with this page

This guide demonstrates how to run a HashiCorp MCP server and connect it via Teleport.

How it works​

The HashiCorp Vault MCP server uses a service token to access HashiCorp Vault and runs on a local endpoint reachable by Teleport. 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 for a free trial or set up a demo environment.

  • 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:

      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.

  • 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.
  • Running Teleport Application Service.
  • 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:

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.

After starting, the Vault MCP Server exposes a streamable-HTTP endpoint at http://localhost: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:

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.

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 interactive with Vault via Teleport in your MCP clients:

Next Steps​