Run the Vault MCP server with Docker

Beta feature

Beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments of Vault.

We recommend running the MCP server in Docker for most users because it provides the most reliable and consistent way to run the Vault MCP server across different environments.

Assumptions

You have Docker installed. The MCP server requires Docker Engine v20.10.21+ or Docker Desktop v4.14.0+. = You have Docker running locally.
You plan to use the server in stdio mode for direct communication through standard input/output. If you need to use network-based communication, change the stdio argument to streamable-http.

Option 1: Run MCP globally

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.
Open your user settings JSON file.

Add the mcp configuration details:

{
  "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
      }
    ]
  }
}

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.
Open your user settings JSON file.

Add the following mcp configuration:

{
  "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"
      }
    }
  }
}

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"
      }
    }
  }
}

Option 2: Run MCP in a specific workspace

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.
Create a new mcp.json file in the .vscode directory for your workspace.

Add the following mcp configuration details:

{
"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.
Create a new mcp.json file in the .vscode directory of your workspace.

Add the mcp configuration details:

{
  "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.

Next steps

Try the Write secrets to kv example prompt to begin prompting your AI model about Vault operations.
Ask your AI agent for help with specific Vault operations and workflows.
Explore advanced configuration options for your specific deployment needs.