MCP Tool Transform Proxy

A Python CLI that proxies remote MCP servers while applying configurable tool transformations (name, description, arguments). Sits transparently between MCP clients (like Claude Desktop) and remote MCP servers.

Installation

pip install mcp-transform-proxy

Quick Start

1. Create a configuration file:

{
  "mcpServers": {
    "myserver": {
      "url": "https://my-mcp-server.example.com/mcp",
      "tools": {
        "original_tool": {
          "description": "Enhanced description with context about when to use this tool"
        }
      }
    }
  }
}

2. Run the proxy:

mcp-transform-proxy --config config.json

Configuration

Full Configuration Example

{
  "proxy": {
    "name": "MyToolProxy",
    "transport": "stdio",
    "port": 8080
  },
  "mcpServers": {
    "weather": {
      "url": "https://weather-api.example.com/mcp",
      "transport": "sse",
      "tools": {
        "get_weather": {
          "name": "check_weather",
          "description": "Check current weather. Use when user asks about weather.",
          "arguments": {
            "units": {
              "default": "metric",
              "hide": true
            },
            "location": {
              "name": "city",
              "description": "City name to check"
            }
          }
        },
        "internal_tool": {
          "enabled": false
        }
      }
    }
  }
}

Configuration Reference

Proxy Settings

Server Settings

Tool Transformations

Argument Transformations

Tool Name Prefixing

FastMCP's composite proxy automatically prefixes tool names with the server name. For example, if you have a server named weather with a tool get_forecast, the prefixed name will be weather_get_forecast.

When configuring tool transforms, use the original tool name (without prefix) in your config - the proxy handles prefixing internally.

CLI Options

Usage: mcp-transform-proxy [OPTIONS]

Options:
  -c, --config PATH      Path to JSON config file (required)
  -t, --transport TEXT   Override transport mode (stdio or http)
  -p, --port INTEGER     Override HTTP port
  --version              Show version
  --help                 Show this message and exit

Container Usage

Running with Podman/Docker

# Pull the image
podman pull quay.io/bbrowning/mcp-transform-proxy:latest

# Run with a config file
podman run -v ./config.json:/config/config.json:ro \
  quay.io/bbrowning/mcp-transform-proxy:latest

# Run in HTTP mode for testing
podman run -p 8080:8080 -v ./config.json:/config/config.json:ro \
  quay.io/bbrowning/mcp-transform-proxy:latest \
  --config /config/config.json --transport http

Building the Container

# Build with podman
make build-container

# Build with docker
make build-container CONTAINER_ENGINE=docker

OpenShift Deployment

See docs/openshift-deployment.md for deploying to OpenShift with Kustomize manifests.

Development

# Clone the repository
git clone https://github.com/bbrowning/mcp-transform-proxy.git
cd mcp-transform-proxy

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy src

License

MIT