TernoDBI: Database Intelligence Layer

TernoDBI is a data layer for AI agents, built for security and accuracy. It gives agents one controlled way to read your databases (Postgres, MySQL, Snowflake, BigQuery, Databricks, Oracle, SQLite) and your business tools (Google Ads, GA4, HubSpot, Salesforce, Shopify and more), with access rules enforced on every query.

Run it as a standalone Model Context Protocol (MCP) server — locally over stdio, or hosted over HTTP with OAuth — or embed it in an existing Django project.

Quick Start: Chat with your DB in 5 Minutes

1. Install TernoDBI

   pip install terno-dbi

2. Start the server

   ternodbi start [port]

   By default this starts on 127.0.0.1:8376. On first boot it runs migrations, creates an admin / admin user and a default organisation. It runs in development mode, which is fine on your own machine — see Configuration before exposing it anywhere.

3. Add your database Open the admin panel at http://127.0.0.1:8376/admin and add a datasource. Credentials are encrypted at rest.

4. Generate an access token, bound to your organisation and a user (--org / --user) — an unbound token can't use organisation features such as memory:

   # Query token (read-only, for AI agents)
   ternodbi manage issue_token --name "My Agent" --type query --org default --user admin
   
   # Admin token (schema metadata, memory, organisation prompt)
   ternodbi manage issue_token --name "System Admin" --type admin --org default --user admin

5. Connect your MCP client — see TernoDBI as an MCP Server. To skip self-hosting, use the hosted server instead: Connect to mcp.terno.ai.

6. Start chatting with your data.

Related MCP server: aifordatabase-mcp

Key Features

• Databases: Postgres, MySQL, Snowflake, BigQuery, Databricks, Oracle and SQLite through one API.

• Business tools (API connectors): 17 sources — ads, analytics, CRM, commerce and documents — queried through the same agent tools. See API Connectors.

• Security by default:

  • SQLShield: every query is parsed and rewritten before it runs. Only SELECT is accepted; writes and stacked statements never reach your database.

  • Row-level security: SQL filters (e.g. department_id = 5) are injected into every query, per role.

  • Private tables and columns: hidden from the model's context unless a role is allowed to see them.

  • Scoped tokens: per organisation, per datasource, with expiry; OAuth scopes and an Org Admin check for anything that writes.

• LLM-ready schema:

  • Semantic names: expose Customers instead of t_users_v2_fnl; descriptions for tables and columns.

  • Column statistics: row and null counts, cardinality and common values, to help models write correct filters.

• Memory and organisation prompt: durable facts and instructions that agents read before answering, per organisation and per user.

• MCP, two ways:

  • stdio: separate query (read-only) and admin servers, each with its own token.

  • Hosted HTTP: one server with OAuth 2.1 (dynamic client registration, PKCE, consent screen), plus a preview channel for unreleased tools.

• Large results: server-side cursors stream rows as NDJSON or download them as CSV.

Usage & Core APIs

Running the server

ternodbi start          # default port 8376
ternodbi start 9000     # custom port

ternodbi start runs the REST API and admin panel. To also serve MCP over HTTP (/mcp), run the ASGI app — see Hosted over HTTP.

Sharing the database with an existing Django project

If your Django project embeds terno_dbi.core and uses SQLite, the standalone server can read and write the same database file:

DJANGO_PROJECT_PATH=/path/to/your/django/project ternodbi start

This uses /path/to/your/django/project/db.sqlite3.

Management commands

Always pass --org / --user so the token has an identity:

# Query token that expires in 30 days
ternodbi manage issue_token --name "Claude Agent" --type query --expires 30 --org acme --user alice

# Admin token
ternodbi manage issue_token --name "System Admin" --type admin --org acme --user alice

# Token restricted to one datasource
ternodbi manage issue_token --name "Finance Data Only" --type query --datasource 1 --org acme --user alice

ternodbi manage runs any Django management command (migrate, createsuperuser, …).

Query API

Every request carries Authorization: Bearer <token>. Datasources can be addressed by ID or display name.

POST /api/query/datasources/1/query/
{
    "sql": "SELECT name, email FROM Customers WHERE country = 'DE'",
    "max_rows": 500
}

Queries use public (semantic) names and are rewritten by SQLShield for the caller's role. Results are capped at MAX_QUERY_ROWS (10,000 by default) with a 300-second timeout; both are configurable in DBI_LAYER.

TernoDBI as an MCP Server

Query tools (read-only)

Admin tools

The server also provides prompts (explore-datasources, build-a-query, schema-health) and resources (ternodbi://docs, ternodbi://changelog). The API-connector tools are listed under API Connectors.

Connect to the hosted server (mcp.terno.ai)

No install needed: point any MCP client that supports Streamable HTTP at the hosted server. The first time you connect, your client opens a browser to sign in with your Terno account and choose an organisation (OAuth 2.1); no API key is pasted anywhere.

It is also listed in the official MCP Registry as io.github.terno-ai/terno.

Claude Code

claude mcp add --transport http terno https://mcp.terno.ai/mcp/preview

Claude (Desktop or claude.ai): Settings → Connectors → Add custom connector, and paste https://mcp.terno.ai/mcp/preview.

VS Code (GitHub Copilot): add to .vscode/mcp.json:

{
  "servers": {
    "terno": {
      "type": "http",
      "url": "https://mcp.terno.ai/mcp/preview"
    }
  }
}

Cursor: add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "terno": {
      "url": "https://mcp.terno.ai/mcp/preview"
    }
  }
}

Then ask: "Show me the available datasources."

Local (stdio): connecting Claude Desktop

1. Install Claude Desktop and open Settings → Developer → Edit Config.

2. Mint a query and an admin token (see Management commands) and add:

{
  "mcpServers": {
    "ternodbi-query": {
      "command": "uvx",
      "args": ["--from", "terno-dbi", "dbi-mcp", "query"],
      "env": {
        "TERNODBI_API_URL": "http://127.0.0.1:8376",
        "TERNODBI_API_KEY": "dbi_query_YOUR_TOKEN_HERE"
      }
    },
    "ternodbi-admin": {
      "command": "uvx",
      "args": ["--from", "terno-dbi", "dbi-mcp", "admin"],
      "env": {
        "TERNODBI_API_URL": "http://127.0.0.1:8376",
        "TERNODBI_API_KEY": "dbi_admin_YOUR_TOKEN_HERE"
      }
    }
  }
}

3. Restart Claude Desktop and ask: "Show me the available datasources."

If you started TernoDBI on another port, update TERNODBI_API_URL.

Hosted over HTTP with OAuth

Hosted, both tool sets are one server over Streamable HTTP. Users sign in with OAuth 2.1 — dynamic client registration, PKCE, and a consent screen where they pick the organisation — so no API key is pasted into the client. Write access needs both a write scope and the Org Admin role, re-checked on every request.

pip install 'terno-dbi[http]'
uvicorn terno_dbi.server.asgi:application --port 8376

This serves two release channels: /mcp (stable: released tools, changes only on purpose) and /mcp/preview (everything, including tools not yet released on stable). See the MCP guide for OAuth discovery, scopes and releasing tools.

API Connectors

Besides databases, TernoDBI connects to business tools and queries them through the same agent workflow:

Connecting a source. An organisation admin opens /connect?connector=<key> (for example google_ads), signs in with the provider, and chooses which of their accounts TernoDBI may query. Tokens are stored encrypted and refreshed automatically. The server needs an OAuth app for each provider you enable:

Register <your server>/connectors/oauth/callback/ as the redirect URI with each provider.

Querying. Agents use list_accounts (only the accounts the admin allowed), list_fields (dimensions and metrics), data_query (returns a query_id) and get_query_results. Requests are rate-limited per organisation and source.

Write actions. Some sources support changes such as pausing a campaign (list_actions, execute_action). Every write needs all of: the connector:write scope, the Org Admin role, and writes enabled on that specific account (off by default). dry_run validates with the provider without applying, and every real write is recorded in an audit log.

On the hosted server the connector tools are currently on the /mcp/preview channel.

Configuration

The standalone server reads these environment variables (full list in the Setup Guide):

Before running anywhere other than your own machine:

• Set DBI_DEBUG=False, a random DBI_SECRET_KEY, and DBI_ALLOWED_HOSTS.

• Set MCP_ENCRYPTION_KEY — with development mode off, credentials can't be stored without it. Generate one with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" and keep it safe: losing it makes stored credentials unreadable.

• Change the admin / admin password created on first boot.

• Serve over HTTPS.

Advanced Integrations

Inside your Django project

1. pip install terno-dbi

2. Add 'terno_dbi.core' to INSTALLED_APPS.

3. Add 'terno_dbi.middleware.ServiceTokenMiddleware' to MIDDLEWARE, after AuthenticationMiddleware — without it, API tokens are not authenticated.

4. Set MCP_ENCRYPTION_KEY in your settings.

5. Include the URLs, e.g. path('api/', include('terno_dbi.core.urls')), and run python manage.py migrate.

The services and models are then usable directly from your views and tasks. See the Django Integration Guide for settings and customisation.

Custom AI agents (LangChain, AutoGen, OpenAI Agents SDK)

Any agent can use the REST API without an MCP host:

1. Issue a query token for the agent.

2. List datasources (/api/query/datasources/), then tables and columns for the one you need.

3. Put that schema in the prompt, send the generated SQL to /api/query/datasources/{ds}/query/, and retry on SQLShield errors.

Working examples: src/terno_dbi/examples/agents/. pip install 'terno-dbi[agents]' installs LangChain, LangGraph, CrewAI and AutoGen; the OpenAI Agents SDK example needs that SDK installed separately.

Documentation

• Setup Guide

• System Architecture

• MCP Integration

• Security & SQLShield

• Django Integration

• API Reference

• Changelog

Development

git clone https://github.com/terno-ai/ternodbi.git
cd ternodbi
pip install -e '.[dev,http]'
pytest tests/unit
ruff check src tests

See CONTRIBUTING.md.

Contributing

Contributions are welcome — bug reports, connectors, docs and fixes. Read CONTRIBUTING.md for setup, tests and what we look for in a pull request.

Security

Please don't report vulnerabilities in public issues. See SECURITY.md for how to report them privately.

Community & Support

• Issues for bug reports and feature requests.

• Discussions for questions and ideas.

License

TernoDBI is open source under the Apache 2.0 License. See LICENSE.