@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](docs/ide/README.md)
- [Cursor](docs/ide/cursor.md)
- [Claude Desktop](docs/ide/claude.md)
- [Other IDEs](docs/ide/other.md)
- [Configuration](docs/configuration.md) - Configuration reference and examples
- [Usage](docs/usage.md) - CLI options, endpoints, authentication, and tool filtering
- [PII Redaction](docs/redaction.md) - Redaction setup and configuration
- [Deployment](docs/deployment.md) - Production deployment
- [Docker Usage](docs/docker.md) - Build, run, and configure the Docker image
## Quick Start
### Prerequisites
- Node.js >= 20 (or equivalent bun or pnpm)
### Option 1 — Run with stdio (recommended)
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):
```bash
gs-mcp-proxy --init
# or without installing globally
npx -y @growthspace-engineering/gs-mcp-proxy-pii-redactor --init
```
See [Usage](docs/usage.md) to customize the destination via `--init-dest`.
- Cursor: see [docs/ide/cursor.md](docs/ide/cursor.md) (stdio section)
- Claude Desktop: see [docs/ide/claude.md](docs/ide/claude.md) (stdio section)
- Other IDEs: see [docs/ide/other.md](docs/ide/other.md)
### Option 2 — Run locally before IDE integration (SSE/HTTP)
1. Install the module globally:
```bash
npm install -g @growthspace-engineering/gs-mcp-proxy-pii-redactor
```
2. Initialize a default config file (creates `~/gs-mcp-proxy/config.json` by default):
```bash
gs-mcp-proxy --init
```
See [Usage](docs/usage.md) to customize the destination via `--init-dest`.
3. Run the CLI (with or without a config file):
```bash
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](docs/ide/cursor.md) (SSE/HTTP sections)
- Claude Desktop: see [docs/ide/claude.md](docs/ide/claude.md) (SSE/HTTP sections)
Developer setup (clone, build, run locally) has moved to [CONTRIBUTING.md](CONTRIBUTING.md).
### Minimal Configuration (for local server)
```json
{
"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](docs/configuration.md) for full configuration reference and examples.
## Testing
```bash
# 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](CONTRIBUTING.md) for guidelines.
This project follows the [all-contributors](https://github.com/all-contributors/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](CODE_OF_CONDUCT.md) before contributing.
## Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
### 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:
```bash
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](https://github.com/TBXark/mcp-proxy): a Go-based MCP proxy server that aggregates multiple MCP servers through a single HTTP endpoint.
- [nestjs/nest](https://github.com/nestjs/nest): a progressive Node.js framework for building server-side applications.
## License
MIT 2025
![allcontributors[bot]](https://avatars.githubusercontent.com/in/23186?v=4?s=100)
