Deploy the Vault MCP server

The Vault Model Context Protocol (MCP) server enables AI models to interact with Vault and perform actions using up-to-date APIs. This page explains how to install, configure, and integrate the MCP server with your AI client.

Overview

The Vault MCP server is a specialized service that provides AI models with access to Vault APIs. You can deploy the server using the stdio mode for direct communication through standard input/output, or using streamable-http for network-based communication.

The Vault MCP server is still in beta. We recommend that you only run the server locally, without exposing it to other network users.

Installation methods

Choose from three installation options based on your environment and preferences:

Method	Best for	Requirements
Docker	Most users, consistent environments	Docker Engine v20.10.21+ or Docker Desktop v4.14.0+. Refer to the Docker documentation for installation instructions.
Compiled binary	Lightweight deployments, specific OS needs	Compatible operating system
Source installation	Development, customization	Go development environment

Run in Docker

Docker provides the most reliable and consistent way to run the Vault MCP server across different environments.

Start Docker on your system.
Integrate with your AI client:

Verify Visual Studio Code is installed.
Verify the GitHub Copilot extension is installed and chats are configured to Agent mode.
Verify MCP support enabled, refer to the VS Code MCP documentation for more information.

To use the MCP server in all workspaces, add the following configuration to your user settings JSON file:

{
  "mcp": {
    "servers": {
      "vault-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e", "VAULT_ADDR",
          "-e", "VAULT_NAMESPACE",
          "-e", "VAULT_TOKEN",
          "hashicorp/vault-mcp-server"
        ],
        "env": {
          "VAULT_ADDR": "${input:vault_address}",
          "VAULT_NAMESPACE": "${input:vault_namespace}",
          "VAULT_TOKEN": "${input:vault_token}"
        },
        "type": "stdio"
      }
    },
    "inputs": [
      {
          "type": "promptString",
          "id": "vault_address",
          "description": "Vault address",
          "password": false
      },
      {
          "type": "promptString",
          "id": "vault_namespace",
          "description": "Vault Namespace (optional)",
          "password": false
      },
      {
          "type": "promptString",
          "id": "vault_token",
          "description": "Vault Token",
          "password": true
      }
    ]
  }
}

Alternatively, to use the server in a specific workspace, create an mcp.json file with the following configuration in your workspace's .vscode directory:

{
"inputs": [
  {
      "type": "promptString",
      "id": "vault_address",
      "description": "Vault address",
      "password": false
  },
  {
    "type": "promptString",
    "id": "vault-namespace",
    "description": "Vault Namespace (optional)",
    "password": false
  },
  {
    "type": "promptString",
    "id": "vault-token",
    "description": "Vault Token",
    "password": true
  }
],
"servers": {
  "vault-mcp-server": {
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "-e", "VAULT_ADDR",
          "-e", "VAULT_NAMESPACE",
          "-e", "VAULT_TOKEN",
          "hashicorp/vault-mcp-server"
      ],
      "env": {
          "VAULT_ADDR": "${input:vault_address}",
          "VAULT_NAMESPACE": "${input:vault_namespace}",
          "VAULT_TOKEN": "${input:vault_token}"
      },
      "type": "stdio"
  }
}
}

Verify the integration by opening the chat interface and selecting Agent from the mode settings.
Click the tools icon to verify that Vault MCP server tools appear in the available tools list.

Verify Cursor is installed.
Verify the MCP support configured, refer to Cursor's MCP documentation for more information.

To use the MCP server in all workspaces, add the following configuration to your user settings JSON file:

{
  "mcp": {
    "servers": {
      "vault": {
          "command": "docker",
          "args": [
              "run",
              "-i",
              "--rm",
              "-e", "<<vault_address_here>>",
              "-e", "<<vault_namespace_here>>",
              "-e", "<<vault_token_here>>",
              "hashicorp/vault-mcp-server"
          ],
          "type": "stdio"
      }
    }
  }
}

Alternatively, to use the server in a specific workspace, create an mcp.json file with the following configuration in your workspace's .vscode directory:

{
  "servers": {
  "vault": {
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "-e", "<<vault_address_here>>",
          "-e", "<<vault_namespace_here>>",
          "-e", "<<vault_token_here>>",
          "hashicorp/vault-mcp-server"
      ],
      "type": "stdio"
  }
  }
}

Verify the installation by opening the chat pane and selecting Chat Settings from the ellipses menu.
Choose Agent from the Default new chat mode drop-down menu.
Select MCP from the Cursor Settings sidebar to verify that Vault MCP server tools are enabled.

Verify Claude Desktop is installed.
Verify MCP support is configured, refer to Claude Desktop's MCP documentation for more information.

Create or edit the mcp.json file and add the following configuration:

{
  "mcpServers": {
    "servers": {
      "vault-mcp-server": {
          "command": "docker",
          "args": [
              "run",
              "-i",
              "--rm",
              "-e", "<<vault_address_here>>",
              "-e", "<<vault_namespace_here>>",
              "-e", "<<vault_token_here>>",
              "hashicorp/vault-mcp-server"
          ],
          "type": "stdio"
      }
    }
  }
}

Verify the integration by opening the chat pane and clicking the search and tools slider icon.
Click vault-mcp-server to verify that all tools are enabled and accessible.

Verify Amazon Q is installed.
Verify MCP support is configured, refer to Amazon Q's MCP documentation for more information.
Create or edit the mcp.json file with the following configuration:

{
  "mcpServers": {
    "servers": {
      "vault-mcp-server": {
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--rm",
            "-e", "<<vault_address_here>>",
            "-e", "<<vault_namespace_here>>",
            "-e", "<<vault_token_here>>",
            "hashicorp/vault-mcp-server"
        ],
        "type": "stdio"
      }
    }
  }
}

Run the compiled binary

The compiled binary option provides a lightweight installation without Docker dependencies. This method is ideal when you want to minimize resource usage or work in environments with restricted container access.

Download the binary for your operating system and architecture, visit the release library.

Add the following configuration to your client settings. Replace /path/to/vault-mcp-server with the actual path to your downloaded binary.

{
  "mcp": {
    "servers": {
      "vault": {
        "command": "/path/to/vault-mcp-server",
        "args": ["stdio"],
        "env": {
          "VAULT_ADDR": "<<vault_address_here>>",
          "VAULT_NAMESPACE": "<<vault_namespace_here>>",
          "VAULT_TOKEN": "<<vault_token_here>>"
            }
      }
    }
  }
}

Install from source

Installing from source gives you access to the latest features and allows for customization. This method requires a Go development environment.

Install the latest stable release.

$ go install github.com/hashicorp/vault-mcp-server/cmd/vault-mcp-server@latest

Alternatively, you can install the development version on main.

$ go install github.com/hashicorp/vault-mcp-server/cmd/vault-mcp-server@main

After installation, add the following configuration to your client.

{
  "mcp": {
    "servers": {
      "vault": {
        "command": "/path/to/vault-mcp-server",
        "args": ["stdio"],
        "env": {
          "VAULT_ADDR": "<<vault_address_here>>",
          "VAULT_NAMESPACE": "<<vault_namespace_here>>",
          "VAULT_TOKEN": "<<vault_token_here>>"
        }
      }
    }
  }
}

Replace /path/to/vault-mcp-server with the actual path to your downloaded binary. The binary location depends on your Go installation and GOPATH configuration.

Use which vault-mcp-server to find the installed binary path.

Start the server

You can use the vault-mcp-server CLI and specify the transport protocol you want to use to start the server. Refer to the transport protocols reference for more information.

Start the server in stdio mode.

$ vault-mcp-server stdio [--log-file /path/to/log]

Run the following command on the local instance to start the server in streamable-http mode:

$ vault-mcp-server streamable-http \
  [--transport-port 8080] \
  [--transport-host 127.0.0.1] \
  [--mcp-endpoint /mcp] \
  [--log-file /path/to/log]

Instead of setting values manually, you can also use the supported environment variables. Refer to the environment variables reference for details.

Next steps

Begin prompting your AI model about Vault operations. Refer to Prompt an AI model for guidance on effective prompting techniques.
Ask for help with specific Vault operations and workflows.
Explore advanced configuration options for your specific deployment needs.