SQL Database Bridge

This local Codex plugin exposes configured SQL databases through a small MCP stdio server. SQLite works with Python's standard library. SQL Server/MSSQL, PostgreSQL, and MySQL are optional adapters.

This repository is the open-source client/plugin. Account login, billing, entitlements, OAuth, and hosted PostgreSQL remain on the SQL Bridge portal at https://sql-bridge.lovable.app.

Install from source

Clone this repository and install the adapters into the same Python runtime that launches the MCP server:

python -m pip install -r .\requirements.txt

Microsoft SQL Server also requires Microsoft's ODBC Driver 17 or 18 installed on the desktop. The plugin never installs drivers or packages automatically.

For a bundled local runtime, run the platform installer once from the plugin directory:

.\install.ps1

On macOS or Linux:

./install.sh

The installer creates a local .runtime environment containing the Python adapters. The launcher automatically uses it for MCP requests. The Windows release bundle can be built with .\build_windows_bundle.ps1; it includes the Python adapters in a standalone executable. Microsoft SQL Server's ODBC driver remains a separately installed Microsoft prerequisite.

Execution modes

The Lovable app is the account, billing, entitlement, and hosted MCP control plane. Both execution modes require the same authenticated Lovable account and active entitlement. Local desktop mode is the default: SQL connections stay on the desktop, but every local SQL tool call is still gated by a Lovable OAuth login and the hosted get_account_access check. Local mode is not an authorization bypass.

The hosted endpoint is baked into the plugin as the default:

https://sql-bridge.lovable.app/mcp

Use LOVABLE_MCP_URL to override it for another deployment. To select the hosted advanced mode, set SQL_BRIDGE_MODE=remote (or hosted) before starting the MCP process. Hosted mode exposes Lovable's cloud PostgreSQL tools. Set SQL_BRIDGE_MODE=local only when you want to make the local default explicit.

The first call to login_platform opens the SQL Database Bridge platform account login in a browser (login_lovable remains a legacy alias). The plugin reads the app's protected resource metadata, follows its advertised Supabase Auth issuer, uses the issuer's /.well-known/oauth-authorization-server metadata, registers a native client with DCR, and completes PKCE login. LOVABLE_OAUTH_ISSUER is only an optional override. The bridge persists the refresh token in the OS keyring when available, with Windows DPAPI as the secure fallback, so a new MCP process reuses the linked account instead of reopening browser approval.

The current Lovable MCP manifest publishes eight tools: echo, list_connections, get_connection, test_connection, list_schemas, list_tables, describe_table, and run_query, plus the metadata-sync tools upsert_connection and delete_connection. The proxy discovers the live manifest after login and also advertises this known surface during first-run login so MCP clients that cache tools/list can continue.

Hosted execution currently supports PostgreSQL. Lovable returns a clear unsupported-driver error for MySQL, MSSQL, and SQLite; use the default local mode when the database is on the desktop or when those drivers are required.

Hosted query flow

1. Call login_platform once. The browser handles the platform/Google/email login; the plugin stores the resulting refresh token in the operating-system keyring and checks entitlement before SQL execution.
2. Call list_connections and choose a connection id. Connection metadata is RLS-scoped to the authenticated user and secrets never leave the hosted backend.
3. Use test_connection, list_schemas, list_tables, or describe_table as needed.
4. Call run_query with a UUID, SQL, optional parameters, and an optional row limit:

{
  "connection_id": "3f2c...",
  "sql": "select id, email from users where created_at > $1 limit 50",
  "params": ["2026-01-01"],
  "row_limit": 1000
}

run_query is read-only, rejects multi-statement input, applies a statement timeout, and returns bounded results with columns, rows, rowCount, truncated, and duration_ms in structured content.

Local connection metadata sync

In local mode, the database connection and password remain on the desktop. The plugin synchronizes only non-secret metadata with Lovable:

• connect_database automatically calls upsert_connection and persists the returned UUID.
• list_connections and sync_connections pull remote metadata and push unsynced local metadata.
• Connections created elsewhere appear locally as needs_credentials: true; supply credentials locally with connect_database before using them.
• delete_connection removes the local connection and calls the hosted delete_connection tool.
• close_connection only closes the current session and leaves metadata available for later reattachment.

The local sync file is user-local and contains metadata only. It never stores passwords, secret ciphertext, or credential-bearing connection strings. Local sync still requires login_platform and an active platform entitlement.

Configure databases

For environment-configured local connections, set SQL_DATABASE_URLS to a JSON object before starting Codex, for example:

$env:SQL_DATABASE_URLS = '{"main":"sqlite:///C:/data/app.db","analytics":"postgresql://user:password@localhost:5432/analytics"}'

You can use SQL_DATABASE_URL for one database, which is exposed as default.

Install optional drivers when needed:

python -m pip install pyodbc "psycopg[binary]" pymysql

The command must target the same Python executable used by the MCP server. If the server reports that pyodbc is missing, run python -m pip install pyodbc once in that runtime; the plugin does not silently install packages or make network changes during a database connection.

For MSSQL, also install Microsoft ODBC Driver 18 or 17 for SQL Server on the desktop. The server automatically prefers Driver 18 and falls back to Driver 17 when no explicit driver is supplied. The desktop bridge can pass a connection directly to connect_database, so credentials do not need to be stored in SQL_DATABASE_URLS or in the plugin files. Example SQL authentication profile:

{
  "name": "mssql-main",
  "engine": "mssql",
  "server": "sql01.example.com",
  "port": 1433,
  "database": "Sales",
  "authentication": "sql",
  "username": "report_reader",
  "password": "<provided by the bridge>",
  "trust_server_certificate": false,
  "encrypt": true
}

For Windows authentication, omit username/password and use "authentication": "windows". The current Windows user running the MCP process is used by the ODBC driver. This requires the Codex desktop process and the target SQL Server to support that user's Windows identity.

Runtime connect_database profiles are held only in memory for the MCP process. Call close_connection when finished. A password passed in a tool call may still be visible to the host application's logs or transcript, so the desktop bridge should apply its own authorization, redaction, and confirmation policy before forwarding credentials.

In local mode, list_connections, connect_database, list_tables, describe_table, query_sql, and close_connection return an authentication or account-access error until login_platform succeeds and the hosted get_account_access check reports entitled: true. Set LOVABLE_ENTITLEMENT_TOOL only when using a compatible deployment with a different tool name.

For a LocalDB connection, the bridge can send this compact profile. The connection name defaults to main, the engine is inferred as MSSQL from server, and encryption defaults to off for LocalDB:

{
  "server": "(localdb)\\MSSQLLocalDB",
  "database": "eMeditDb",
  "authentication": "windows"
}

The tool also accepts a nested connection object and aliases such as host, database_name, auth, and encryption. If a LocalDB instance rejects encryption, the bridge retries once with Encrypt=no by default; set allow_localdb_encryption_fallback to false to disable that behavior.

The default local server exposes connect_database, list_connections, sync_connections, delete_connection, list_tables, describe_table, query_sql, and close_connection. Read-only statements are the default. Set SQL_ALLOW_WRITE=true only for a database where write access is intentional. SQL_MAX_ROWS limits returned rows and defaults to 500.

Run the server directly

$env:SQL_DATABASE_URL = 'sqlite:///C:/data/app.db'
python .\server.py

The .mcp.json file launches the same server from Codex with stdio transport.