@keypost/wrapper

Lightweight Node.js wrapper for local stdio MCP servers with Keypost policy enforcement.

Overview

The Keypost Wrapper enables you to apply Keypost policies to local stdio MCP servers (like filesystem, local databases, system tools) while maintaining low latency and a simple user experience.

How It Works

AI Agent (Claude Desktop, etc.)
    ↓ (spawns keypost-wrapper)
Keypost Wrapper
    ↓ (HTTP) → Keypost Cloud (evaluates request policies)
    ↓ (stdio) → Local MCP Server
    ↓ (HTTP) → Keypost Cloud (evaluates response policies)
    ↓ (stdio) → AI Agent

The wrapper:

1. Receives MCP requests from AI agents via stdin
2. Evaluates request policies via Keypost cloud API
3. Forwards allowed requests to local stdio servers
4. Evaluates response policies via Keypost cloud API
5. Returns modified/allowed responses via stdout

Installation

Using npx (Recommended)

No installation needed - just use npx:

npx @keypost/wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp

Global Installation

npm install -g @keypost/wrapper

Then use directly:

keypost-wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp

Usage

Basic Usage

Replace your stdio server command with the wrapper:

Before:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    }
  }
}

After:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@keypost/wrapper",
        "--keypost", "my-fs",
        "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"
      ]
    }
  }
}

CLI Arguments

npx @keypost/wrapper --keypost <SLUG_OR_URL> -- <SERVER_COMMAND>

Options:

• --keypost <SLUG_OR_URL> (or -k) - Keypost slug or full URL (required).
  • Slug: my-fs (defaults to https://my-fs.keypost.ai)
  • Full URL: http://localhost:5001/my-fs (for local development)
• -- <COMMAND> - Local stdio server command and args (everything after --)

Environment Variables:

• DEBUG=keypost:* - Enable debug logging

Examples

Filesystem Server (Production):

npx @keypost/wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp

GitHub Server (Production):

npx @keypost/wrapper --keypost my-github -- npx @modelcontextprotocol/server-github

Custom Server (Local Development):

npx @keypost/wrapper --keypost http://localhost:5001/my-server -- python3 my_mcp_server.py

Configuration

1. Create Keypost in Dashboard

1. Go to https://app.keypost.ai
2. Click "Add Keypost"
3. Select type: Stdio
4. Enter name and slug (e.g., "My Filesystem", "my-fs")
5. Configure policies

2. Update AI Agent Config

Add the wrapper to your AI agent's MCP server configuration (see Usage above).

3. Use Normally

Your AI agent will now enforce Keypost policies on all tool calls to the local server.

Policy Examples

Block Write Operations

- tool: write_file
  access: deny

Restrict File Paths

- tool: read_file
  param:
    path:
      must_match: "^/Users/me/Documents/public/"

DLP on Responses

- tool: read_file
  response:
    dlp:
      block_patterns:
        ssn: "\\d{3}-\\d{2}-\\d{4}"
        api_key: "sk-[a-zA-Z0-9]{32}"
      action: redact

Rate Limiting

- tool: query_database
  throttle:
    max: 100
    per: hour

Rust Alternative

If you prefer a compiled binary with faster startup time, we also provide a Rust version:

cargo install keypost-wrapper

See keypost-wrapper for details.

Troubleshooting

Debug Logging

Enable verbose logging to see what's happening:

DEBUG=keypost:* npx @keypost/wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp

Wrapper Not Starting

Check that the server command after -- is correct:

# Test the server command directly first
npx @modelcontextprotocol/server-filesystem /tmp

Authentication Errors

Ensure your Keypost is configured with type "stdio" in the dashboard.

Process Not Cleaning Up

The wrapper handles SIGTERM/SIGINT to ensure stdio servers are terminated when the wrapper exits.

Requirements

• Node.js 18+
• npm or npx

License

MIT