Terno

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

1. 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.

1. Add your database Open the admin panel at http://127.0.0.1:8376/admin and add a datasource. Credentials are encrypted at rest.
2. 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](#ternodbi-as-an-mcp-server). To skip self-hosting, use the hosted server instead: [Connect to mcp.terno.ai](#connect-to-the-hosted-server-mcpternoai).

1. Start chatting with your data.

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](#hosted-over-http-with-oauth).

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 . 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= (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:

| LinkedIn | TERNO_LINKEDIN_CLIENT_ID, `TERNO_LINKEDIN_CLIENT