# 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.

---

## 📂 Project Architecture Layout

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

```text
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:

```bash
# 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`:

```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:

```bash
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: <some-uuid> Grab that value.

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

```bash
 $ 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:

```bash
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