phantom-secrets-mcp

Phantom Secrets MCP Server

MCP server for AI-safe secrets management. Lets Claude Code, Cursor, Windsurf, and Codex manage API keys without ever seeing real values.

Part of Phantom Secrets -- the CLI that replaces real secrets with inert phm_ tokens so AI agents never see your API keys.

Install

Claude Code

claude mcp add phantom-secrets-mcp -- npx phantom-secrets-mcp

Cursor

Add to Cursor Settings > Features > MCP Servers:

• Name: phantom
• Command: npx phantom-secrets-mcp

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "phantom": {
    "command": "npx",
    "args": ["phantom-secrets-mcp"]
  }
}

Codex / Other MCP Clients

Add to your MCP configuration:

{
  "phantom": {
    "command": "npx",
    "args": ["phantom-secrets-mcp"]
  }
}

Works with any tool that supports the Model Context Protocol.

25 MCP Tools

Read-only tools (safe to call anytime):

Tool	Description
phantom_list_secrets	List secret names in the vault (never exposes values)
phantom_status	Check project configuration, vault health, and proxy state
phantom_doctor	Diagnose configuration and vault health
phantom_why	Explain why a key is or is not protected
phantom_check	Scan for unprotected secrets (pre-commit-style)
phantom_env	List environment variables with protection status (no values)
phantom_sync	Preview deployment-platform sync (Vercel, Railway)
phantom_cloud_status	Check cloud authentication and sync status

Mutating tools (modify vault or .env):

Tool	Description
phantom_init	Protect secrets in .env files -- store in vault, rewrite with phantom tokens
phantom_add_secret_interactive	Start a terminal prompt for adding a secret without passing the value through MCP
phantom_remove_secret	Remove a secret from the vault
phantom_rotate	Regenerate all phantom tokens (invalidates old ones)
phantom_copy_secret	Copy a secret from this project to another project's vault
phantom_wrap	Wrap a plaintext .env value into a vaulted phm_ token
phantom_unwrap	Reverse a wrap (restore plaintext to .env from vault)
phantom_cloud_push	Push encrypted vault to Phantom Cloud (E2E encrypted)
phantom_cloud_pull	Pull and decrypt vault from Phantom Cloud

Team vault tools (Pro plan; multi-developer shared vaults):

Tool	Description
phantom_team_list	List teams the user belongs to (read-only)
phantom_team_create	Create a new team. Caller becomes owner
phantom_team_members	List members of a team (read-only)
phantom_team_invite	Invite someone to a team by GitHub username
phantom_team_key_publish	Register the caller's X25519 public key on a team
phantom_team_vault_push	Push the current project's vault to a team (envelope-encrypted to every registered member)
phantom_team_vault_pull	Pull the team vault into the local vault

All tools are read-safe: they never return actual secret values, and real secret values are never accepted as MCP tool arguments. The AI can manage your secrets lifecycle (add, remove, rotate, sync, share with teams) without key exposure in agent context. Mutating tools require confirm: true.

How It Works

• The MCP server runs as a stdio transport process alongside your AI coding tool
• When the AI needs to manage secrets, it calls Phantom MCP tools
• Phantom stores real secrets in the OS keychain (macOS Keychain, Linux Secret Service) or encrypted file vault
• The AI only ever sees phm_ phantom tokens -- never real API keys
• A local reverse proxy swaps tokens back at the network layer when making API calls

Requirements

• Phantom Secrets CLI must be initialized in your project (npx phantom-secrets init)
• Node.js >= 16
• macOS (arm64/x64) or Linux (x64/arm64)

Cloud Sync

The MCP server includes cloud push/pull tools for syncing vaults across machines:

AI: "Push this project's secrets to the cloud"
-> phantom_cloud_push (E2E encrypted with ChaCha20-Poly1305, Argon2id key derivation)

AI: "Pull secrets from the cloud to this machine"
-> phantom_cloud_pull (decrypted locally, server never sees plaintext)

Requires phantom login (GitHub OAuth) via the CLI first.

Links

• Phantom Secrets CLI
• GitHub
• phm.dev -- Cloud dashboard
• Security Model

License

MIT