iblai/ontology

Mirrored from iblai/ontology · README.md. This page is generated — edit it in the repository, not here.

On-premise knowledge layer that makes an organization's existing systems queryable by AI agents over MCP — no data extraction.

Google MCP Toolbox NVIDIA auto-ontology

---

What it is

iblai/ontology is a knowledge layer that runs inside your network. It makes the systems you already run queryable by AI agents over the Model Context Protocol (MCP): databases (Oracle and PeopleSoft, PostgreSQL, MySQL, SQL Server), warehouses and analytics engines (Snowflake, Trino, ClickHouse), and SaaS applications through a small connector each (Canvas, Slate, Twenty CRM, and others you add).

The prevailing approach extracts your data through a VPN tunnel into a vendor cloud. iblai/ontology does the opposite: the copy that agents query, the permissions and the logs stay on a server you own. The agent runtime, where the models run, is a separate concern and can be anywhere; it reaches the knowledge layer over MCP, one authorized request at a time.

You will have your data, and we may not even have access to it.

It is domain-agnostic: the same stack serves a university, an enterprise, a school district, a government agency, a law firm, a financial firm or a hospital (see What it connects to).

At a glance

How it works

The picture at the top shows every runtime connection. The numbers in parentheses are its numbers.

1. A system is connected read-only. Your team gives the Ontology Backend a read-only login for a database, or an API key for a SaaS system. A database is first put to a test: seven kinds of write are attempted, and all seven must be refused before any of its data is copied (10).
2. Its structure is discovered and reviewed. The backend reads the tables, columns and keys, then drafts what to copy, how often, and which questions agents may ask. Nothing is served until your team approves it.
3. The Sync Engine copies on a schedule. It reads the approved tables or API objects (8) and writes three things on your server (9): rows in Cache Postgres, one Markdown file per record in Memory Files, and a search index over those files. The copy is as fresh as the schedule you set.
4. Agents ask through one gateway. An agent calls the MCP Gateway over HTTPS (4). The gateway checks who is calling and in which role, then answers from Memory Files (7), from the cache (0), or by running one of that role's predefined queries through the MCP Toolbox (6, 14).
5. A change happens only through a named operation. Out of the box agents only read. To let an agent release a hold or add a note, your team writes that one operation, runs it on a login or API key created for that purpose, and grants it by name to the roles that need it. A connector can bring its operations with it: connecting Twenty CRM adds creating and updating people, companies, opportunities, notes and tasks, and no deleting. Those are granted by name too: connecting Twenty CRM makes one role that holds them, and no agent has that role until you connect one as it. An agent fills in an operation's inputs and nothing else.
6. Each tool call is recorded: who called, in which role, which tool, allowed or refused, when and from where. A change is recorded before it runs, with its inputs.

Where your data lives

The search index is built on your host. Text is turned into vectors by a small open model that runs locally (ChromaDB's built-in one, downloaded once), not by an outside service.

Three choices send more than answers. Each is yours:

• Keeping settings in your ibl.ai platform. The platform then holds the roles, the sync schedules and the service registry: the list of connected systems with the names of their tables and columns, and their test and health results. It never holds source records. A system's login is stored there only encrypted, and the key stays on your host. The audit log and the sync history stay on your host either way. A server set up with the one-command install works this way where your platform can hold these settings. Where it cannot yet, the install says so: the roles are kept in the platform and the rest stays on the server.
• An LLM to help map a schema. It is off until you configure a provider: your own Anthropic or OpenAI account, or your ibl.ai platform. Schema analysis sends table and column names. The table-mapping step also sends up to five sample rows per table. Left off, discovery uses built-in rules (16).
• The admin console hosted by ibl.ai. If your administrators use it instead of a console on your host, what they view passes through that service on the way to their browser (1). It reaches your server at the address an administrator gives it once. Your platform keeps that address, or, where the platform cannot yet, that administrator's own browser does.

Administrators sign in with their ibl.ai account. The Ontology Backend asks the platform whether the token is valid and whether the person is an administrator of the platform it is configured for (2, 3).

Security and governance

The settings behind these are in docs/deployment.md; how access is decided is in docs/authorization-model.md.

Built with Google MCP Toolbox and NVIDIA auto-ontology

Two open-source projects do work that iblai/ontology does not do itself.

How Google MCP Toolbox applies. It is the governed query layer between agents and SQL. Each query an agent may run is written down in advance with its parameters, by your team or drafted by discovery for your team to review, and queries are grouped into toolsets that roles are granted. When an agent calls one, the MCP Gateway first decides whether that caller's role may. Only then does it pass the call to the Toolbox, which fills in the parameters, runs the statement on the cache or on the source, and returns the rows. A change is the same thing with a different statement: an update or an API request your team wrote in advance, never text an agent composes. The Toolbox is not reachable from outside the host: agents talk to the gateway, never to it. One exception is deliberate: free SQL against the local cache is run by the gateway itself, read-only, under the limits listed above.

How NVIDIA auto-ontology applies. Support for Snowflake, Trino and ClickHouse is built on auto-ontology's database connectors; iblai/ontology has no driver of its own for those three. Through them the same steps run as for any other database: the read-only test, the discovery of tables, columns and keys, and the scheduled copy. That is all of it. auto-ontology's own semantic layer, server and store are not used; here a schema is interpreted by iblai/ontology's rules and, if you turn it on, an LLM. Two things follow for these three engines. Their row counts are not reported, so they show as zero. And an engine is offered only when the MCP Toolbox can serve it too, which is why Databricks and DuckDB, which auto-ontology can also read, are not.

The rest of the stack:

What it connects to

• Databases, directly: Oracle (including PeopleSoft), PostgreSQL, MySQL, SQL Server, Snowflake, Trino and ClickHouse.
• API systems, through a small connector each. Connectors ship for Canvas, Slate, EAB Navigate and LDAP.
• Twenty CRM, from the admin console. It connects with its address and an API key, on Twenty's cloud or your own server. Its data starts arriving at once, and agents can then also create and update its records. Connecting it also makes the role an agent is given for that.
• Everything else in the catalog is a starting point. The built-in catalog holds a definition for the common systems of seven sectors: how to connect, which read-only operations exist, a suggested schedule. For a system without a shipped connector, that definition is what its connector is written from.

What a deployment takes

There are two ways to set it up.

With your ibl.ai platform and the hosted console: one command on a fresh server. The console shows the command and makes the key the install asks for. You provide:

• A fresh Ubuntu server. The install adds Docker if it is missing and leaves one folder with two files; everything else it brings lives inside Docker.
• A host name that points to the server. The proxy obtains and renews its certificate.
• Ports 80 and 443 open to the internet. The hosted console and your platform call from addresses that change, so they cannot be admitted by address; every call is guarded by sign-in instead.
• An API key for each application you connect, and a read-only login for each database.

Its roles are kept in your ibl.ai platform, and so are its other settings where the platform can hold them; otherwise they stay on the server. It runs the MCP Gateway, the Sync Engine and its queue, Cache Postgres, the search index and the HTTPS proxy. It runs no MCP Toolbox and no connectors: agents query the synced copy and use a connected application's own operations, and predefined queries against a source database are not available on it.

In your network, behind your firewall: the full stack. You provide:

• A Linux server or virtual machine in your network with Docker. The deployment guide starts at 16 GB of memory and 500 GB of disk.
• Network access from that server to the systems you want to connect.
• A read-only login for each database and an API key for each SaaS system.
• Only if agents are to change records in a system through an operation your team writes: a second login or API key for it, limited to those changes.
• An app registration in your Microsoft Entra ID, and the roles you assign to your users there.
• A DNS name for the server and a TLS certificate for it; the proxy can obtain one automatically or use yours.
• A firewall rule that admits only the networks you authorize to port 443, such as your agent runtime.

What runs. The MCP Gateway, the Sync Engine and its queue, Cache Postgres, the search index, the MCP Toolbox, one connector per API system and the HTTPS proxy. The agent runtime is not part of either stack.

How it is rolled out. Start with one system and one agent, then add sources and roles. The deployment guide lays out four phases: foundation, more sources, the full set, and advanced options.

What it does not do. It changes nothing in your systems on its own: there is no free-form write, and an agent can make only the changes that were defined and granted. It does not run the agents. It is not real-time: an agent sees the copy as of the last sync, except where a predefined query reads a source directly. A record an agent changes through a connector's operation is refreshed in the copy right away.

Running it day to day

The Ontology Frontend is the admin console. Your team uses it to:

• Connect a system: pick it, give its address and login, and for a database see its structure, run the read-only test and approve it. An application such as Twenty CRM is connected in one step.
• Watch the sync: schedules, the last run of each, its history. A schedule you add starts by itself within a minute.
• Decide access: what each role may reach, from the systems of record to the agents that act, changed by flipping a switch. A tool group that changes data is marked as such wherever it appears.
• Connect an agent: pick one of your platform's agents and a role; a role that can change data is offered first. The console makes a key that carries that role and nothing more, and gives it to the agent. Removing the connection ends its access at once.
• See the whole map: everything the ontology knows, and who may reach it.
• Try a tool: call one with parameters and read the answer, before an agent does.

It runs on your host or is the one hosted by ibl.ai. On the hosted one, an administrator of a platform that has no backend yet is shown how to install one and connects it there. Your operators can also work from a command line.

For your technical team

License

MIT — see LICENSE.