MCP 服务器

Keiko

Enables AI agents to securely use secrets by running commands with environment-injected credentials and sanitizing output to prevent leakage.

README

Keiko

Secure secrets manager for AI agents. Keiko lets AI tools like Claude Code use API tokens, passwords, and credentials without ever seeing the actual values.

The Problem

AI agents need API tokens to do useful work — calling APIs, deploying code, managing infrastructure. But passing secret values through an AI's context window is a security risk: they appear in conversation logs, tool responses, and potentially in training data.

How Keiko Solves It

Keiko uses a proxy pattern. The AI agent tells Keiko what command to run and which secrets it needs, but never sees the secret values themselves:

AI Agent ──► Keiko MCP Server ──► Keiko Backend
                   │                      │
              resolves secrets ◄── HTTPS ──┘
                   │
              spawns: bash -c "your command"
              with secrets as env vars
                   │
              captures output
              sanitizes (redacts leaked values)
                   │
AI Agent ◄── clean output only

The AI says "run this curl command with my API token" — Keiko injects the token as an environment variable, runs the command, scans the output for any leaked values, redacts them, and returns clean output.

Quick Start

1. Deploy the backend

The backend stores secrets encrypted (AES-256-GCM) and serves them over HTTPS. Deploy with Docker to any platform with persistent storage:

# Generate an encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Deploy (Railway, Render, Fly, Docker Compose, etc.)
# See docs/setup-guide.md for full instructions

2. Set up the MCP server

The MCP server runs on each machine that needs access to secrets. It's a standalone package with only 2 dependencies — no native compilation needed.

cd packages/mcp
npm install
npm run build
node dist/index.js --store-token YOUR_TOKEN

3. Connect to Claude Code

Add to ~/.mcp.json:

{
  "mcpServers": {
    "keiko": {
      "command": "node",
      "args": ["/absolute/path/to/keiko/packages/mcp/dist/index.js"],
      "env": {
        "KEIKO_URL": "https://your-keiko-backend.example.com"
      }
    }
  }
}

Restart Claude Code. Ask "Check Keiko session status" to verify.

How the AI Uses It

Once connected, the AI discovers available secrets and uses them in commands — without ever seeing the values:

AI: list_secrets
→ my_api_token [Bearer token in Authorization header]

AI: run_with_secrets
   command: curl -s -H "Authorization: Bearer $API_TOKEN" https://api.example.com/data
   secrets: [{env: "API_TOKEN", name: "my_api_token"}]
→ {"data": [...]}  (secret values redacted from output)

Each secret includes auth_pattern and auth_instructions metadata, so the AI knows how to use it without external documentation.

MCP Tools

Tool	Purpose
`run_with_secrets`	Run a command with secrets injected as env vars
`list_secrets`	Discover available secrets (names and auth patterns only)
`session_status`	Check authentication state
`lock`	Kill switch — revoke all active sessions
`set_ttl`	Configure session expiry (0.5–24 hours)
`add_secret`	Create a new secret
`update_secret`	Replace an existing secret's value
`get_guide`	Fetch the usage guide

Security

Encryption at rest — AES-256-GCM with per-secret random IV, plus versioned keys (ENCRYPTION_KEY, ENCRYPTION_KEY_V2, …) and an in-place rotation endpoint so the key can be rotated without downtime
Hashed auth tokens — 64-char hex tokens, SHA-256 hashed in the database, plaintext shown once
Token scoping — each token is restricted to a set of secret-name glob patterns (e.g. railway_*), so a leaked token only exposes the slice of the vault it actually needs
Output sanitization — command output scanned for secret values in raw, base64, base64url, URL-encoded, hex, JSON-string-escaped, and HTML-entity-escaped forms
Per-token rate limit — independent of per-IP, caps abuse from a single token routed through multiple IPs
CSRF protection — X-CSRF-Token header required on every mutating admin-UI endpoint
Session management — configurable TTL, auto-refresh, global kill switch
Audit trail — every action logged with token ID, session ID, IP, and timestamp

Secret values never appear in AI tool responses, conversation logs, or on disk on client machines. See GET /api/guide for the full threat model — what the proxy pattern does and does not prevent.

Architecture

keiko/
├── packages/mcp/          # MCP server (runs on your machine)
│   ├── src/
│   │   ├── server.ts       #   7 tool registrations
│   │   ├── client.ts       #   HTTPS client to backend
│   │   ├── executor.ts     #   Shell spawner + env var injection
│   │   ├── sanitizer.ts    #   Output redaction
│   │   └── keychain.ts     #   OS keychain (Win/Mac/Linux)
│   └── package.json        #   2 deps: @modelcontextprotocol/sdk + zod
│
├── src/                    # Backend API (runs on your server)
│   ├── api/                #   Express routes, auth, crypto
│   └── ui/                 #   EJS admin templates
│
└── Dockerfile              # Multi-stage production build

The MCP server and backend are fully independent packages. The MCP server has zero native dependencies — npm install works everywhere without compilers or --ignore-scripts.

Platform Support

Environment	Token Storage	Notes
Windows	Windows Credential Manager	Commands run via Git Bash (not WSL)
macOS	macOS Keychain	System bash
Linux	libsecret	Requires `secret-tool`
Docker / CI	`KEIKO_TOKEN` env var	No keychain needed