mcp-foxxy-bridge 1.5.0

A MCP Forward Proxy Bridge designed to be a one-to-many bridge allowing you to use a single MCP server to communicate with many MCP servers transparently.

MCP Foxxy Bridge

Overview

MCP Foxxy Bridge is a secure one-to-many proxy for the Model Context Protocol (MCP). Connect multiple MCP servers through a single endpoint with enterprise-grade security.

✨ Key Benefits

• 🔌 Single Endpoint: Access all your MCP servers through one connection point
• 🛡️ Enterprise Security: OAuth 2.0 + PKCE authentication with configurable SSL verification
• ⚡ Easy Setup: Simple configuration with environment variable support
• 🔀 Smart Routing: Automatic request routing to the right backend server
• 🏠 Secure by Default: Localhost-only binding, SSL verification enabled, and comprehensive input validation
• 🚀 HTTP/2 Support: Automatic protocol upgrade for improved performance

🎯 Perfect For

• Connecting multiple MCP servers to Claude Desktop, VS Code, or other AI tools
• Centralizing credential management with secure command substitution
• Production deployments requiring OAuth authentication
• Development environments with multiple data sources

---

🚀 Quickstart

See the Installation Guide for full details.

1. Choose one of the following installation methods

A. Install via uv (Recommended):

uv tool install mcp-foxxy-bridge

B. Install latest from GitHub:

uv tool install git+https://github.com/billyjbryant/mcp-foxxy-bridge

C. Run with Docker (from GHCR):

docker run --rm -p 8080:8080 ghcr.io/billyjbryant/mcp-foxxy-bridge:latest --bridge-config /app/config.json

---

2. Run the Bridge

With config file:

mcp-foxxy-bridge --bridge-config config.json

Or with named servers:

mcp-foxxy-bridge --port 8080 \
  --named-server fetch 'uvx mcp-server-fetch' \
  --named-server github 'npx -y @modelcontextprotocol/server-github' \
  --named-server filesystem 'npx -y @modelcontextprotocol/server-filesystem'

# With security features
mcp-foxxy-bridge --bridge-config config.json \
  --allow-command-substitution  # Enable secure command substitution

See Configuration Guide for config file examples.

---

3. Connect Your AI Tool

Point your MCP-compatible client to:

http://localhost:8080/sse

See API Reference for integration details.

---

📚 Documentation

🚀 Getting Started

• 📖 Documentation Overview - Start here for a complete guide
• ⬇️ Installation Guide - Multiple installation methods
• ⚙️ Configuration Guide - Configure your setup
• 🎯 Example Configurations - Ready-to-use config files

🔧 Advanced Usage

• 🚀 Deployment Guide - Docker, production deployments
• 🔌 API Reference - Programmatic integration
• 🏗️ Architecture Overview - Technical deep dive

📡 REST API Endpoints

The bridge provides REST endpoints for operational management, monitoring, and tool discovery:

Server Discovery & Status:

# Global bridge health and status
curl http://localhost:9000/status

# List all configured servers and their endpoints
curl http://localhost:9000/sse/servers

# List all available tags and their associated servers
curl http://localhost:9000/sse/tags

# Individual server status and health metrics
curl http://localhost:9000/sse/mcp/filesystem/status

Tool Discovery:

# List all available tools from all servers
curl http://localhost:9000/sse/list_tools

# List tools for a specific server
curl http://localhost:9000/sse/mcp/filesystem/list_tools

# List tools filtered by tags (supports union and intersection)
curl http://localhost:9000/sse/tag/development/list_tools      # Single tag
curl http://localhost:9000/sse/tag/dev+local/list_tools        # Intersection (AND)
curl http://localhost:9000/sse/tag/web,api/list_tools          # Union (OR)

Server Management:

# Force reconnection of a specific server
curl -X POST http://localhost:9000/sse/mcp/filesystem/reconnect

# Refresh tool capabilities across all servers
curl -X POST http://localhost:9000/sse/tools/rescan

OAuth Status (for OAuth-enabled servers):

# Check OAuth authentication status
curl http://localhost:9000/oauth/filesystem/status

These endpoints are ideal for monitoring, debugging, and operational management of your MCP bridge deployment.

🛡️ Security & Production

• 🔒 Security Guide - Comprehensive security practices
• 🔐 OAuth Authentication - Enterprise authentication setup

🆘 Support

• 🔧 Troubleshooting Guide - Common issues and solutions
• 🤝 Contributing Guide - Development setup and guidelines

---

🛠️ Development

• Development Setup
• Contributing Guide

---

🤝 Contributing & Support

• Contributing Guide
• Issue Tracker
• Discussions

---

⚖️ License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPLv3+). See the LICENSE file for details.

---