The open-source ontology layer for AI agents.
Connect the systems you already run, dissect them into business terms and relationships, certify the result, and publish it as MCP servers — for ibl.ai agents, Claude, Codex, and any other MCP client. One ontology. Every system. Your server, your data, any agent.
Ubuntu 22.04, 24.04 or 26.04 on x86-64 · four blocks to paste · built on your server from this source → looking after the server
▶︎ Watch the demo · Install it on your own server and connect a database to an agent
▶︎ Watch the HTTP API demo · Connect the data source, create an MCP, and connect to an agent in 3 minutes
Why ibl.ai/ontology · Every system · Features · How it works · Case studies · Screenshots · Quick Start · Deployment · Architecture · FAQ
SOC 2 Type II · Universities, enterprises, and governments run on ibl.ai — read the case studies →
| Why | What it means |
|---|---|
| 🔓 Your code, your data | MIT-licensed and built from this source on your own server. The ontology, the database passwords and the MCP servers stay in your network, and ibl.ai/ontology keeps no database of its own. |
| 🧭 One ontology, every system | SQL connections and HTTP API connections become one set of business terms and relationships: a Student is the same Student in the SIS, the LMS and the CRM. |
| ✅ People certify, agents call | The engine suggests terms, joins and metrics, and a person certifies them. A certified term becomes a tool with a fixed definition and fixed SQL, so an agent picks the right one and cannot widen it. |
| 🤖 Any agent, over MCP | ibl.ai agents, Claude, Codex, Cursor or your own code call the same endpoint, and each caller sees only the toolsets its grant reaches. |
| 🏢 Enterprise-ready | Read-only SQL connections, ibl.ai SSO and RBAC, Microsoft Entra ID, Google and custom OIDC, allowed origins and hosts, API keys limited to toolsets, rate limits, and a log of every call and every refusal. |
| 🧩 Built on proven engines | NVIDIA auto-ontology infers the terms, Google MCP Toolbox serves the tools, and the ibl.ai platform provides sign-in, roles and agents. |
Most agent integrations are wired one system at a time. ibl.ai/ontology reads the systems you already run into one set of terms, and serves them to every agent.
| System | Status | |
|---|---|---|
| PostgreSQL | 🐘 | Dissected into terms and served as tools |
| MySQL | 🐬 | Dissected into terms and served as tools |
| Snowflake | ❄️ | Dissected into terms and served as tools |
| ClickHouse | ⚡ | Dissected into terms and served as tools |
| HTTP APIs | 🌐 | Any system with an HTTP API, served as named tools from an OpenAPI document or the endpoints you name |
| Filesystem | 📁 | A folder or file on your server, served as tools to list and read text files; not dissected |
| Trino · Databricks | 🧱 | Dissected into terms and shown on the map; not served as tools |
| DuckDB · HeavyDB · Kyuubi · SQLite | 🔜 | SQL connections coming soon |
| SQL Server · Oracle · BigQuery | 🔜 | SQL connections coming soon |
An HTTP API connection reaches everything else. If a system has an HTTP API, it can be connected today, with no connector to wait for: a CRM, an SIS, an LMS, a ticketing system, a SaaS product or a service you wrote yourself. Point at its OpenAPI document and tick the endpoints, or name them by hand; each becomes a tool. Reads and writes go in separate toolsets, so you decide per agent whether it may only look or also act, and the upstream credential stays on your server.
On the other side, anything that speaks MCP can call it: ibl.ai agents, attached in one dialog; Claude Desktop and Claude Code; Codex CLI; Cursor and Windsurf; your own code with the MCP SDK; cURL (connecting agents).
|
🔌 Connect
🧠 Dissect & model
|
🚀 Publish & serve
🔐 Govern & operate
|
Five steps, one page each. docs/console.md walks through every page with screenshots.
| Step | Page | What happens |
|---|---|---|
| 1 · Connect | Systems | Add a SQL connection or an HTTP API connection. SQL connections are read-only, as a security measure. The password is saved on your server. |
| 2 · Dissect | Map | The engine reads the tables and names the business terms above them. Terms that span several systems are called out. |
| 3 · Model | Ontology | Review what was inferred and certify it: object types, their properties, links and metrics. |
| 4 · Expose | MCP Gateway → New MCP Server | Pick the toolsets, how callers sign in, and the allowed origins and hosts. The config file is shown as it will be written. |
| 5 · Serve | MCP Gateway → the server | Deploy, attach it to an ibl.ai agent or paste a snippet into Claude, Codex or Cursor, and watch the calls arrive. |
| For | ibl.ai/ontology uses |
|---|---|
| Inferring terms, joins and metrics | NVIDIA auto-ontology 1.2.0, as NVIDIA's own published images, with a Postgres of its own |
| Serving tools over MCP | Google MCP Toolbox 1.16.0, one process per MCP server on your server's loopback |
| Sign-in, roles, API keys and agents | The ibl.ai platform, through @iblai/iblai-js; the shell matches os.ibl.ai |
| The pages, the host API and the MCP gateway | Next.js 16 and React 19, in this repository |
Universities, enterprises, and government agencies build on ibl.ai — deploying agents on their own infrastructure, with their own models, at a fraction of the cost of closed platforms.
The Map — tables under the business terms the engine named, clustered by system
Every page and tab, with what each control does → docs/console.md
This runs ibl.ai/ontology in demo mode: sample data, with no ibl.ai account and no engine. For the real thing, see With a real engine or Deployment.
git clone https://github.com/iblai/ontology.git
cd ontology
pnpm install
NEXT_PUBLIC_DEMO=1 pnpm dev # demo modeUsing Claude Code? Read AGENTS.md first: this is Next.js 16, and its conventions differ from earlier releases.
Open http://localhost:3000. Demo mode needs no ibl.ai account and no
engine: it uses a fixed session and the sample data in lib/mock.ts, and the SDK
panels show a notice. Node.js 26 and pnpm 12, as .tool-versions names them;
mise brings both with mise install.
On one host, as a developer runs it: the pages and the server half (the host API, the MCP gateway, Toolbox and their files) on one origin.
-
Start the engine from a checkout of NVIDIA/auto-ontology. Fill in its
.envas its README says, but setAPP_URL=http://localhost:3100and leaveCONNECTION_STRINGSempty. The override runs the engine on the host's network (a Linux host), with its web app on127.0.0.1:3100and every service listening on loopback only, so a database on this machine is reached at127.0.0.1by the engine and by ibl.ai/ontology alike (Docker Compose 2.24.4 or later):docker compose -f docker-compose.yml -f <this repo>/deploy/auto-ontology.override.yml up -d --build
-
Give ibl.ai/ontology the engine's key, one of two ways. Sign in at http://localhost:3100 as the engine's admin, open the user menu → API Tokens → New token, and copy it into
AO_API_KEY(it is shown once; an admin's token is needed for the model export). Or leaveAO_API_KEYout and setAO_ADMIN_EMAIL,AO_ADMIN_PASSWORD_FILE(a file holding the admin's password) andAO_ORIGIN=http://localhost:3100: it then signs in as the admin and makes its own key on the first call that needs the engine. -
Start it:
cp .env.example .env.local # set ONTOLOGY_PLATFORM, and AO_API_KEY or the admin's sign-in pnpm dev # http://localhost:3000 → signs in with ibl.ai
ONTOLOGY_PLATFORMis the key of the ibl.ai platform the engine belongs to. WithAO_URLset and noONTOLOGY_PLATFORMthe dev server refuses to start. Any other platform you sign in to is answered403"This server serves another platform."
One engine serves one platform. To serve several from one host, leave AO_URL and
ONTOLOGY_PLATFORM unset and write each platform's engine, on another machine, to
$ONTOLOGY_HOME/platforms/<platform>/engine.json as {"url": "...", "key": "..."}
(docs/network.md).
ibl.ai/ontology runs on your own server, inside your network. The ibl.ai platform provides sign-in, roles, API keys and agents; your server keeps the ontology, the database passwords and the MCP servers. One server serves one platform.
Platforms are hosted on api.iblai.app unless yours runs its own ibl.ai deployment, and the
install points there by default. A self-hosted platform is under Advanced.
-
Install it on a fresh Ubuntu server
docs/install.md is the whole install: four blocks to paste. The first one names your platform and the name the server answers at, and nothing starts without the platform:
ONTOLOGY_PLATFORM=example-university ONTOLOGY_HOST=ontology.example.edu
ibl.ai/ontology is built on the server from this repository and run by systemd (
deploy/iblai-ontology.service); NVIDIA's engine with its database, and Caddy for TLS, run beside it in Docker (deploy/compose.yaml). Nothing of ibl.ai's arrives as a prebuilt image.Or with Docker alone. Build ibl.ai/ontology's image on the server from this repository's
Dockerfileand let Compose run it beside the engine: no Node on the server, and still nothing prebuilt from ibl.ai (docs/install_docker_local.md).Or on a machine of your own. With no host name and no Caddy, with Docker or with none, at
http://localhost:3000on that machine only (docs/dev_local.md). -
Sign in
Open
https://<host>/and sign in as an administrator of that platform. The server serves the pages, the host API and the MCP gateway, which agents call athttps://<host>/<platform>/<slug>/mcp. -
Look after it
Settings, giving the engine a model, upgrades, backups and what to do when something stops are in docs/operations.md, which also covers running ibl.ai/ontology as an image instead: one built on your server, or ibl.ai's prebuilt one (
COMPOSE_PROFILES=all-in-one, with the optionaldeploy/install.sh). What talks to what is in docs/network.md.
Note: ibl.ai/ontology requires the ibl.ai platform for sign-in, roles, API keys and agents. The platform is not included in this repository — visit ibl.ai to get started.
- A block of the install fails. Blocks 2, 3 and 4 can be pasted again as they are (docs/install.md).
- Something stops later.
sudo journalctl -u iblai-ontology -n 30says why for ibl.ai/ontology, andsudo docker compose logs --tail 30 <service>in/opt/iblai-ontologyfor the rest. What each message means is in docs/operations.md.
On a server the settings live in /opt/iblai-ontology/.env, which Docker Compose and
ibl.ai/ontology's service both read (docs/operations.md).
| Setting | Default | What it does |
|---|---|---|
ONTOLOGY_PLATFORM |
None: nothing starts without it | Your platform's key, shown at login.iblai.app/me. The server serves that platform only; another platform's administrator is refused. |
ONTOLOGY_HOST |
localhost |
The host name. Caddy gets the certificate for it. |
ONTOLOGY_DM_URL |
https://api.iblai.app/dm |
The ibl.ai platform's address, where every sign-in and key is checked. |
OPENAI_API_KEY |
Empty | Turns the semantic features on (a model). |
OPENAI_API_BASE_URL |
https://api.openai.com/v1 |
Where the model calls go: OpenAI, or a gateway that speaks its API. |
OPENAI_MODEL |
gpt-4.1 |
The chat model. |
OPENAI_EMBEDDING_MODEL |
text-embedding-3-large |
The embedding model. |
ONTOLOGY_LOCAL_ROOT |
See operations | The one folder a Filesystem source may read. Nothing outside it is listed or read. |
For pnpm dev, .env.example lists every setting of the one-host shape with its
comment.
One codebase: the Next.js 16 app at the repository root, in the ibl.ai shell (the os.ibl.ai header
and sidebar, Open Sans, #0058cc). It has two halves: the pages, and the server half (the host
API under /api/host/*, the MCP gateway, one Toolbox process per MCP server, and their files).
admins' browsers ──┐
ibl.ai agents ─────┼─ 443 ─▶ Caddy (TLS) ─▶ ibl.ai/ontology, 127.0.0.1:3000
Claude · Codex ────┘ pages · host API · MCP gateway at
/<platform>/<slug>/mcp
│ │
▼ ▼
NVIDIA auto-ontology MCP Toolbox
127.0.0.1:3100, with one process per server,
a Postgres of its own on loopback
│ │
▼ ▼
your databases, your databases and
read to build terms HTTP APIs, as tools
outbound: ibl.ai (every sign-in and key is checked there) · your data sources ·
Let's Encrypt · your model's address, if you give it a key
The same code runs three ways:
| Shape | Setting | Behaviour |
|---|---|---|
| Your server | ONTOLOGY_PLATFORM, with the engine in AO_URL |
All of it, built from source beside NVIDIA's engine and Caddy; serves that one platform |
| Pages hosted elsewhere | NEXT_PUBLIC_ONTOLOGY_RELAY=1 at build |
Pages only; every /api/host/* call is forwarded to the platform's server |
| One host run by hand | None, or AO_URL with ONTOLOGY_PLATFORM |
Pages and server half as one process: pnpm dev, or one host behind a TLS proxy |
The topology, the firewall rules and the hardening checklist are in docs/network.md, sign-in in docs/auth.md, and where every value on screen comes from in docs/data-sources.md.
| Path | What it is |
|---|---|
app/(app)/* |
One folder per route: dashboard, systems, map, ontology, mcp, mcp/new, mcp/[slug], agents, roles, access, catalog, sync (Compilation), config |
components/shell/ |
Sidebar, header, page primitives, shell state, the OS-style footer dialogs hosting SDK tabs and the prototype walkthrough stepper |
components/graph/ontology-graph.tsx |
Canvas force graph used on the Map |
components/ui/ |
shadcn components (base-nova on Base UI) |
lib/iblai/, store/, app/(auth)/ |
ibl.ai SSO: session, SDK store, sign-in callback |
lib/host/, app/api/host/ |
The host layer: checks the caller with ibl.ai, proxies the platform's engine, writes its server configs and runs one Toolbox process per server |
lib/host/engine-key.ts |
The server's own engine key: signs in as the engine's admin, makes a key and keeps it in $ONTOLOGY_HOME/engine-key |
lib/host/models.ts, app/internal/models/v1/ |
The loopback model route the engine calls: swaps in the OpenAI model, adds OPENAI_API_KEY and sends the call on |
instrumentation.ts |
The start-up check: a server with AO_URL and no ONTOLOGY_PLATFORM refuses to start |
lib/host/relay.ts |
On the pages-only build, forwards each /api/host/* call to the server the browser names |
lib/server-address.ts |
The x-ontology-server header, a server's address https://<host>/iblai, and the browser's store of it per platform |
app/[platform]/[slug]/mcp/ |
The gateway agents call: origin, credential and toolset checks, then Toolbox |
lib/data.ts, lib/ibl-flows.ts |
What each page reads and does; the ibl.ai writes (roles, policies, API keys, agents) |
lib/mock.ts |
The fixed data demo mode shows |
deploy/compose.yaml |
What Docker runs on a server: NVIDIA's engine as its own published images, Postgres, Caddy and the four generated secrets; ibl.ai/ontology's own image under the all-in-one profile |
deploy/iblai-ontology.service |
The systemd unit of ibl.ai/ontology built from source on the server (docs/install.md) |
deploy/install.sh |
Optional: prepares an Ubuntu server and installs ibl.ai/ontology as an image (docs/operations.md) |
deploy/auto-ontology.override.yml |
For development: runs a local checkout of the engine on the host's network, on loopback, its web app on 3100; not part of a release |
Dockerfile |
ibl.ai/ontology's image: Next's standalone build of the whole app with the Toolbox binary; the ibl.ai addresses are build arguments. Built on your own server (docs/install_docker_local.md), or by ibl.ai as public.ecr.aws/ibleducation/iblai-ontology |
.github/workflows/release.yml |
On every push to main: release-it for the version and the changelog, then a published release with the install files |
.env.example |
Environment settings |
scripts/screenshots.mjs |
Regenerates every screenshot in docs/screenshots/ |
scripts/audit-layout.mjs |
Checks every page at six widths for overflow, overlap and sideways scrolling |
providers/iblai-providers.tsx |
ibl.ai SSO provider chain (see docs/auth.md) |
AGENTS.md |
Rules for coding agents, written by next dev; keep it committed |
docs/ |
The documents listed under Resources |
.claude/launch.json |
Dev-server definition for the Claude desktop preview |
This project is covered by Vitest unit tests beside the code they test, in lib/ and deploy/. Run them for any change so nothing regresses:
pnpm testOther useful commands:
| Command | What it does |
|---|---|
pnpm typecheck |
TypeScript 7 (tsc --noEmit) |
pnpm lint |
oxlint, zero warnings |
pnpm format:check |
oxfmt (pnpm format rewrites) |
node scripts/audit-layout.mjs |
Checks every page at 375, 768, 1024, 1280, 1440 and 1920 px for overflow, overlap and sideways scrolling (with NEXT_PUBLIC_DEMO=1 pnpm dev running) |
node scripts/screenshots.mjs |
Regenerates every screenshot in docs/screenshots/ (with NEXT_PUBLIC_DEMO=1 pnpm dev running) |
If you run your own ibl.ai deployment, point the server at it: ONTOLOGY_DM_URL in the server's
.env, and that deployment's addresses in .env.local before the build
(docs/operations.md). If you need the full
backend, reach out at ibl.ai/contact for an enterprise license and
deploy it with iblai/infra-cli.
The pages can also be hosted apart from the server. Built with NEXT_PUBLIC_ONTOLOGY_RELAY=1,
ibl.ai/ontology serves pages only and forwards every /api/host/* call to the platform's server
at https://<host>/iblai, which an administrator connects under Connect a server
(docs/operations.md).
Getting started · Connections · Security and data · Models · Agents and access · Running it
Yes. Watch the demo and the HTTP API demo, or run demo mode from the Quick Start: sample data, no account and no engine.
Yes: an ibl.ai platform and an administrator of it. Sign-in, roles and API keys are checked there.
Your platform's key is shown at login.iblai.app/me.
ibl.ai/ontology is MIT-licensed. The ibl.ai backend platform it signs in with is separate (ibl.ai/contact).
An agent gets certified business terms, each a tool with a fixed definition and fixed SQL, and it reaches only the toolsets its grant names.
| Connection | Systems | Status |
|---|---|---|
| SQL | PostgreSQL, MySQL, Snowflake, ClickHouse | Dissected into terms and served as tools |
| SQL | Trino, Databricks | Dissected and shown on the map; not served as tools |
| SQL | DuckDB, HeavyDB, Kyuubi, SQLite, SQL Server, Oracle, BigQuery | Coming soon |
| HTTP API | Any system with an HTTP API | Served as tools today, with no connector to wait for |
| Filesystem | A folder or file on your server | Text files served as tools; not dissected |
More: connect data sources.
Yes, if it has an HTTP API. An HTTP API connection needs no connector: give it the base URL and an OpenAPI document, or name the endpoints by hand.
More: connect data sources, the HTTP API demo.
Not by default. SQL connections are read-only, as a security measure.
With an HTTP API connection you can choose to let an agent modify data: the endpoints that write go in a toolset of their own, which stays off until you tick it on an MCP server. An agent then reaches it with a key granted that toolset by name, or with a platform admin's own key.
More: permissions.
Yes, text files. A Filesystem connection serves one folder or file under ONTOLOGY_LOCAL_ROOT as
two tools, one to list a folder and one to read a file. Files whose name starts with a dot are
never read, and PDF, Office files and images are not read at all.
More: connect data sources.
No. ibl.ai/ontology runs on your server, and the ontology, the passwords and the MCP servers stay there.
If you give the engine a model key, its model calls go to the address you set, with the samples of personal columns masked first.
On your server only: in a file that its service alone can read, and in the engine's own database.
More: connect data sources.
No data is exposed by default. Only ports 80 and 443 are open, through Caddy, and anything behind them that returns data asks for a sign-in or a key.
NVIDIA auto-ontology engine, the engine's database and every MCP server's process listen on the server's loopback only.
More: network.
Columns that look personal are tagged and flagged in the Ontology, and you decide per toolset which tools may return them.
More: permissions.
Yes, three ways:
- by the toolsets a grant names,
- by the certified SQL, which a caller cannot widen,
- by binding a parameter to a claim of the caller's verified sign-in.
More: permissions.
Yes. Every tool call and every refusal is logged on your server and shown under Activity, and the log can be shipped to your SIEM.
More: permissions.
It is not required. Connecting a system, the map, certifying terms and the tools all work without one.
An OpenAI API key turns on the semantic features of NVIDIA auto-ontology, such as inferred joins
and questions in plain words: set OPENAI_API_KEY in the server's
.env.
No. The engine calls a route on the server's loopback, and ibl.ai/ontology adds your key and sends the call on.
More: a model.
Yes: any gateway that speaks OpenAI's API, set in OPENAI_API_BASE_URL. The embedding model must
be able to answer in 2048 dimensions.
More: a model.
ibl.ai agents, Claude Desktop and Claude Code, Codex, Cursor, and anything else that speaks MCP.
More: connect agents.
Yes, once their origin is on the server's Allowed Origins.
More: connect agents.
With ibl.ai credentials, Microsoft Entra ID, Google or a custom OIDC issuer, chosen per MCP server.
More: permissions.
Each caller sees only the tools in the toolsets its grant reaches, so two people can get different lists from the same address.
More: permissions.
Revoke the key under Tokens & Origins on the server's page, or remove the group from the toolset's policy on ibl.ai.
More: walkthrough.
Yes: 120 requests or 30 tool calls a minute, per caller.
More: connect agents.
Ubuntu 22.04, 24.04 or 26.04 on x86-64 is recommended, 4 GB of memory, 15 GB free, and ports 80 and 443 open.
More: install.
Yes, on a machine of your own, with Docker or without it. It answers at http://localhost:3000
on that machine only, still needs the internet for ibl.ai sign-in, and ibl.ai's agents cannot
call it.
More: run it on your own machine.
Only NVIDIA's engine, its Postgres and Caddy run in Docker. ibl.ai/ontology itself is built on
your server from this repository. It can run in Docker too, as an image you build on your server
from this repository's Dockerfile. On a machine of your own it can also run with no Docker at
all, the engine built from NVIDIA's source.
More: install, the Docker install, your own machine.
No. One server serves one platform.
More: network.
Yes. Each MCP server keeps its revisions, and Roll Back puts the previous one back.
More: walkthrough.
See Day to day in the operations guide.
We welcome contributions! Open an issue or a pull request. Before you push, run pnpm format:check, pnpm lint, pnpm typecheck and pnpm test. If you'll be working with AI-assisted tooling, read AGENTS.md first — it holds the Next.js 16 rules that next dev writes for coding agents.
- Documentation
- ibl.ai/ontology — the product page
- Install — four blocks to paste on a fresh Ubuntu server
- Install with Docker, built locally — the same four blocks, with ibl.ai/ontology as an image built on the server
- Operations — looking after that server: settings, a model, upgrades, backups, the image, failures
- Walkthrough — every page with screenshots, and what each control does
- Connect data sources — SQL and HTTP API connections: read-only logins, scope, PII, what Connect & Dissect does, troubleshooting
- Permissions — policies and toolsets, sign-in methods, row-level restriction, PII, writes, origins, audit
- Connect agents — ibl.ai agents, Claude Desktop and Claude Code, Codex, Cursor, Python, cURL
- Authentication — ibl.ai SSO: the session as iblai/os implements it, how it is wired here, configuration, demo mode
- Network — topology, inbound, outbound to
ext.ibl.aiand data sources, what runs where, hardening - Data sources — where every value on screen comes from, and where each thing is saved
- ibl.ai/os — the agent platform whose agents call these servers
- NVIDIA auto-ontology — the engine that infers terms, joins and metrics
- Google MCP Toolbox — the runtime that serves the tools