How vouchlyai/pincer-mcp works
Project type and purpose
• Pincer-MCP is a Node.js/TypeScript CLI + library that acts as a stateless Model Context Protocol (MCP) gateway.
• Its purpose is to proxy AI agent tool calls using short-lived “proxy tokens,” decrypt & inject real API keys at call-time, scrub them from memory, and audit every call.
File structure
• Top level:
• src/cli.ts → CLI entrypoint (“pincer” command)
• src/index.ts → JSON-RPC server bootstrap (implements MCP transport)
• src/pincer.ts → Core orchestration
• src/audit/logger.ts → Tamper-evident audit chain
• src/security/ → Gatekeeper & validator for token/schema checks
• src/vault/ → Two-tier vault: OS keychain & SQLite store
• src/callers/ → Tool callers (openai.ts, claude.ts, openrouter.ts, etc.) + registry
• Config & scripts: tsconfig.json, vitest.config.ts, package.json
• Docs: architecture, setup, testing, integrations, tool mappings
• Tests: cover server flow, security, multi-key vault
Key insights from README
• Two-tier vault architecture:
• Tier 1: Master key in OS keychain via keytar
• Tier 2: AES-256-GCM encrypted secrets in ~/.pincer/vault.db (SQLite)
• Authentication flow:
1. Gatekeeper extracts proxy token
2. Vault resolves real key
3. Injector decrypts & injects key into caller
4. Caller makes external API request
5. Scrubber zeroes key in memory
6. Audit logger appends chain-hashed entry
• External integrations: OpenAI, Google Gemini, Anthropic Claude, OpenRouter, OpenWebUI, etc.
Main components
A. External Agent (MCP-compliant client)
B. Pincer Gateway Process
1. CLI/API Layer (src/cli.ts + src/index.ts)
2. Gatekeeper (src/security/gatekeeper.ts)
3. Vault
• OS Keychain (keytar)
• Encrypted SQLite (better-sqlite3)
4. Injector (src/vault/injector.ts)
5. Caller Registry + Callers (src/callers/*.ts)
6. Scrubber (in-memory cleanup)
7. Audit Logger (src/audit/logger.ts)
C. External Services
• OS Keychain service
• External LLM APIs/Providers
D. Local Persistence
• ~/.pincer/vault.db (SQLite)
• ~/.pincer/audit.jsonl
Relationships and interactions
• Agent → Pincer CLI/Server (JSON-RPC “tools/call” + proxy_token)
• Gatekeeper ⟵ token extraction & validation
• Gatekeeper → Vault (resolve token → agent_id → tool_name → real_key)
• Vault master key ↔ OS Keychain
• Vault store ↔ SQLite DB
• Injector decrypts real_key & passes to Caller
• Caller → External API (with real_key)
• Caller ← Response → Injector → Scrubber
• Audit Logger writes to local JSONL with SHA-256 chain
• All sensitive data flows are one-way and scrubbed
Architectural patterns & principles
• Layered architecture (Gatekeeper → Vault → Injector → Caller → Audit)
• Defense-in-depth: schema validation, JIT decryption, zero-footprint memory
• Separation of concerns: distinct modules for security, vault, callers, audit
• Immutable audit chain (append-only logs)
• Stateless gateway for horizontal scaling
Technologies & frameworks
• Node.js 18+, TypeScript 5.x
• keytar for OS keychain
• better-sqlite3 for encrypted vault store
• Vitest for testing
Final advice
• Six stages of the auth flow in sequence
• Keep it high-level but include enough detail to understand each responsibility
• Review docs/CAPABILITIES.md and docs/TOOL_MAPPINGS.md for any missing components