iblai/ontology

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

What it is

iblai/ontology is a unified knowledge layer that runs inside your network. It makes the systems you already run — SIS/ERP databases (PeopleSoft, Oracle, Postgres), data warehouses (Snowflake), and SaaS apps (Canvas, Salesforce, ServiceNow, Workday, Jira, …) — queryable by AI agents over the Model Context Protocol (MCP).

The prevailing approach extracts your data through a VPN tunnel into a vendor cloud. iblai/ontology does the opposite: no data extraction, no VPN to our cloud, no third-party infrastructure holding your data. The agent runtime (where models execute) is a separate concern and can run anywhere; the knowledge layer — the data, the cache, the permissions — stays on-premise and is exposed over MCP so any authorized runtime can connect.

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

It is domain-agnostic: the same stack serves a university (higher-ed systems) and an enterprise (CRM/ITSM/HCM/data-warehouse), with built-in defaults for both (see the catalog).

How it connects (MCP in, MCP out)

   YOUR NETWORK (ON-PREMISE)
   ┌──────────────────────────────────────────────────────────────┐
   │  Source systems                                                │
   │  PeopleSoft/Oracle · Snowflake · Postgres   Canvas · Salesforce │
   │        │  (SQL, read-only)                   │ (REST)           │
   │        ▼                                      ▼                  │
   │  ┌───────────────────────────┐   ┌──────────────────────────┐  │
   │  │ Google MCP Toolbox        │   │ Custom MCP servers        │  │
   │  │ (databases) [1]           │   │ (APIs) [1]                │  │
   │  └─────────────┬─────────────┘   └────────────┬─────────────┘  │
   │                └───────────────┬───────────────┘                │
   │            [2] sync → text memories (MD) + Postgres cache + vectors │
   │                                │                                │
   │            [3] identity: Entra ID JWT + roles.yaml (X-Iblai-Role) │
   │                                │                                │
   │            [4] iblai/ontology exposed as ONE MCP server (HTTPS) │
   └────────────────────────────────┬───────────────────────────────┘
                                     │  MCP over HTTPS, role-scoped
                                     ▼
   EXTERNAL: agent runtime (ibl.ai or anywhere) — forwards the user's
   Entra token per request, never stores institutional data.

• Inbound uses Google MCP Toolbox for Databases: databases are exposed as MCP tools via config/tools.yaml (kind: source | tool | toolset). REST systems get lightweight custom MCP servers (mcp-servers/). Run ontology mcp validate to check tools.yaml against the Toolbox schema.
• Outbound, iblai/ontology is itself one MCP server (streamable_http, behind your firewall + Entra ID). Any MCP client — the ibl.ai agent runtime, Claude, Cursor, a custom app — connects and gets results scoped to the caller's role.

Full design: docs/architecture.md.

Quick start

pip install -e ".[dev]"      # core CLI + tests
ontology --help
ontology config init         # scaffold a deployment (config/, sql/, compose)

Hybrid stack — a lean, Django-free CLI + config layer (works on a fresh checkout) and a Django + Celery backend for the long-running services. Install extras as needed:

pip install -e ".[django]"   # backend services (gateway, sync, discovery)
pip install -e ".[llm]"      # BYOK schema analysis (anthropic / openai)
pip install -e ".[db]"       # source drivers (oracle, postgres, mysql, mssql)
pip install -e ".[vector]"   # ChromaDB vector index

Names: distribution iblai-ontology · import package iblai_ontology · command ontology.

End to end

1 · Discover a service — two ways

A. Live database — connect, verify read-only, introspect, analyze, provision:

ontology service add --from peoplesoft \
  --host psft-db.internal.edu --database CSPRD --user iblai_readonly

--from <catalog-key> prefills the connection shape (driver, port, env) from the built-in catalog. The pipeline runs a read-only safety suite first — seven write attempts that must all be denied — then introspects the schema and generates config.

B. From a SKILL.md — seed an API source with no live connection:

ontology service add --skill canvas      # or: ontology skill import canvas
ontology skill list                      # all vendored skills (higher-ed + enterprise)

This parses the skill's connection env and key operations into a discovery seed (read-only operations become suggested MCP tools).

2 · Interpret the schema & see the connection

ontology service schema peoplesoft        # discovered tables, by row count
ontology service connection peoplesoft     # stored connection (secrets redacted)

$ ontology service schema peoplesoft
peoplesoft — oracle | 847 tables, 12,400,000 rows
            Top 20 tables
┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓
┃ Schema ┃ Table              ┃ Rows      ┃ Columns ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩
│ SYSADM │ PS_STDNT_CAR_TERM  │ 2,345,678 │ 24      │
│ SYSADM │ PS_STDNT_ENRL      │ 1,876,543 │ 31      │
└────────┴────────────────────┴───────────┴─────────┘

3 · Test it

ontology service test peoplesoft           # 7-test read-only safety suite
ontology mcp validate                       # tools.yaml is MCP Toolbox compliant
ontology mcp test get-student-enrollment --params '{"student_id":"001234567"}'

$ ontology service test peoplesoft
  [PASS] CREATE TABLE blocked   [PASS] INSERT blocked   [PASS] UPDATE blocked
  [PASS] DELETE blocked   [PASS] DROP TABLE blocked   [PASS] ALTER blocked
  [PASS] TRUNCATE blocked
  All safety checks passed.   # credentials confirmed read-only

4 · Provision, sync, serve

ontology service approve peoplesoft         # cache schema, tools, sync schedules
ontology sync run peoplesoft                # pull → cache + text memories + vectors
ontology deploy up                          # bring up the stack (compose)

Then register iblai/ontology as an MCP server in your agent platform (see docs/platform-integration.md):

ontology platform register --url https://ontology.your-org.edu/mcp
ontology platform connect  --server 14 --scope user --role FinancialAidCounselor

Built-in service catalog

ontology catalog list ships defaults (connection shape, adapter, default toolset, sync cadences, and the upstream SKILL.md) for 22 systems across two domains. Seed any of them with ontology service add --from <key> or ontology skill import <key>.

Higher-ed — iblai/higher-education-agents

Enterprise — iblai/enterprise-agents

ontology catalog show snowflake     # connection shape, env, default toolset, cadences, skill

Utilities

ontology doctor          # diagnostics: config validity, drivers, per-service env, Entra
ontology health          # PostgreSQL cache, MCP servers, sync engine, text-memory storage
ontology catalog list    # built-in service defaults (--domain higher-ed|enterprise)
ontology mcp validate    # tools.yaml ↔ Google MCP Toolbox schema

CLI reference

Full reference: docs/components/07-cli.md.

Security posture

• Read-only everywhere. No source writes in v1. Before touching any data, the safety suite attempts seven write operations and requires all seven be denied — otherwise it refuses to proceed and prints remediation SQL.
• Data stays on-premise. Source credentials never leave your network; the agent runtime queries at runtime, scoped by the authenticated user.
• Identity through Entra ID. Every MCP request carries the user's Entra ID JWT; the gateway validates it and resolves the caller's role against roles.yaml. See docs/identity.md.
• Credential isolation & containment. Each inbound MCP server has its own credential scope; connection secrets are encrypted at rest.

Documentation

License

MIT — see LICENSE.