Skip to main content

Pass-through Proxy

Overview​

The Pass-through Proxy is a Model Context Protocol (MCP) server that acts as a middleware layer between AI assistants and MCP tools. It enables you to intercept, validate, modify, and monitor all tool interactions through a flexible hook system.

Why Use Pass-through Proxy?​

For a detailed explanation of why MCP needs hooks, see the repository README which explains the core concepts.

Getting Started​

Installation​

The Pass-through Proxy is available as an npm package:

npm install -g @civic/passthrough-mcp-server

Basic Setup​

  1. Identify your target MCP server - The server you want to add middleware to
  2. Choose or create hooks - Pre-built hooks are available, or create custom ones
  3. Configure and run - Set environment variables and start the proxy

For a complete getting started guide, see Getting Started in the repository.

Configuration​

Configure via environment variables:

  • PORT - Where the proxy listens (default: 34000)
  • TARGET_SERVER_URL - The MCP server to forward requests to
  • HOOKS - Comma-separated URLs of hook servers

Example:

export TARGET_SERVER_URL="http://localhost:3000"
export HOOKS="http://localhost:33004,http://localhost:33005"
pnpm start

Available Hooks​

The monorepo includes several pre-built hooks. See Available Packages for the complete list:

Audit Hook​

Logs every request and response for debugging and compliance. Perfect for understanding what your AI is doing.

Guardrail Hook​

Implements security rules to filter and validate requests. Includes domain filtering and content restrictions.

Rate Limit Hook​

Enforces usage limits per user with configurable windows and clear retry-after responses.

Explain Hook​

Adds a "reason" parameter to all tools, encouraging transparency in AI tool usage.

Custom Description Hook​

Modifies tool descriptions based on context, useful for environment-specific guidance.

Creating Custom Hooks​

Hooks implement a simple interface with three possible responses:

  1. Continue - Allow the request (possibly modified)
  2. Reject - Block the request with an error
  3. Respond - Return a response without calling the target

For detailed implementation examples, see Creating Your Own Hook in the repository.

Integration Patterns​

With MCP Hub​

Use Pass-through Proxy as middleware in the MCP Hub to apply consistent policies across all tools.

With Claude Desktop​

Add hooks to any MCP server used by Claude Desktop by configuring the proxy as an intermediary.

In Production​

Deploy hooks as separate microservices for scalability and independent updates.

Architecture​

The proxy uses:

  • @modelcontextprotocol/sdk for the server implementation
  • tRPC for type-safe hook communication

Hook processing follows a pipeline pattern:

  • Requests flow through hooks in order
  • Responses flow back in reverse order
  • Any hook can short-circuit the pipeline

Resources​

Contact us if you need help building custom middleware for your MCP tools.