fastproxy

fastproxy

An OAuth-secured, unified MCP gateway. Aggregates all your MCP servers into a single endpoint — one URL, one login, granular per-user tool control.

Built on FastMCP.

---

What it does

You have a dozen MCP servers (filesystem, GitHub, home automation, databases, etc.) spread across Claude, Cursor, Codex, Gemini. Each needs its own config entry in each AI assistant. There's no central auth, no way to say "this user can't touch the filesystem tools", and no audit trail.

fastproxy fixes that:

• One endpoint — connect your AI assistant to https://your-server/mcp and get every tool from every backend
• OAuth-secured — one login for everything, with API key fallback for machine-to-machine
• Per-user tool control — admin can revoke specific tools per user without touching upstream servers
• Live updates — toggle a tool off and connected clients are notified immediately
• Auto-discovery — scans your existing AI assistant configs and imports servers with your approval
• Admin UI — interactive FastMCPApp interface for managing everything

---

Quick start

pip install fastproxy

# Required: set JWT secret before first run
export FASTPROXY_JWT_SECRET="$(openssl rand -hex 32)"

# Start with a config file
fastproxy serve --config proxy.json

# Or auto-discover from your existing AI assistant configs
fastproxy discover

Minimal proxy.json

{
  "admins": ["your-user-id"],
  "storage": {
    "backend": "redis",
    "url": "redis://localhost:6379/0"
  },
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

All tools are namespaced by server alias: filesystem__read_file, github__create_issue, etc.

---

Installation

Requires Python 3.11+.

# Core proxy
pip install fastproxy

# With code-mode transform support
pip install "fastproxy[code-mode]"

# With app UI support
pip install "fastproxy[apps]"

# Everything
pip install "fastproxy[all]"

---

Two commands

# HTTP proxy server — clients connect to this
fastproxy serve [--config proxy.json] [--host 0.0.0.0] [--port 8000]

# Admin channel server — Claude Code spawns this for in-session notifications (optional)
fastproxy channel [--config proxy.json]

---

Docker

docker compose up

docker-compose.yml:

services:
  proxy:
    image: ghcr.io/jmagar/fastproxy:latest
    ports:
      - "8000:8000"
    environment:
      FASTPROXY_JWT_SECRET: "${FASTPROXY_JWT_SECRET}"
    volumes:
      - ./proxy.json:/app/proxy.json:ro
      - ./skills:/app/skills
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  redis-data:

---

Configuration reference

proxy.json is watched for changes — edit it and the proxy hot-reloads without dropping connections.

{
  "admins": ["user-id-1", "user-id-2"],

  "storage": {
    "backend": "redis",
    "url": "redis://localhost:6379/0"
  },

  "rate_limits": {
    "requests_per_minute": 60,
    "requests_per_hour": 1000
  },

  "list_page_size": 50,

  "skills_dir": "./skills",
  "vendor_skills": ["claude", "cursor"],

  "servers": {
    "my-server": {
      "transport": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      },
      "tags": ["cacheable"],
      "cache_ttl": 300,
      "enabled": true
    },
    "remote-server": {
      "transport": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Server entry fields:

Field	Type	Description
transport	"stdio" | "http" | "sse"	How to connect to the upstream server
command	string	Command to run (stdio only)
args	string[]	Command arguments (stdio only)
url	string	Upstream URL (http/sse only)
env	object	Environment variables. ${VAR} interpolation supported
tags	string[]	Tags for filtering. Use "cacheable" to enable response caching
cache_ttl	int	Component list cache TTL in seconds (default: 300, set to 0 to disable)
enabled	bool	Whether this server is active (default: true)

Server aliases must match [a-z0-9-]+. Hyphens are converted to underscores in tool names: my-server → my_server__tool_name.

---

Environment variables

Variable	Required	Description
FASTPROXY_JWT_SECRET	Yes	JWT signing key. Proxy refuses to start without it. Changing this invalidates all sessions.
FASTPROXY_LIST_PAGE_SIZE	No	Override pagination page size (default: 50)

---