GhostShell

MCP-native credential vault — AI agents authenticate without holding secrets.

npm version npm downloads CI License: MIT Node.js

What is GhostKey?

GhostKey is an MCP server that manages credentials on behalf of AI agents. Agents never see raw secrets — they call MCP tools like ghostkey_request or ghostkey_connect, and GhostKey injects the right authentication transparently.

• Zero secret exposure — agents authenticate without holding API keys, passwords, or tokens
• 7 auth patterns — bearer, basic, API key header, custom header, XML-RPC, OAuth2, query parameter
• Persistent connections — managed PostgreSQL and XML-RPC/Odoo sessions
• Works with any MCP client — Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, and more

Tiers

Feature	Local (Free)	Cloud Backup (Free)	Pro ($10/mo)	Enterprise
Encrypted local vault	✓	✓	✓	✓
MCP stdio transport	✓	✓	✓	✓
Midnight cloud backup	—	✓	✓	✓
HTTP relay (remote agents)	—	—	✓	✓
Included ops/month	—	—	5,000	Unlimited
Cardano NFT ownership	—	—	✓	✓
Own wallet mode	—	—	✓	✓
Self-hosted proof server	—	—	—	✓
SSO / RBAC	—	—	—	✓

Install

npm install -g ghostkey

Or run without installing:

npx ghostkey

Quick Start

# 1. Create a vault
ghostkey init

# 2. Register a credential
ghostkey register --id stripe --type bearer --base-url https://api.stripe.com

# 3. Configure your AI client
ghostkey setup

# 4. Agents use MCP tools — no secrets exposed
#    ghostkey_request { credential_id: "stripe", method: "GET", url: "/v1/charges" }

MCP Client Configuration

Add GhostKey to your MCP client config:

{
  "mcpServers": {
    "ghostkey": {
      "command": "npx",
      "args": ["-y", "ghostkey"]
    }
  }
}

Config file locations:

Client	Config Path
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	~/.claude.json
Cursor	.cursor/mcp.json in your project
VS Code (Copilot)	.vscode/mcp.json in your project

MCP Tools

Tool	Description
ghostkey_list	List stored credentials, optionally filtered by tag, scope, or description
ghostkey_status	System status or detailed credential info with expiry warnings
ghostkey_request	Authenticated HTTP request using a stored credential
ghostkey_connect	Open a persistent connection (PostgreSQL or XML-RPC/Odoo)
ghostkey_query	Execute a query on an existing managed connection

Auth Patterns

Type	Use Case
bearer	REST APIs with Bearer tokens (Stripe, GitHub, etc.)
basic	HTTP Basic authentication (username:password)
api_key_header	APIs that use a custom header for the key (e.g., X-API-Key)
custom_header	Arbitrary header with a {{secret}} template
xmlrpc	XML-RPC services (Odoo execute_kw pattern)
oauth2	OAuth2 client credentials with automatic token refresh
query_param	Secret injected as a URL query parameter

Security

GhostKey is designed with defense-in-depth:

• Argon2id key derivation (password to 256-bit AES key)
• AES-256-GCM authenticated encryption for all stored credentials
• SSRF prevention — domain whitelisting per credential, private IP blocking
• CRLF injection — rejected in all header values
• Error sanitization — credentials never leak in error messages or MCP responses
• Buffer zeroing — best-effort secret wipe on shutdown
• File permissions — vault directory 700, credential file 600

Privacy

• No telemetry — GhostKey collects zero usage data
• No network calls — in local vault mode, nothing leaves your machine
• No cloud dependency — works fully offline with local vault storage
• Credentials never logged — secrets are excluded from all error messages, MCP responses, and debug output
• Your vault, your data — vault files are standard AES-256-GCM encrypted files on your filesystem

CLI Reference

Command	Description
ghostkey init	Create a new credential vault
ghostkey register	Add a new credential to the vault
ghostkey list	List credential metadata
ghostkey status	Show vault health status
ghostkey rotate	Update a credential secret
ghostkey revoke	Deactivate a credential
ghostkey start	Launch MCP server with stdio transport
ghostkey setup	Configure LLM clients to use GhostKey

Supported Clients

GhostKey auto-detects and configures itself for these MCP clients:

Client	Auto-Setup	Transport
Claude Desktop	ghostkey setup	stdio
Claude Code	ghostkey setup	stdio
Cursor	ghostkey setup	stdio
VS Code (Copilot)	ghostkey setup	stdio
Windsurf	ghostkey setup	stdio
Gemini CLI	Manual	stdio
Continue	Manual	stdio
Custom	Manual	stdio/SSE

License

MIT. Copyright (c) 2026 Loomworks Solutions LLC. See LICENSE.