MCP Integration

Connect Claude Code, Cursor, Codex, and VS Code to the Agent Vault MCP server to resolve secrets natively as tool calls.

Coming Soon — the Agent Vault is not yet generally available. This documentation describes the feature ahead of its release; details may change before launch.

The Agent Vault MCP server is the primary way to connect an agent. It's a standard Model Context Protocol server reachable over HTTP, so any MCP-aware client can add it the same way it adds any other remote MCP server.

Server URL: https://secretstash.cloud/api/v1/mcp/agent-vault
Transport: streamable HTTP
Auth: Authorization: Bearer <YOUR_AGENT_API_KEY> header, using the API key generated for this agent in Getting Started

The URL includes the v1 version segment. This is the canonical, supported path — always prefer it over the unversioned fallback described in the REST API reference.

Every client below points at the same server; only the configuration surface differs.

Claude Code

Add the server with the claude mcp add command, using the HTTP transport and passing your agent's token as a header:

claude mcp add --transport http agent-vault \
  https://secretstash.cloud/api/v1/mcp/agent-vault \
  --header "Authorization: Bearer <YOUR_AGENT_API_KEY>"

Verify it connected:

claude mcp list

agent-vault should show as connected. Claude Code can now call resolve_secret, list_available_secrets, and test_connection on your behalf whenever it needs a credential.

Cursor

Add the server to your global ~/.cursor/mcp.json (or a project-local .cursor/mcp.json):

{
  "mcpServers": {
    "agent-vault": {
      "type": "http",
      "url": "https://secretstash.cloud/api/v1/mcp/agent-vault",
      "headers": {
        "Authorization": "Bearer <YOUR_AGENT_API_KEY>"
      }
    }
  }
}

This is the exact snippet shown on each agent's page in the SecretStash UI, under Setup snippet → MCP — copy it directly from there to avoid retyping the URL or token.

Reload Cursor (or reopen the workspace) and confirm agent-vault appears under Settings → MCP as connected.

Codex

Add the server to your ~/.codex/config.toml:

[mcp_servers.agent-vault]
url = "https://secretstash.cloud/api/v1/mcp/agent-vault"
bearer_token = "<YOUR_AGENT_API_KEY>"

Codex's MCP configuration schema has changed across versions. If your Codex CLI doesn't recognize url / bearer_token for a remote server, check codex mcp --help for the syntax your version expects — the server URL and Bearer token above stay the same regardless.

Run codex mcp list to confirm agent-vault is registered before starting a session.

VS Code

Add the server to your workspace's .vscode/mcp.json (or your user mcp.json for a global setup):

{
  "servers": {
    "agent-vault": {
      "type": "http",
      "url": "https://secretstash.cloud/api/v1/mcp/agent-vault",
      "headers": {
        "Authorization": "Bearer <YOUR_AGENT_API_KEY>"
      }
    }
  }
}

VS Code will prompt to start the server the first time it's referenced — accept the prompt, then check the MCP: List Servers command to confirm agent-vault is running.

Available tools and resources

Once connected, every client above sees the same three tools and one resource:

Name	Kind	Description
`resolve_secret`	Tool	Resolve `variable` (and optionally `environment`) to its plaintext value, scoped to the agent's authorized environments.
`list_available_secrets`	Tool	List the variable names and environment slugs this agent may resolve. Metadata only — no values.
`test_connection`	Tool	Run the same diagnostic checklist as the Test connection button in the web app.
`secret://{environment}/{variable}`	Resource	Read a specific secret by URI template; returns the decrypted plaintext as the resource content.

Secrets outside an agent's authorized environments are never returned by any tool or resource — you'll get an error, not an empty value, if you ask for one out of scope.

Placeholder convention

Never paste a real credential into a prompt, config file, or log. Reference it with a placeholder of the form __SECRETSTASH_<VARIABLE_NAME>__ instead, for example __SECRETSTASH_GITHUB_PROD_TOKEN__. Being connected to the MCP server doesn't teach the agent this syntax on its own, so tell it in your prompt or project instructions to resolve __SECRETSTASH_*__ placeholders through resolve_secret (or the REST API) — see the worked example. Once instructed, the agent resolves the value at the moment it needs it, so only the placeholder is ever committed, logged, or left in a transcript.

Your agent's own Bearer token is the one value that must live in client configuration. Store it in an environment variable or your client's secret store where supported (note that pasting the token into a command such as claude mcp add records it in your shell history — clear that entry, or add the server by editing its config file instead), and revoke it from the agent's page if it leaks — see Verification & Operations for revocation and the audit trail.

Next steps

Prefer a plain HTTP call instead? See the REST API reference.
Walk through a full worked example using resolve_secret to make a real authenticated API call.

Getting Started

Create your first agent, authorize environments, provision its encryption keys, generate its API key, and verify the connection.

REST API

Reference and language examples for the Agent Vault REST API — the fallback surface for any agent that isn't MCP-aware.

On This Page

Claude Code
Cursor
Codex
VS Code
Available tools and resources
Placeholder convention
Next steps

Star the CLI on GitHub Report an issue