# vouchlyai/pincer-mcp architecture

> Architecture diagram of the GitHub repository vouchlyai/pincer-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vouchlyai/pincer-mcp
- Repository: https://github.com/vouchlyai/pincer-mcp

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client"
        Agent["External Agent (MCP Client)"]:::infra
    end

    subgraph "Pincer Gateway Process"
        subgraph "Entry Layer"
            CLI["CLI"]:::core
            API["JSON-RPC Server"]:::core
        end
        Pincer["Core Orchestration"]:::core

        subgraph "Security Layer"
            Gatekeeper["Gatekeeper"]:::security
            Validator["Schema Validator"]:::security
        end

        subgraph "Vault Layer"
            Keychain["OS Keychain"]:::infra
            SQLite["Encrypted SQLite\n(~/.pincer/vault.db)"]:::infra
            Store["Vault Store"]:::vault
            Injector["Injector"]:::vault
            VaultCLI["Vault CLI"]:::vault
        end

        subgraph "Callers"
            Registry["Caller Registry"]:::callers
            OpenAI["openai.ts"]:::callers
            OpenAIComp["openai-compatible.ts"]:::callers
            Claude["claude.ts"]:::callers
            Gemini["gemini.ts"]:::callers
            OpenRouter["openrouter.ts"]:::callers
            OpenWebUI["openwebui.ts"]:::callers
            BaseCaller["base.ts"]:::callers
        end

        Scrubber["Scrubber"]:::core
        Audit["Audit Logger"]:::audit
        AuditLog["Audit Log\n(~/.pincer/audit.jsonl)"]:::infra
    end

    subgraph "External Services"
        LLMApis["External LLM APIs"]:::infra
    end

    Agent -->|tools/call + proxy_token| CLI
    Agent -->|tools/call + proxy_token| API
    CLI --> Pincer
    API --> Pincer
    Pincer --> Gatekeeper
    Gatekeeper --> Validator
    Gatekeeper -->|resolve token| Store
    Store --> Keychain
    Store --> SQLite
    Keychain <--> SQLite
    Store --> Injector
    Injector --> Registry
    Registry --> OpenAI
    Registry --> OpenAIComp
    Registry --> Claude
    Registry --> Gemini
    Registry --> OpenRouter
    Registry --> OpenWebUI
    Registry --> BaseCaller
    OpenAI -->|API call| LLMApis
    OpenAIComp -->|API call| LLMApis
    Claude -->|API call| LLMApis
    Gemini -->|API call| LLMApis
    OpenRouter -->|API call| LLMApis
    OpenWebUI -->|API call| LLMApis
    BaseCaller -->|API call| LLMApis
    LLMApis --> Injector
    Injector --> Scrubber
    Scrubber --> Audit
    Audit --> AuditLog

    click CLI "https://github.com/vouchlyai/pincer-mcp/blob/main/src/cli.ts"
    click API "https://github.com/vouchlyai/pincer-mcp/blob/main/src/index.ts"
    click Pincer "https://github.com/vouchlyai/pincer-mcp/blob/main/src/pincer.ts"
    click Gatekeeper "https://github.com/vouchlyai/pincer-mcp/blob/main/src/security/gatekeeper.ts"
    click Validator "https://github.com/vouchlyai/pincer-mcp/blob/main/src/security/validator.ts"
    click Store "https://github.com/vouchlyai/pincer-mcp/blob/main/src/vault/store.ts"
    click Injector "https://github.com/vouchlyai/pincer-mcp/blob/main/src/vault/injector.ts"
    click VaultCLI "https://github.com/vouchlyai/pincer-mcp/blob/main/src/vault/cli.ts"
    click Registry "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/registry.ts"
    click OpenAI "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/openai.ts"
    click OpenAIComp "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/openai-compatible.ts"
    click Claude "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/claude.ts"
    click Gemini "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/gemini.ts"
    click OpenRouter "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/openrouter.ts"
    click OpenWebUI "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/openwebui.ts"
    click BaseCaller "https://github.com/vouchlyai/pincer-mcp/blob/main/src/callers/base.ts"
    click Audit "https://github.com/vouchlyai/pincer-mcp/blob/main/src/audit/logger.ts"

    classDef core fill:#d3c0ff,stroke:#8884ff;
    classDef security fill:#a0c4ff,stroke:#3366ff;
    classDef vault fill:#caffbf,stroke:#33aa00;
    classDef callers fill:#ffad60,stroke:#ff7700;
    classDef infra fill:#cccccc,stroke:#666666;
    classDef audit fill:#ffb3c1,stroke:#ff3333;
```
