Connect to Claude Desktop
Give Claude Desktop access to your secret vault via the Model Context Protocol. Claude can retrieve API keys, store new credentials, and manage your secrets through conversation.
Prerequisites
You need Claude Desktop installed (version 0.7 or later) and an Agent Secret Store account with at least one secret stored. Node.js 18+ must be available on your system for the npx transport.
- 1
Get your agent API key
Log in to the Agent Secret Store dashboard and navigate to Agents. Either copy your existing agent key or create a new dedicated agent for Claude Desktop.
Your agent key looks like:
ass_xxxxxxxxxxxxxxxxxxxxxxxx - 2
Find your Claude Desktop config file
The config file location depends on your operating system:
macOS
Shell~/Library/Application Support/Claude/claude_desktop_config.jsonWindows
Shell%APPDATA%\Claude\claude_desktop_config.json # Typically: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.jsonLinux
Shell~/.config/Claude/claude_desktop_config.jsonIf the file doesn't exist, create it (including parent directories).
- 3
Add the MCP server configuration
Open the config file and add the Agent Secret Store MCP server. Replace
ass_your_agent_key_herewith your actual agent key:New config file (no existing MCP servers)
claude_desktop_config.json{ "mcpServers": { "agent-secret-store": { "command": "npx", "args": ["-y", "@agentsecretstore/mcp"], "env": { "ASS_AGENT_KEY": "ass_your_agent_key_here" } } } }Existing config file (add alongside other servers)
claude_desktop_config.json{ "mcpServers": { "some-other-mcp-server": { "command": "npx", "args": ["-y", "some-other-package"] }, "agent-secret-store": { "command": "npx", "args": ["-y", "@agentsecretstore/mcp"], "env": { "ASS_AGENT_KEY": "ass_your_agent_key_here" } } } }Don't commit this file
The config file contains your agent API key in plaintext. Don't commit it to source control, share it, or sync it to cloud storage without first removing the key.
- 4
Restart Claude Desktop
Fully quit Claude Desktop (not just close the window — use File → Quit or ⌘Q on macOS) and reopen it. The MCP server starts alongside Claude Desktop and connects automatically.
- 5
Test the connection
Start a new conversation and ask Claude to access your vault:
TextYou: "List my Agent Secret Store secrets" Claude: I can see your vault through the Agent Secret Store MCP connection. Here are your secrets in the production namespace: • production/gemini/GEMINI_API_KEY (sensitive, v3) • production/stripe/STRIPE_SECRET_KEY (critical, v1) • production/database/DATABASE_URL (standard, v2) Would you like me to retrieve any of these values?You should see Claude call the
list_secretstool and display your vault contents. A hammer icon in the message indicates tool use.
Create a dedicated scoped agent (recommended)
Rather than using your master agent key, create a dedicated agent for Claude Desktop with only read access. This limits blast radius if the key is exposed:
# Create a dedicated agent for Claude Desktop with read-only scopes
ass agents create \
--name "claude-desktop" \
--description "Claude Desktop MCP access" \
--scopes "secrets:read:production/*"
# Use the returned API key in your claude_desktop_config.jsonTroubleshooting
❓ Claude doesn't show the Agent Secret Store tools
Verify the JSON config is valid (no trailing commas, correct quotes). Restart Claude Desktop completely. Check that Node.js is installed and accessible from your terminal.
❓ Authentication error when asking Claude to list secrets
Double-check your agent key in the config file. The key must start with ass_ and have no extra spaces or quotes around it.
❓ Tools visible but secrets not found
Confirm you have secrets stored in the vault — log in to the dashboard to verify. Check the namespace in your request matches where secrets are stored.
❓ npx hangs on first run
The first run downloads the MCP package. This can take 10-30 seconds on a slow connection. Subsequent starts are fast since npx caches the package.
Check logs
# macOS — view Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp-agent-secret-store.log
# Windows
Get-Content "$env:APPDATA\Claude\Logs\mcp-agent-secret-store.log" -WaitTest the MCP server directly
# Start the MCP server with SSE transport for a local smoke test
ASS_AGENT_KEY=ass_your_key npx -y @agentsecretstore/mcp --transport sse --port 3100
# In another terminal:
curl http://localhost:3100/health
# {"status":"ok","version":"1.0.0"}