# pincer
**Category:** ๐ฐ Finance & Fintech
**Repository:** https://github.com/VouchlyAI/Pincer-MCP
**npm Downloads (last month):** 21
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/pincer
## Description
Secure grip for your agent's secrets - security-hardened MCP gateway with proxy token architecture
## Claude Desktop Quick Installation
Heuristic fallback โ verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"pincer": {
"command": "npx",
"args": ["-y","pincer"]
}
}
```
## Documentation & README
# Pincer MCP ๐ฆ
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io)
[](https://www.npmjs.com/package/pincer-mcp)
[](https://www.npmjs.com/package/pincer-mcp)
[](https://registry.modelcontextprotocol.io/?q=io.github.VouchlyAI%2Fpincer)
Pincer-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**.
## ๐ The Problem
Current 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:
- Database passwords
- Third-party API keys
## โจ The Solution: Proxy Token Architecture
Pincer implements a **"blindfold" security model**:
1. **Agent knows**: Only a unique proxy token (`pxr_abc123...`)
2. **Pincer knows**: Mapping of proxy tokens โ real API keys (encrypted in OS keychain)
3. **Agent never sees**: The actual credentials
```mermaid
sequenceDiagram
participant Agent
participant Pincer
participant Vault (OS Keychain)
participant External API
Agent->>Pincer: tools/call + proxy_token: pxr_abc123
Pincer->>Vault: Decrypt real API key
Vault-->>Pincer: gemini_api_key: AIzaSy...
Pincer->>External API: API call with real key
External API-->>Pincer: Response
Pincer->>Pincer: Scrub key from memory
Pincer-->>Agent: Response (no credentials)
```
## ๐ฆ Available Tools
- `gemini_generate`: Secure Google Gemini API calls.
- `openai_chat`: Chat completions with OpenAI GPT models (gpt-4o, gpt-4-turbo, gpt-3.5-turbo, etc.).
- `openai_list_models`: List all available OpenAI models.
- `openai_compatible_chat`: Chat completions with **any** OpenAI-compatible API (Azure OpenAI, Ollama, vLLM, etc.).
- `openai_compatible_list_models`: List models from custom OpenAI-compatible endpoints.
- `claude_chat`: Chat completions with Anthropic Claude models (Claude 3.5 Sonnet, Opus, Haiku).
- `openrouter_chat`: Unified API access to 100+ models from multiple providers (OpenAI, Anthropic, Google, Meta, etc.).
- `openrouter_list_models`: List all available models across OpenRouter providers.
- `openwebui_chat`: OpenAI-compatible interface for self-hosted LLMs.
- `openwebui_list_models`: Discover available models on an OpenWebUI instance.
- `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)*
- `gpg_decrypt`: Decrypt PGP-encrypted data using a vault-stored private key.
### ๐ GPG Key Management
```bash
# Generate a new GPG keypair (private key stored in vault)
pincer key generate --name "Release Signing" --email dev@example.com
# Import an existing PGP private key
pincer key import ./my-key.asc --passphrase "my-passphrase"
# List all stored GPG keys
pincer key list
# Export public key (safe to share)
pincer key export
# Authorize an agent for signing
pincer agent authorize mybot gpg_sign_data --key
```
*(More callers coming soon!)*
## ๐ Quick Start
### Prerequisites
- Node.js 18+
- macOS, Windows, or Linux with native keychain support
### Installation
**Option 1: Global Installation (Recommended)**
```bash
npm install -g pincer-mcp
# Now 'pincer' command is available system-wide
```
**Option 2: Local Development**
```bash
git clone https://github.com/VouchlyAI/Pincer-MCP.git
cd Pincer-MCP
npm install
npm run build
npm link # Makes 'pincer' command available locally
```
### Setup Vault
```bash
# 1. Initialize vault (creates master key in OS keychain)
pincer init
# 2. Store your real API keys (encrypted)
pincer set gemini_api_key "AIzaSyDpxPq..."
pincer set openai_api_key "sk-proj-..."
# 3. Register an agent and generate proxy token
pincer agent add openclaw
# Output: ๐ซ Proxy Token: pxr_V1StGXR8_Z5jdHi6B-myT
# 4. Authorize the agent for specific tools
pincer agent authorize openclaw gemini_generate
```
### Multi-Key Support
Store multiple keys for the same tool and assign them to different agents:
```bash
# Store two different Gemini API keys
pincer set gemini_api_key "AIzaSy_KEY_FOR_CLAWDBOT..." --label key1
pincer set gemini_api_key "AIzaSy_KEY_FOR_MYBOT..." --label key2
# View all stored keys
pincer list
# Assign specific keys to each agent
pincer agent add clawdbot
pincer agent authorize clawdbot gemini_generate --key key1
pincer agent add mybot
pincer agent authorize mybot gemini_generate --key key2
# View agent permissions
pincer agent list
```
**Result:** `clawdbot` uses key1, `mybot` uses key2 - perfect for rate limiting or cost tracking!
### Run the Server
```bash
npm run dev
```
### Configure Your Agent
Give your agent the **proxy token** (not the real API key):
```bash
export PINCER_PROXY_TOKEN="pxr_V1StGXR8_Z5jdHi6B-myT"
```
## Tool-to-Secret Name Mappings
When 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.
When you run `pincer agent authorize myagent gemini_generate`, Pincer will inject the `gemini_api_key` secret when that tool is called.
### Make a Tool Call
Your agent sends requests with the proxy token in the body:
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "gemini_generate",
"arguments": {
"prompt": "Hello world",
"model": "gemini-2.0-flash"
},
"_meta": {
"pincer_token": "pxr_V1StGXR8_Z5jdHi6B-myT"
}
}
}
```
Pincer maps the proxy token to the real API key and executes the call securely.
## ๐๏ธ Architecture
### Two-Tiered Vault System
**Tier 1: Master Key (OS Keychain)**
- Stored in macOS Keychain, Windows Credential Manager, or GNOME Keyring
- Never touches the filesystem
- Accessed only for encryption/decryption
**Tier 2: Encrypted Store (SQLite)**
- Database at `~/.pincer/vault.db`
- Three tables:
- `secrets`: Real API keys (AES-256-GCM encrypted)
- `proxy_tokens`: Proxy token โ Agent ID mappings
- `agent_mappings`: Agent ID โ Tool authorization
### Authentication Flow
```
Request (_meta.pincer_token: pxr_xxx)
โ
Gatekeeper: Extract proxy token from body
โ
Vault: Resolve pxr_xxx โ agent_id โ tool_name โ real_api_key
โ
Injector: JIT decrypt & inject real key
โ
Caller: Execute external API call
โ
Scrubber: Overwrite key in memory with zeros
โ
Audit: Log to tamper-evident chain
```
## ๐ Security & Compliance
Pincer is built for enterprise-grade security:
- **Hardware-Backed Cryptography**: Master encryption keys never leave the OS-native keychain.
- **Proxy Token Isolation**: Agents only handle ephemeral `pxr_` tokens; they never touch real credentials.
- **JIT Decryption**: Secrets are decrypted only for the duration of the API call.
- **Zero-Footprint Memory**: Sensitive data is scrubbed (zeroed out) from memory immediately after use.
- **Fine-Grained Authorization**: Strict per-agent, per-tool access control policies.
- **Tamper-Evident Audit Log**: Append-only tool call history with SHA-256 chain-hashing.
- **Hardened Execution**: Schema validation on all inputs and protected environment execution.
- **Stdio Compatible**: Fully compatible with the standard Model Context Protocol transport.
## ๐ Audit Logs
Every tool call is logged to `~/.pincer/audit.jsonl` with both UTC and Local timestamps, plus character counts and estimated token usage:
```json
{
"agentId": "openclaw",
"tool": "gemini_generate",
"duration": 234,
"status": "success",
"input_chars": 156,
"output_chars": 423,
"estimated_input_tokens": 39,
"estimated_output_tokens": 106,
"timestamp_utc": "2026-02-05T08:32:00.000Z",
"timestamp_local": "2/5/2026, 2:02:45 PM",
"chainHash": "a1b2c3d4e5f6g7h8",
"prevHash": "0000000000000000"
}
```
**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.
```
Chain hashes provide tamper detection - any modification breaks the SHA-256 chain.
## ๐งช Development
```bash
# Install dependencies
npm install
# Run tests
npm test
# Run with watch mode
npm run dev
# Build for production
npm run build
```
## ๐ Documentation
- **[Setup Guide](docs/SETUP.md)** - Getting started with Pincer-MCP
- **[IDE Integration](docs/IDE_INTEGRATION.md)** - Use Pincer with VSCode, Claude Desktop, Cursor, and more
- **[OpenClaw Integration](docs/OPENCLAW_INTEGRATION.md)** - Integrate Pincer with OpenClaw agents
- **[Testing Guide](docs/TESTING.md)** - Comprehensive test suite documentation
- **[Capabilities Reference](docs/CAPABILITIES.md)** - Full API and feature documentation
- **[Security Policy](SECURITY.md)** - Vulnerability reporting and security best practices
- **[CHANGELOG](CHANGELOG.md)** - Version history and release notes
## ๐ค Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## ๐ License
BSL 1.1 (Business Source License) โ See [LICENSE](LICENSE) for details. Converts to Apache 2.0 on 2028-04-01.
- [Model Context Protocol](https://modelcontextprotocol.io) - The standard for AI tool integration.
- [keytar](https://github.com/atom/node-keytar) - Secure cross-platform keychain access.
- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - High-performance local persistence.
---
**Built with โค๏ธ for a more secure AI future.**
