HashiCorp Vault MCP Server Cursor IDE Setup 2026: stdio, HTTP & KV/PKI Tools

How do you set up the HashiCorp Vault MCP server in Cursor? Run the official hashicorp/vault-mcp-server over stdio via Docker, passing VAULT_ADDR and VAULT_TOKEN as environment variables in a mcpServers block in mcp.json, or point Cursor at a Streamable HTTP instance of the same server with the token in an X-Vault-Token header. Either way, once connected, Cursor's agent can list secret mounts, read and write KV secrets, and manage PKI issuers and roles against your real Vault cluster instead of you copy-pasting vault kv get output into chat.

This is the official server — hashicorp/vault-mcp-server on GitHub — not a community wrapper. HashiCorp ships it with two transports and a fixed, documented tool set covering KV v1/v2 secrets engines and PKI. This guide adapts HashiCorp's published configuration (written for a generic MCP client) into the mcpServers schema Cursor actually reads, since the official examples use VS Code's servers-plus-inputs format, which Cursor does not support as-is.

If you're looking for a secrets-manager-as-a-service instead of a self-hosted Vault cluster, the 1Password MCP server guide covers a lighter-weight alternative. For the general pattern of scoping credentials across any MCP server, see how to authenticate MCP servers with OAuth and API keys.

What the Vault MCP server actually does

Vault MCP is a bridge between an AI coding agent and a running Vault cluster. It does not replace Vault, and it does not create a new auth boundary — every call it makes runs with the permissions attached to whatever VAULT_TOKEN you give it. If that token's policy can't read a path in the Vault UI or CLI, the MCP tool call fails the same way.

The server exposes three groups of tools, per HashiCorp's own repo documentation:

There is no tool for unsealing Vault, managing auth methods, or rotating the root token. This server assumes Vault is already unsealed and reachable, and that you're handing it a token — not standing up the cluster for you.

Two transports: stdio and Streamable HTTP

HashiCorp's repo documents both, and which one you want depends on how you run Vault:

stdio is the default. Cursor (or Docker on Cursor's behalf) launches the server as a short-lived subprocess for the session, and it talks over standard input/output. No open port, nothing else on the network needs to reach it. This is the simpler default for a single developer against a Vault instance they can already reach locally or over VPN.

Streamable HTTP runs the server as a long-lived process listening on a port (TRANSPORT_PORT, default 8080), reachable by URL. Use this when you want one running instance shared by a team, or when the server needs to sit behind a proxy rather than being spawned fresh by every editor session. HTTP mode adds MCP_ALLOWED_ORIGINS for CORS restriction, which stdio mode doesn't need since there's no browser origin involved.

Prerequisites

Step 1: Get a scoped Vault token

Create a policy before you create a token. A policy limited to read and list on the KV paths the agent needs, plus whatever PKI capabilities you actually want it exercising, is the right starting point — expand it only when a specific tool call fails with a permission-denied error, not up front.

vault policy write cursor-mcp-readonly - <<EOF
path "secret/data/*" {
  capabilities = ["read", "list"]
}
path "pki/issuers/*" {
  capabilities = ["read", "list"]
}
EOF

vault token create -policy="cursor-mcp-readonly" -ttl=8h

An 8-hour TTL matching a workday is a reasonable default for interactive use — you don't want a long-lived static token sitting in mcp.json any more than you'd want one in a shell history file.

Step 2: stdio config (Docker, recommended)

HashiCorp's own MCP client example uses VS Code's servers object with an inputs array that prompts for values interactively — that's a VS Code-specific mechanism Cursor doesn't implement. Cursor reads a top-level mcpServers key and doesn't have an equivalent prompt-on-connect flow, so the values need to be either hardcoded (fine for a local-only, gitignored file) or interpolated from your shell environment with Cursor's ${env:NAME} syntax.

{
  "mcpServers": {
    "vault": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "VAULT_ADDR",
        "-e", "VAULT_TOKEN",
        "-e", "VAULT_NAMESPACE",
        "hashicorp/vault-mcp-server"
      ],
      "env": {
        "VAULT_ADDR": "http://127.0.0.1:8200",
        "VAULT_TOKEN": "${env:VAULT_MCP_TOKEN}",
        "VAULT_NAMESPACE": ""
      }
    }
  }
}

VAULT_ADDR defaults to http://127.0.0.1:8200 if you omit it, which only works if Vault is reachable at that address from inside the Docker container — on macOS or Windows with Docker Desktop, 127.0.0.1 inside the container is not the same as your host's 127.0.0.1; use host.docker.internal instead if your Vault instance runs on the host machine outside Docker. VAULT_NAMESPACE is Vault Enterprise-only — leave it empty on open-source Vault, an empty string is not the same as omitting the variable but the server treats both the same way as "no namespace."

Restart Cursor after saving. Settings → MCP should show a green vault entry.

Step 3: Streamable HTTP config (shared or remote instance)

If you're running the server as a standing process — for a team, or because it needs to live behind an internal proxy rather than being launched per-session — start it with TRANSPORT_MODE=http and point Cursor's config at the URL instead of a command:

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "VAULT_ADDR": "http://127.0.0.1:8200",
        "X-Vault-Token": "${env:VAULT_MCP_TOKEN}",
        "X-Vault-Namespace": ""
      }
    }
  }
}

Note the header name changes shape between modes: the stdio path passes VAULT_TOKEN as a process environment variable, while the HTTP path expects the same credential as an X-Vault-Token header, not Authorization: Bearer. Getting this backwards — putting X-Vault-Token in a stdio env block, or VAULT_TOKEN in an HTTP headers block — is the single most common reason people report the server starting but every call failing with a permissions or connection error.

If the HTTP server sits behind TLS (it should, for anything beyond localhost), use https:// in the URL and make sure the certificate is one Cursor's underlying HTTP client trusts — a self-signed cert without the CA installed on your machine fails silently rather than with an obvious "untrusted cert" message in some Cursor builds.

Step 4: Verify the connection

In Cursor chat:

List the secret mounts in Vault

or

Read the secret at path secret/data/myapp/config

A real list of mounts, or actual secret data, confirms the token and path are both correct. An empty or error response usually means the policy on your token doesn't cover that path — check with vault token capabilities <token> <path> from the CLI before assuming the MCP config is wrong.

Practical workflows

Reading config before writing code:

Read the KV secret at secret/data/payments-service/stripe and tell me which keys are set, without printing the actual values in chat.

Asking the agent to confirm keys exist without echoing secret values back into the chat transcript is worth doing as a habit — chat history isn't a secure place to have live credentials sitting in plaintext, even in a local session.

Issuing a short-lived cert for local dev:

Issue a PKI certificate from the dev-internal issuer for the hostname api.dev.local, using the short-lived role.

Auditing mounts before onboarding a new service:

List every KV mount in this Vault cluster and tell me which ones look unused based on naming.

Cursor prompts for approval before running write tools by default — write_secret, delete_secret, create_mount, delete_mount, and the PKI create/issue tools all fall into that category. Read tools like list_secrets and read_secret are lower-risk to approve on sight; slow down and actually read the arguments on anything that writes, issues a certificate, or deletes a mount.

When not to use this

Don't wire a token with write access to production KV paths into a Cursor session that also has other, less-trusted MCP servers connected. A prompt-injection chain that gets an unrelated tool's output fed into a write_secret or delete_mount call is a realistic failure mode for any MCP server with write capability, not a hypothetical one — this is the same caution HashiCorp and other vendors give for MCP servers that can mutate state. Scope the token narrowly (Step 1), keep write tools behind manual approval, and don't leave a long-TTL token sitting in a config file on a shared machine.

Troubleshooting

Server never appears in Cursor. Confirm the config lives in ~/.cursor/mcp.json or .cursor/mcp.json, the top-level key is mcpServers (not HashiCorp's documented servers, which is VS Code's schema), and the JSON is valid — a single syntax error drops every server in the file, not just this one.

"connection refused" from inside the Docker container. This is almost always VAULT_ADDR pointing at 127.0.0.1 when Vault actually runs on your host machine, not inside the container's own network namespace. On Docker Desktop for Mac or Windows, use host.docker.internal in place of 127.0.0.1. On Linux, add --network host to the docker run args or use the host's real IP.

Permission denied on a read that works fine in the Vault CLI. The token attached to the MCP server and the token you're using in the CLI are probably not the same one, or the policy attached to the MCP token is narrower than you think. Run vault token lookup against the exact token in your mcp.json to see its attached policies, rather than assuming it matches whatever you're logged in as locally.

HTTP mode connects but every call 403s. Check that you sent X-Vault-Token, not Authorization: Bearer — this server's HTTP mode uses Vault's own header convention, not the generic bearer-token pattern most other MCP servers on this site use. Mixing up the two header names produces a request that reaches the server but fails Vault's own auth check.

Namespace-scoped secrets return nothing. VAULT_NAMESPACE only matters on Vault Enterprise. If you're on the open-source edition and set it anyway, most builds ignore it silently rather than erroring, but double-check by omitting it entirely if a namespaced-looking path returns empty.

Writes silently do nothing. Confirm you're not accidentally pointed at a read-only token, and that the mount you're writing to still exists — a mount that was deleted and recreated under the same path can have different KV version settings (v1 vs v2) than before, which changes the exact API path the tool needs to hit.

Frequently Asked Questions

Is this the official Vault MCP server, or a community package?
Official. hashicorp/vault-mcp-server is published and maintained by HashiCorp on GitHub, with the deployment guide living at developer.hashicorp.com/vault/docs/ai/mcp-server/deploy. It is not a third-party wrapper around the Vault API.

Does the MCP server need its own Vault policy, or does it use my personal permissions?
It uses whatever VAULT_TOKEN you configure — there's no separate MCP-specific permission layer. Create a dedicated policy and token scoped to only the paths and PKI mounts you want the agent touching, rather than reusing your personal admin token.

Can this server unseal Vault or manage auth methods?
No. The documented tool set covers KV secrets (read/write/list/delete) and PKI (issuers, roles, certificate issuance) plus mount management. Unsealing, auth method configuration, and root token operations aren't in the tool list — you still do those through the Vault CLI or UI.

stdio or Streamable HTTP — which should I use in Cursor?
stdio for a single developer against a Vault instance you can already reach — Cursor launches the process per session, nothing stays running when Cursor is closed. Streamable HTTP if you want one server instance shared across a team or sitting behind an internal proxy; it needs a TRANSPORT_PORT and, if exposed beyond localhost, TLS.

Why did HashiCorp's example config not work when I pasted it into Cursor?
HashiCorp's published examples use the servers object with an inputs array — that's VS Code's MCP config schema, including its interactive credential-prompt mechanism. Cursor reads a top-level mcpServers key and has no equivalent prompt-on-connect flow, so values need to be hardcoded in a gitignored file or pulled from your shell environment with ${env:NAME}, as shown in Step 2 and Step 3 above.

Related Guides

Official docs cited