MCP Gateway

The production platform for MCP tools.
Claude Desktop can connect to your internal tools β databases, filesystems, APIs, anything β through a single authenticated endpoint. You control who can use which tools, every action is logged, and no raw credentials ever leave your server.
Built-in tools: SQL query (Postgres, MySQL, SQLite, MSSQL), filesystem access.
Custom tools: plug in anything that implements the MCP tool interface.
See it in action β short demo of Claude Desktop querying a database through MCP Gateway.
Table of Contents
Overview
MCP Gateway sits between AI assistants and your databases. It:
- Authenticates users via password login, Microsoft Entra ID (Azure AD), or API keys
- Enforces role-based access control (viewer / analyst / admin)
- Exposes databases as MCP tools that AI assistants can discover and call
- Translates natural language questions into SQL via Claude, executes queries, and summarizes results
- Logs all activity to a structured audit trail
Claude Desktop / mcp-remote
β
β MCP over SSE (OAuth 2.1 + PKCE)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Gateway β
β β
β ββββββββββββ ββββββββββββ βββββββββββββββββββββββββ β
β β Auth / β β Admin β β MCP SSE Endpoint β β
β β OAuth β β UI β β /t/{slug}/mcp/sse β β
β ββββββββββββ ββββββββββββ βββββββββββββββββββββββββ β
β β β
β βββββββββββββββββββββββββββββββββββββββββ β
β β Tool Providers ββ β
β β sql.py β get_schema / execute_sql ββ β
β βββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββββ
β Decrypted DSN
βββββββββββββββββββββββΌβββββββββββββββββ
β Your Databases β β
β Postgres MySQL MSSQL SQLite β
βββββββββββββββββββββββββββββββββββββ β
What you get out of the box
For your organisation
- One URL for Claude Desktop β users authenticate once, access everything they're allowed
- Microsoft Entra ID SSO β roles assigned automatically from Azure AD groups
- Full audit trail β every tool call, every query, every login, who did what and when
For your tools
- Drop any MCP tool into the gateway and it inherits auth, RBAC, and logging automatically
- Per-tool role overrides β restrict SQL execution to analysts, filesystem writes to admins
- Bundled: SQL tools (4 databases), filesystem tools (read, write, search, tree)
For your security team
- No credentials on employee machines
- Tenant isolation β org A cannot see org B's tools or data
- API keys for CI/CD, OAuth 2.1 + PKCE for human users
Supported Databases
| Database | Driver | DSN Format |
|---|
| PostgreSQL | psycopg2 | postgresql://user:pass@host/db |
| MySQL / MariaDB | PyMySQL | mysql+pymysql://user:pass@host/db |
| Microsoft SQL Server | pymssql | mssql+pymssql://user:pass@host/db |
| SQLite | Built-in | sqlite:///path/to/file.db |
Filesystem Tools
- Sandboxed file read/write/search exposed as MCP tools
- Enabled via
FILESYSTEM_ALLOWED_DIRS environment variable
- Read operations (analyst+):
fs_read_file, fs_list_directory, fs_directory_tree, fs_search_files, fs_get_file_info
- Write operations (admin):
fs_write_file, fs_create_directory, fs_move_file
Admin UI
- Web interface served at
/admin/
- Manage connections, users, SSO config, API keys, and tool roles
- View audit logs, generated SQL, and query results
Architecture
Technology Stack
| Layer | Technology | Version |
|---|
| API Framework | FastAPI + Starlette | 0.136.1 / 1.3.1 |
| ASGI Server | Uvicorn | 0.34.0 |
| Validation | Pydantic + pydantic-settings | 2.12.5 / 2.7.1 |
| ORM | SQLAlchemy | 2.0.30 |
| Migrations | Alembic | 1.13.1 |
| Auth / JWT | PyJWT + bcrypt | 2.14.0 / 4.0.1 |
| Encryption | cryptography (Fernet) | 50.0.0 |
| LLM | Anthropic SDK | 0.42.0 |
| MCP Protocol | mcp | 1.28.1 |
| SQL Validation | sqlglot | 25.1.0 |
| Rate Limiting | slowapi | 0.1.9 |
| HTTP Client | httpx | 0.28.1 |
| DB Drivers | psycopg2-binary / PyMySQL / pymssql | 2.9.10 / 1.1.1 / 2.3.1 |
| Frontend | React 18 + TypeScript + Vite | β |
Dev tooling (requirements-dev.txt): pytest, pytest-asyncio, ruff, mypy.
The pinned versions above are generated from requirements.txt β update both together.
Project Structure
app/
βββ main.py # FastAPI app setup, middleware, routing
βββ config.py # Environment config (Pydantic Settings)
βββ database.py # SQLAlchemy engine + session factory
βββ api/
β βββ auth.py # POST /auth/login
β βββ auth_entra.py # Entra SSO (legacy admin UI paths)
β βββ oauth.py # OAuth 2.1 endpoints (/t/{slug}/oauth/*)
β βββ connections.py # DB connection CRUD
β βββ query.py # Natural language query endpoint
β βββ tenants.py # Tenant + user management
β βββ tools.py # Tool listing + role overrides
β βββ mcp_sse.py # MCP SSE transport
β βββ api_keys.py # API key management
β βββ audit_logs.py # GET /audit-logs/ (admin)
βββ core/
β βββ auth.py # JWT creation/validation, password hashing
β βββ dependencies.py # FastAPI dependency injection
β βββ rbac.py # Role hierarchy helpers
β βββ security.py # Fernet encrypt/decrypt
β βββ api_keys.py # API key generation + hashing
β βββ limiter.py # slowapi rate limiter setup
β βββ log_filter.py # Health-check log noise filter
βββ constants.py # Non-tunable application-wide constants (pagination caps, etc.)
βββ models/__init__.py # All SQLAlchemy ORM models
βββ schemas/__init__.py # All Pydantic request/response schemas
βββ services/
β βββ entra.py # Microsoft Graph API client
β βββ llm.py # Anthropic API (SQL gen + summarization)
β βββ mcp_client.py # Direct SQLAlchemy schema introspection + query execution
β βββ audit.py # Audit log writer
βββ tools/
βββ __init__.py # Tool provider framework + registry
βββ sql.py # DB schema + execute_sql tools
βββ example.py # Example custom tools
βββ filesystem.py # Sandboxed file read/write/search tools
app/static/ # Built admin UI, served at /admin/ (generated by the
# frontend build; not edited by hand)
frontend/src/
βββ main.tsx # Vite entry point
βββ App.tsx # Root component, auth context, tab routing
βββ api.ts # API client, token management
βββ types.ts # TypeScript types (mirrors Pydantic schemas)
βββ constants.ts # Frontend constants (timeouts, retry config)
βββ app.css # Global styles
βββ hooks/
β βββ useForm.ts # Shared form state helper
βββ components/
βββ Login.tsx # Sign-in form
βββ Setup.tsx # Tenant registration
βββ Dashboard.tsx # Tenant info + role display
βββ Connections.tsx # DB connection management
βββ ConnectionCreateForm.tsx # Add-connection form
βββ ConnectionEditRow.tsx # Inline connection editor
βββ Query.tsx # Natural language query UI
βββ Users.tsx # User management (admin)
βββ SsoConfig.tsx # Entra ID configuration (admin)
βββ Tools.tsx # Tool browser + role overrides
βββ ToolGroup.tsx # Grouped tool listing
βββ ToolRoleOverride.tsx # Per-tool role control
βββ ApiKeys.tsx # API key management
βββ AuditLog.tsx # Filterable audit log viewer (admin)
βββ AuditLogFilters.tsx # Audit log filter controls
βββ AuditLogDetail.tsx # Single audit entry detail
βββ ConfirmModal.tsx # Reusable confirmation dialog
βββ ErrorBoundary.tsx # Top-level error boundary
alembic/versions/ # Database migrations
docs/ # Guides (OAuth flow, deployment, audit logging, β¦)
tests/ # pytest suite (SQLite in-memory, no services needed)
Database Schema
Tenants ββ¬ββΊ Users βββββββΊ APIKeys
βββΊ APIKeys (also a direct tenant_id FK, not only via Users)
βββΊ DBConnections
βββΊ TenantEntraConfig
βββΊ AuditLogs (tenant_id and user_id both nullable)
βββΊ OAuthAuthorizationCodes
βββΊ OAuthRefreshTokens
βββΊ ToolRoleOverrides
OAuthStates (no tenant_id FK β holds a plain
tenant_slug string, since the row is
created before the tenant is resolved)
Quick Start
Prerequisites
- Docker and Docker Compose
- An Anthropic API key (for the
/query/ endpoint; not needed for raw MCP tool access)
1. Clone and configure