MCP Gateway

A generic, semantic MCP gateway exposing any HTTP-based SQL portal as both LLM-friendly MCP tools and standard REST endpoints. Designed from the ground up to serve human users (via UI/API) and AI agents simultaneously.

uv run main.py
uv run chainlit run chatbot.py -w

Architecture

                  +------------------+
                  |    Human User    |
                  +--------+---------+
                           |
                           | HTTP / REST
                           v
+---------+  MCP  +------------------+  HTTP  +------------------+
|   AI    +------>|   FastAPI App    +------>| SQL HTTP Portal  |
| (Agent) |       | (Semantic Layer) | (SQL) |                  |
+---------+       +--------+---------+       +------------------+
    ^                      |
    |                      |
    +--- from_fastapi() ---+
    (FastMCP Auto-maps tools)

User / Agent
     |
HTTP | MCP
     |
     v
+-------------+
| MCP Gateway |
+-------------+
       |
       +--> Auth : OIDC | OAuth2 | API Key
       +--> Secrets : .env | Secret Store | KMS
       +--> Identity : User Token | Service Account
       |
 HTTPS + Bearer Token
       |
       +--> OTCS
       +--> SQL Portal
       +--> REST API
       +--> CMIS API
       +--> Any Backend

Related MCP server: anythingmcp

Core Design Principles (LLM & Human Best Practices)

1. Semantic Layer Abstraction: No raw CRUD endpoints. Expose high-level intent routes (/search-tables, /top, /explore) to reduce LLM cognitive load and simplify frontend code.

2. Strict Explict Identification: Every route enforces a clean, action-oriented operation_id (query_sql, search_tables). FastMCP maps these directly into clear tool names for the LLM.

3. Intent-Driven Documentation: Docstrings explicitly declare when and why to use the endpoint ("""Semantic table search."""), acting directly as LLM prompt steering.

4. Strict Typing via Enums: Restrict input options using Pydantic Enums to eliminate LLM parameter hallucinations.

5. Server-Side Data Aggregation: Compute metrics and perform table joins inside Python to save LLM context window tokens and prevent API call chaining.

Pros & Cons

Advantages

• DRY Codebase: Single source of truth. One FastAPI setup automatically serves both humans (REST) and AI (MCP).

• AI-First Performance: Fastembed vector search and server-side constraints (FORBIDDEN keywords, limits) keep the LLM fast, secure, and accurate.

• Low Footprint: No heavy local database or native drivers required; works over standard HTTP.

Disadvantages

• Path Parameter Blindness: Complex dynamic routes like /distinct/{table}/{column} require the LLM to successfully call /search-tables first to discover valid values.

• Tight Coupling: Aligning REST routes to serve both human UX and LLM token-efficiency can require design trade-offs for heavily nested data.

AI

# if : full python agent (use openrouter)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install aider-chat --python 3.12 --force
uv tool install specify-cli
specify init mcp-gateway --integration claude --ignore-agent-tools
aider --model openrouter/nvidia/nemotron-3-ultra-550b-a55b:free --no-auto-commits --test-cmd pytest

# else :
sudo bash script.sh