MCP Gateway

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](docs/media/local_demo.mp4) — short demo of Claude Desktop querying a database through MCP Gateway.

Table of Contents

• Overview
• Features
• Architecture
• Quick Start
• Configuration
• Authentication
• API Reference
• MCP Integration
• Role-Based Access Control
• Entra ID / SSO
• Development
• Troubleshooting
• Security
• Additional Documentation

---

Overview

MCP Gateway sits between AI assistants and your databases. It:

1. Authenticates users via password login, Microsoft Entra ID (Azure AD), or API keys
2. Enforces role-based access control (viewer / analyst / admin)
3. Exposes databases as MCP tools that AI assistants can discover and call
4. Translates natural language questions into SQL via Claude, executes queries, and summarizes results
5. 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

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

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

git clone <repo-url>

cd MCP-Gateway cp .env.example .env

Edit .env:

# Required — generate unique values

SECRET_KEY= ENCRYPTION_KEY= POSTGRES_PASSWORD=

Required for natural language query

ANTHROPIC_API_KEY=sk-ant-...

Update to your server's public URL in production

BASE_URL=http://localhost:8000

Generate secure random values:

# SECRET_KEY

python3 -c "import secrets; print(secrets.token_hex(32))"

ENCRYPTION_KEY (min 32 chars; full key consumed via BLAKE2b derivation)

python3 -c "import secrets; print(secrets.token_hex(32))"

2. Start the stack

docker compose up -d

Services started:

• api on port 8000 (FastAPI + admin UI)
• db on port 5432 (PostgreSQL, internal only)

3. Register your first tenant

curl -s -X POST http://localhost:8000/tenants/ \

-H "Content-Type: application/json" \ -d '{ "name": "My Organization", "slug": "my-org", "admin_email": "admin@example.com", "admin_password": "SuperSecret123!" }' | jq

The slug becomes part of your MCP URL: http://localhost:8000/t/my-org/mcp/sse

4. Open the admin UI

Navigate to http://localhost:8000/admin/ and sign in with your admin credentials.

5. Add a database connection

In the admin UI → Connections → Create connection, or via API:

TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \

-H "Content-Type: application/json" \ -d '{"email":"admin@example.com","password":"SuperSecret123!"}' \ | jq -r .access_token)

curl -s -X POST http://localhost:8000/connections/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Production DB", "db_type": "postgres", "connection_string": "postgresql://user:pass@host/mydb", "min_role": "viewer" }' | jq

6. Connect Claude Desktop

Add to your Claude Desktop MCP config (`~/Li