gs-mcp-proxy-pii-redactor

@growthspace-engineering/gs-mcp-proxy-pii-redactor

MCP Proxy with PII Redaction

---

An MCP proxy that aggregates multiple MCP servers behind a single HTTP entrypoint, with built-in PII redaction capabilities.

Features

• Proxy multiple MCP servers: Aggregate tools, prompts, and resources from many servers through a single HTTP endpoint
• Multiple transport types: Support for stdio, sse, and streamable-http client transports
• Server transport options: Serve via Server-Sent Events (SSE) or streamable HTTP
• PII redaction: Automatic redaction of PII using GCS-backed dictionaries and generic pattern matching
• Tool filtering: Allow or block specific tools per server configuration
• Authentication: Bearer token authentication with per-server or global configuration
• Audit logging: Optional verbose audit logging for redaction operations
• Flexible configuration: JSON configuration with environment variable interpolation

Documentation

• IDE setup
  • Cursor
    • Claude Desktop
    • Other IDEs
• Configuration - Configuration reference and examples
• Usage - CLI options, endpoints, authentication, and tool filtering
• PII Redaction - Redaction setup and configuration
• Deployment - Production deployment
• Docker Usage - Build, run, and configure the Docker image

Quick Start

Prerequisites

• Node.js >= 20 (or equivalent bun or pnpm)

Integrate directly with your IDE over stdio. No global install required.

Before configuring your IDE, initialize a default config file (creates ~/gs-mcp-proxy/config.json by default):

gs-mcp-proxy --init
# or without installing globally
npx -y @growthspace-engineering/gs-mcp-proxy-pii-redactor --init

See Usage to customize the destination via --init-dest.

• Cursor: see docs/ide/cursor.md (stdio section)
• Claude Desktop: see docs/ide/claude.md (stdio section)
• Other IDEs: see docs/ide/other.md

Option 2 — Run locally before IDE integration (SSE/HTTP)

1. Install the module globally:

   npm install -g @growthspace-engineering/gs-mcp-proxy-pii-redactor
   

2. Initialize a default config file (creates ~/gs-mcp-proxy/config.json by default):

   gs-mcp-proxy --init
   

   See Usage to customize the destination via --init-dest.
3. Run the CLI (with or without a config file):

   gs-mcp-proxy --config ~/gs-mcp-proxy/config.json
   # or (uses ./config.json by default if present)
   gs-mcp-proxy
   

4. Connect your IDE using mcp-remote (SSE or streamable HTTP):
   • Cursor: see docs/ide/cursor.md (SSE/HTTP sections)
     • Claude Desktop: see docs/ide/claude.md (SSE/HTTP sections)

Developer setup (clone, build, run locally) has moved to CONTRIBUTING.md.

Minimal Configuration (for local server)

{
  "mcpProxy": {
    "baseURL": "http://localhost:8084",
    "addr": ":8084",
    "name": "MCP Proxy with PII Redaction",
    "version": "1.0.0",
    "type": "sse"
  },
  "mcpServers": {
    "github": {
      "transportType": "streamable-http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

See Configuration for full configuration reference and examples.

Testing

# Unit tests
npm test

# E2E tests (requires GITHUB_TOKEN)
export GITHUB_TOKEN=your_token_here
npm run test:e2e

Note: All E2E tests require a valid GITHUB_TOKEN environment variable. The test suite validates both SSE and Streamable HTTP transport options.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

This project follows the all-contributors specification. Contributions of any kind welcome!

Code of Conduct

This project adheres to a Code of Conduct. Please read CODE_OF_CONDUCT.md before contributing.

Contributors

Thanks goes to these wonderful people (emoji key):

Neil Kalman 💻 💬 📝 📖 🤔 🚇 🔬	Romario Nijim 🤔 🔬 💬	shai eliyahu 👀	Gal Amitai 👀	Yevgeni Mumblat 🤔	Utkarsh9571 💻 💡	Mr. Narra Mine 👀
allcontributors[bot] 💻	gr0wth-b0t 💻	Riki Shachor 👀	katerina-semikina 👀

How It Works

When you merge a pull request, our GitHub Actions workflow automatically:

• Adds the contributor to the .all-contributorsrc configuration
• Updates the Contributors section in this README
• Creates a commit with the changes

You can also manually add contributors using:

npm run contributors:add

and the allcontributors cli will prompt you for the contribution details.

Acknowledgments

This project was inspired by the following projects:

• TBXark/mcp-proxy: a Go-based MCP proxy server that aggregates multiple MCP servers through a single HTTP endpoint.
• nestjs/nest: a progressive Node.js framework for building server-side applications.

License

MIT 2025

---

Summary

GrowthSpace’s open-sourced MCP proxy (TypeScript/NestJS): redacts PII from MCP tool responses (Jira, GCP logs) before agents see them. Aho-Corasick dictionary matching (~100k entries) plus pattern scanner, recursive or key-scoped redaction.

Learnings

• MCP is the newest interception point in the stack — the proxy sits between agent and tools instead of agent and LLM. Their rewrite journey (Go fork → TS rewrite for stdio support) is documented in the Medium writeup captured in clippings.

Gotchas

• (none yet)

Hands-on

(research only — see PII redaction)