Agnostic MCP HTTP/SSE Proxy Server (SDK v2.0.0+)

A highly extensible, API-agnostic Model Context Protocol (MCP) proxy gateway built using Python's modern MCP SDK 2.0.0+, FastAPI, and Starlette.

This server acts as a centralized routing engine that discovers, sanitizes, namespaces, and executes tools published across multiple independent, downstream remote HTTP/SSE or unified gateway MCP servers (such as Yahoo Finance or AlphaVantage) without hardcoding explicit routes or functions.

🌟 Key Features

• Agnostic Schema Discovery: Merges dynamic tool capabilities across distinct downstream endpoints seamlessly.

• Isolation Namespacing: Auto-prefixes remote tools using the syntax {server_name}__{original_tool_name} to isolate environments and prevent asset collisions.

• Protocol Failure Resilience: Automatically strips conflicting output_schema fields from non-compliant remote servers to prevent runtime deserialization exceptions.

• Production-Grade Project Layout: Fully modularized layout cleanly separating configurations, server logic, network routers, and telemetry wrappers.

• Daily Rotating Local Logging: Built-in rolling log files saved to a dedicated logs/ directory with explicit date-stamps.

Related MCP server: MCP Proxy Server

📂 Project Architecture Layout

The codebase implements a decoupled design pattern to ensure straightforward maintainability:

mcp_proxy/
│
├── config/
│   ├── __init__.py
│   └── manager.py       # Handles reading/persisting proxy_servers.json relative to the module
│
├── observability/
│   ├── __init__.py
│   └── tracker.py       # Async context manager placeholder for tiktoken and future MLflow metrics
│
├── core/
│   ├── __init__.py
│   └── proxy.py         # Primary MCP server engine and namespaced call routing loops
│
├── api/
│   ├── __init__.py
│   └── routes.py        # Connects raw Starlette routes bypassing FastAPI middleware issues
│
├── logs/
│   └── mcp_proxy.log    # Active file logging sink (daily timestamp rotated)
│
├── .gitignore           # Eradicates runtime cache and configuration leakage to VCS trackers
├── proxy_servers.json   # Local flat registry containing active remote endpoints
└── main.py              # Application lifecycle entry point (Uvicorn launchpad)

🛠️ Quick Start

1. Installation

Clone the repository, initialize your virtual environment, and install dependencies utilizing trusted host flags to bypass SSL roadblocks:

# Create and activate environment
python -m venv venv
./venv/Scripts/activate # On Windows Powershell

# Install dependencies securely
pip install -r requirements.txt

2. Configure Downstream Servers

Populate the configuration registry file inside the config/ directory. Create config/proxy_servers.json:

{
  "yahoo_finance": "https://gateway.mcpservers.org/yahoo-finance/mcp",
  "alphavantage_mcp": "http://localhost:8001/mcp"
}

3. Launch the Server

Execute the uvicorn launchpad from the root project directory:

python main.py

🧪 cURL Testing Sequences

The proxy operates using asynchronous Server-Sent Events (SSE). Testing requires a two-step approach: opening a persistent listening stream channel first, followed by sending JSON-RPC payloads containing an active tracking token.

Step 1: Open the Streaming Monitor Connection

Open a first terminal window.

1. Initialize — capture the session id.

curl -i -X POST http://localhost:8000/mcp
-H "Content-Type: application/json"
-H "Accept: application/json, text/event-stream"
-d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2026-07-28", "capabilities": {}, "clientInfo": {"name": "curl-client", "version": "1.0"} } }'

Look at the response headers (-i prints them) for: Mcp-Session-Id: Grab that value.

2. Send the required initialized notification (some servers reject calls before this)

 $ curl -i -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: a1d13341fca34c7eb5c6684e9983e6b9" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

HTTP/1.1 202 Accepted
date: Wed, 09 Sep 2026 12:05:51 GMT
server: uvicorn
content-type: application/json
mcp-session-id: a1d13341fca34c7eb5c6684e9983e6b9
content-length: 0

Step 2: Fetch the Consolidated Tools List

Open a second terminal window and push a tools/list JSON-RPC request frame. Replace the session_id parameter at the end of the URL with your copied token:

curl -s -X POST http://localhost:8000/mcp
-H "Content-Type: application/json"
-H "Accept: application/json, text/event-stream"
-H "Mcp-Session-Id: a1d13341fca34c7eb5c6684e9983e6b9"
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }' | python3 -m json.tool

The | python3 -m json.tool just pretty-prints it — drop that if you want the raw single-line response.

Step 3: Execute a Proxied Tool Call

To invoke an environment-isolated remote tool, execute a tools/call JSON-RPC payload in your second terminal window, embedding the target parameters inside the flat schema layout:

curl -i -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: a1d13341fca34c7eb5c6684e9983e6b9" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "yahoofinance_mcp__get_quote",
      "arguments": {
        "symbols": ["MSFT", "AAPL"]
      }
    }
  }'


---

### Step 4: Interrogate Internal Proxy Management Tools
You can check proxy states or update bindings on-the-fly using native management tools:

#### List Registered Upstream Hosts

#### Dynamically Register a New Remote Server

####

curl -i -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: a1d13341fca34c7eb5c6684e9983e6b9" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "yahoofinance_mcp__get_quote",
      "arguments": {
        "symbols": ["MSFT", "AAPL"]
      }
    }
  }'

# MLFLOW Logging and URL Configuration resides in .env file Create on ROOT Directory .env file has 

MCP_PROXY_LOGGING=false
MLFLOW_TRACKING_URI=http://127.0.0.1:5000