Pincer MCP

🚀 Pincer MCP 🦀

Pincer-MCP is a security-hardened Model Context Protocol (MCP) gateway. It eliminates the "Lethal Trifecta" vulnerability in agentic AI systems. By acting as a stateless intermediary, it ensures agents never see your real API keys.

🚀 Quick Start

Prerequisites

• Node.js 18+
• macOS, Windows, or Linux with native keychain support

Installation

Option 1: Global Installation (Recommended)

npm install -g pincer-mcp
# Now 'pincer' command is available system-wide

Option 2: Local Development

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

# 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:

# 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

npm run dev

Configure Your Agent

Give your agent the proxy token (not the real API key):

export PINCER_PROXY_TOKEN="pxr_V1StGXR8_Z5jdHi6B-myT"

✨ Features

Pincer-MCP offers a range of features to enhance the security and functionality of AI systems:

• Eliminates Vulnerabilities: Eliminates the "Lethal Trifecta" vulnerability in agentic AI systems.
• Proxy Token Architecture: Implements a "blindfold" security model where agents only know proxy tokens, and Pincer maps them to real API keys.
• Multiple Tools Support: Provides a variety of tools for different AI models and services, including Google Gemini, OpenAI, Anthropic Claude, and more.
• GPG Key Management: Allows for secure GPG key generation, import, listing, export, and authorization.
• Multi-Key Support: Enables storing multiple keys for the same tool and assigning them to different agents.
• Enterprise-Grade Security: Built with hardware-backed cryptography, proxy token isolation, JIT decryption, zero-footprint memory, fine-grained authorization, tamper-evident audit logs, and hardened execution.
• Audit Logging: Logs every tool call with UTC and local timestamps, character counts, and estimated token usage.

📦 Installation

The installation process has been covered in the "Quick Start" section. You can choose between global installation and local development.

💻 Usage Examples

Basic Usage

Your agent sends requests with the proxy token in the body:

{
  "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.

Advanced Usage

Here is an example of using GPG key management:

# 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 <key-id>

# Authorize an agent for signing
pincer agent authorize mybot gpg_sign_data --key <key-id>

📚 Documentation

• Setup Guide - Getting started with Pincer-MCP
• IDE Integration - Use Pincer with VSCode, Claude Desktop, Cursor, and more
• OpenClaw Integration - Integrate Pincer with OpenClaw agents
• Testing Guide - Comprehensive test suite documentation
• Capabilities Reference - Full API and feature documentation
• Security Policy - Vulnerability reporting and security best practices
• CHANGELOG - Version history and release notes

🔧 Technical Details

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:

{
  "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

# Install dependencies
npm install

# Run tests
npm test

# Run with watch mode
npm run dev

# Build for production
npm run build

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

BSL 1.1 (Business Source License) — See LICENSE for details. Converts to Apache 2.0 on 2028-04-01.

• Model Context Protocol - The standard for AI tool integration.
• keytar - Secure cross-platform keychain access.
• better-sqlite3 - High-performance local persistence.

Built with ❤️ for a more secure AI future.