Sql Cortex

SQL Cortex MCP

MCP server that gives AI agents (Claude, OpenAI, Gemini, etc.) direct access to SQL databases — with policy enforcement, schema tools, and an admin UI.

What is this?

SQL Cortex MCP is a Model Context Protocol server that exposes SQL databases as tools for AI agents. It sits between your LLM and your database, providing:

• 11 MCP tools — query, schema introspection, explain plans, migrations, multi-DB switching
• Multi-database — manage multiple connections, per-session switching via db.list/db.use
• Policy enforcement — read-only mode, query allowlists, row limits, timeouts
• Admin UI — web dashboard with query sandbox, schema browser, chat assistant, settings
• Multi-provider LLM — OpenAI, Anthropic, DeepSeek, Ollama, Gemini, Groq, Mistral
• Persistent settings — encrypted API keys, runtime config changes survive restarts

Quick Start

Docker (recommended)

git clone https://github.com/loglux/sql-cortex-mcp.git
cd sql-cortex-mcp
docker compose up -d

Open http://localhost:8123 for the admin UI.

Local

git clone https://github.com/loglux/sql-cortex-mcp.git
cd sql-cortex-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Connect your AI agent

Point any MCP-compatible client at the server:

MCP endpoint:  http://localhost:8123/mcp
Protocol:      HTTP + JSON-RPC
SSE endpoint:  http://localhost:8123/mcp (GET for Server-Sent Events)

MCP Tools

MCP Resources

MCP Prompts

Note: ChatGPT's MCP connector supports only tools, not prompts or resources. If you use ChatGPT, paste the following into your Custom Instructions:

You are a database assistant connected to a live SQL database via MCP
(Model Context Protocol).

Rules:
1. ALWAYS call sql.schema first at the start of each conversation to get
   the current schema. Never assume or cache table names from previous messages.
2. Read the sql.query tool description — it tells you the database engine
   (SQLite, MySQL, PostgreSQL). Use the correct SQL dialect.
3. For read queries use sql.query. For writes use db.apply. Never mix them.
4. If a query fails with a syntax error, check the dialect and retry
   with correct syntax.
5. Prefer sql.schema over SHOW TABLES / information_schema for discovering tables.
6. When presenting results, format them as clean tables. Keep explanations concise.

Admin UI

The built-in web UI provides:

• Dashboard — server status, quick actions
• Query — SQL sandbox with syntax highlighting and result tables
• Schema — browse tables, columns, indexes
• Chat — natural language to SQL via LLM (multiple sessions, persistent history, per-session DB binding)
• Logs — query audit trail
• Settings — manage multiple DB connections, LLM providers, runtime parameters

Sandbox	Settings

Configuration

Environment variables

Settings changed via the admin UI override environment variables at runtime and persist across restarts.

Supported LLM providers

Supported databases

• SQLite — built-in, no extra dependencies
• MySQL — via pymysql (included in requirements)
• PostgreSQL — via psycopg2 (included in requirements)

Development

source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# Lint
ruff check .

# Format
black --check .

# Test
pytest

# Test with coverage
pytest --cov=app --cov-report=term-missing

Project Structure

app/
  main.py            — FastAPI app, MCP JSON-RPC router
  config.py          — Config from env vars + settings DB
  settings_db.py     — SQLite persistence (providers, settings, chat)
  session_db.py      — Per-session DB switching (db.list/db.use)
  mcp/               — MCP protocol: tools, resources, prompts
  sql/               — SQL executor, policy engine, schema introspection
  llm/               — LLM providers (OpenAI-compat, Anthropic, Ollama)
  assistant/         — Chat assistant service
  web/               — Admin UI (FastAPI + Jinja2 + HTMX)
tests/               — pytest test suite

License

MIT