\n\n[](LICENSE)\n[](https://www.typescriptlang.org/)\n[](https://modelcontextprotocol.io)\n[](https://www.npmjs.com/package/pincer-mcp)\n[](https://www.npmjs.com/package/pincer-mcp)\n[](https://registry.modelcontextprotocol.io/?q=io.github.VouchlyAI%2Fpincer)\n\nPincer-MCP is a security-hardened Model Context Protocol (MCP) gateway that eliminates the \"Lethal Trifecta\" vulnerability in agentic AI systems. By acting as a stateless intermediary, Pincer ensures agents **never see your real API keys**.\n\n## ๐ The Problem\n\nCurrent AI agents store long-lived API keys in plain-text `.env` files or local databases. If compromised via prompt injection or host intrusion, attackers gain direct access to your:\n- Database passwords\n- Third-party API keys\n\n## โจ The Solution: Proxy Token Architecture\n\nPincer implements a **\"blindfold\" security model**:\n\n1. **Agent knows**: Only a unique proxy token (`pxr_abc123...`)\n2. **Pincer knows**: Mapping of proxy tokens โ real API keys (encrypted in OS keychain)\n3. **Agent never sees**: The actual credentials\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Pincer\n participant Vault (OS Keychain)\n participant External API\n\n Agent->>Pincer: tools/call + proxy_token: pxr_abc123\n Pincer->>Vault: Decrypt real API key\n Vault-->>Pincer: gemini_api_key: AIzaSy...\n Pincer->>External API: API call with real key\n External API-->>Pincer: Response\n Pincer->>Pincer: Scrub key from memory\n Pincer-->>Agent: Response (no credentials)\n```\n## ๐ฆ Available Tools\n\n- `gemini_generate`: Secure Google Gemini API calls.\n- `openai_chat`: Chat completions with OpenAI GPT models (gpt-4o, gpt-4-turbo, gpt-3.5-turbo, etc.).\n- `openai_list_models`: List all available OpenAI models.\n- `openai_compatible_chat`: Chat completions with **any** OpenAI-compatible API (Azure OpenAI, Ollama, vLLM, etc.).\n- `openai_compatible_list_models`: List models from custom OpenAI-compatible endpoints.\n- `claude_chat`: Chat completions with Anthropic Claude models (Claude 3.5 Sonnet, Opus, Haiku).\n- `openrouter_chat`: Unified API access to 100+ models from multiple providers (OpenAI, Anthropic, Google, Meta, etc.).\n- `openrouter_list_models`: List all available models across OpenRouter providers.\n- `openwebui_chat`: OpenAI-compatible interface for self-hosted LLMs.\n- `openwebui_list_models`: Discover available models on an OpenWebUI instance.\n- `gpg_sign_data`: Sign data or files using a GPG/PGP private key stored in Pincer's vault. *(Keyless Execution โ agent never sees the key)*\n- `gpg_decrypt`: Decrypt PGP-encrypted data using a vault-stored private key.\n\n### ๐ GPG Key Management\n\n```bash\n# Generate a new GPG keypair (private key stored in vault)\npincer key generate --name \"Release Signing\" --email dev@example.com\n\n# Import an existing PGP private key\npincer key import ./my-key.asc --passphrase \"my-passphrase\"\n\n# List all stored GPG keys\npincer key list\n\n# Export public key (safe to share)\npincer key export \n\n# Authorize an agent for signing\npincer agent authorize mybot gpg_sign_data --key \n```\n\n*(More callers coming soon!)*\n\n## ๐ Quick Start\n\n### Prerequisites\n\n- Node.js 18+ \n- macOS, Windows, or Linux with native keychain support\n\n### Installation\n\n**Option 1: Global Installation (Recommended)**\n```bash\nnpm install -g pincer-mcp\n# Now 'pincer' command is available system-wide\n```\n\n**Option 2: Local Development**\n```bash\ngit clone https://github.com/VouchlyAI/Pincer-MCP.git\ncd Pincer-MCP\nnpm install\nnpm run build\nnpm link # Makes 'pincer' command available locally\n```\n\n### Setup Vault\n\n```bash\n# 1. Initialize vault (creates master key in OS keychain)\npincer init\n\n# 2. Store your real API keys (encrypted)\npincer set gemini_api_key \"AIzaSyDpxPq...\"\npincer set openai_api_key \"sk-proj-...\"\n\n# 3. Register an agent and generate proxy token\npincer agent add openclaw\n# Output: ๐ซ Proxy Token: pxr_V1StGXR8_Z5jdHi6B-myT\n\n# 4. Authorize the agent for specific tools\npincer agent authorize openclaw gemini_generate\n```\n\n### Multi-Key Support\n\nStore multiple keys for the same tool and assign them to different agents:\n\n```bash\n# Store two different Gemini API keys\npincer set gemini_api_key \"AIzaSy_KEY_FOR_CLAWDBOT...\" --label key1\npincer set gemini_api_key \"AIzaSy_KEY_FOR_MYBOT...\" --label key2\n\n# View all stored keys\npincer list\n\n# Assign specific keys to each agent\npincer agent add clawdbot\npincer agent authorize clawdbot gemini_generate --key key1\n\npincer agent add mybot \npincer agent authorize mybot gemini_generate --key key2\n\n# View agent permissions\npincer agent list\n```\n\n**Result:** `clawdbot` uses key1, `mybot` uses key2 - perfect for rate limiting or cost tracking!\n\n### Run the Server\n\n```bash\nnpm run dev\n```\n\n### Configure Your Agent\n\nGive your agent the **proxy token** (not the real API key):\n\n```bash\nexport PINCER_PROXY_TOKEN=\"pxr_V1StGXR8_Z5jdHi6B-myT\"\n```\n\n## Tool-to-Secret Name Mappings\n\nWhen storing secrets, you must use the correct secret name for each tool. See the **[Tool Mappings Guide](docs/TOOL_MAPPINGS.md)** for a complete reference.\n\nWhen you run `pincer agent authorize myagent gemini_generate`, Pincer will inject the `gemini_api_key` secret when that tool is called.\n\n### Make a Tool Call\n\nYour agent sends requests with the proxy token in the body:\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"gemini_generate\",\n \"arguments\": {\n \"prompt\": \"Hello world\",\n \"model\": \"gemini-2.0-flash\"\n },\n \"_meta\": {\n \"pincer_token\": \"pxr_V1StGXR8_Z5jdHi6B-myT\"\n }\n }\n}\n```\n\nPincer maps the proxy token to the real API key and executes the call securely.\n\n## ๐๏ธ Architecture\n\n### Two-Tiered Vault System\n\n**Tier 1: Master Key (OS Keychain)**\n- Stored in macOS Keychain, Windows Credential Manager, or GNOME Keyring\n- Never touches the filesystem\n- Accessed only for encryption/decryption\n\n**Tier 2: Encrypted Store (SQLite)**\n- Database at `~/.pincer/vault.db`\n- Three tables:\n - `secrets`: Real API keys (AES-256-GCM encrypted)\n - `proxy_tokens`: Proxy token โ Agent ID mappings\n - `agent_mappings`: Agent ID โ Tool authorization\n\n### Authentication Flow\n\n```\nRequest (_meta.pincer_token: pxr_xxx)\n โ\nGatekeeper: Extract proxy token from body\n โ\nVault: Resolve pxr_xxx โ agent_id โ tool_name โ real_api_key\n โ\nInjector: JIT decrypt & inject real key\n โ\nCaller: Execute external API call\n โ\nScrubber: Overwrite key in memory with zeros\n โ\nAudit: Log to tamper-evident chain\n```\n\n## ๐ Security & Compliance\n\nPincer is built for enterprise-grade security:\n\n- **Hardware-Backed Cryptography**: Master encryption keys never leave the OS-native keychain.\n- **Proxy Token Isolation**: Agents only handle ephemeral `pxr_` tokens; they never touch real credentials.\n- **JIT Decryption**: Secrets are decrypted only for the duration of the API call.\n- **Zero-Footprint Memory**: Sensitive data is scrubbed (zeroed out) from memory immediately after use.\n- **Fine-Grained Authorization**: Strict per-agent, per-tool access control policies.\n- **Tamper-Evident Audit Log**: Append-only tool call history with SHA-256 chain-hashing.\n- **Hardened Execution**: Schema validation on all inputs and protected environment execution.\n- **Stdio Compatible**: Fully compatible with the standard Model Context Protocol transport.\n\n\n\n## ๐ Audit Logs\n\nEvery tool call is logged to `~/.pincer/audit.jsonl` with both UTC and Local timestamps, plus character counts and estimated token usage:\n\n```json\n{\n \"agentId\": \"openclaw\",\n \"tool\": \"gemini_generate\",\n \"duration\": 234,\n \"status\": \"success\",\n \"input_chars\": 156,\n \"output_chars\": 423,\n \"estimated_input_tokens\": 39,\n \"estimated_output_tokens\": 106,\n \"timestamp_utc\": \"2026-02-05T08:32:00.000Z\",\n \"timestamp_local\": \"2/5/2026, 2:02:45 PM\",\n \"chainHash\": \"a1b2c3d4e5f6g7h8\",\n \"prevHash\": \"0000000000000000\"\n}\n```\n\n**Token Estimation**: Pincer automatically estimates token usage using a 4:1 character-to-token ratio (~4 characters per token average). This provides consistent cost tracking across all AI providers without relying on provider-specific APIs.\n```\n\nChain hashes provide tamper detection - any modification breaks the SHA-256 chain.\n\n## ๐งช Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run with watch mode\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\n## ๐ Documentation\n\n- **[Setup Guide](docs/SETUP.md)** - Getting started with Pincer-MCP\n- **[IDE Integration](docs/IDE_INTEGRATION.md)** - Use Pincer with VSCode, Claude Desktop, Cursor, and more\n- **[OpenClaw Integration](docs/OPENCLAW_INTEGRATION.md)** - Integrate Pincer with OpenClaw agents\n- **[Testing Guide](docs/TESTING.md)** - Comprehensive test suite documentation\n- **[Capabilities Reference](docs/CAPABILITIES.md)** - Full API and feature documentation\n- **[Security Policy](SECURITY.md)** - Vulnerability reporting and security best practices\n- **[CHANGELOG](CHANGELOG.md)** - Version history and release notes\n\n\n## ๐ค Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## ๐ License\n\nBSL 1.1 (Business Source License) โ See [LICENSE](LICENSE) for details. Converts to Apache 2.0 on 2028-04-01.\n\n- [Model Context Protocol](https://modelcontextprotocol.io) - The standard for AI tool integration.\n- [keytar](https://github.com/atom/node-keytar) - Secure cross-platform keychain access.\n- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - High-performance local persistence.\n\n---\n\n**Built with โค๏ธ for a more secure AI future.**\n",
"bytes": 10426,
"sha": "d2c4b74f50ba413251d23ed73c07c4ea88a6e6ad0801f0f959d087323559fe26",
"repo_slug": "vouchlyai/pincer-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_vouchlyai_pincer_e43f940c/readme"
}
![\"Pincer-MCP\"](\"https://raw.githubusercontent.com/VouchlyAI/Pincer-MCP/refs/heads/main/mascot.png\")
\n