Ontology

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.

Local checks

./dev.sh mirrors the CI gates so you can confirm everything passes before committing:

./dev.sh setup            # install into the active venv (dev + django extras)
./dev.sh test -k canvas   # pytest (args passed through)
./dev.sh fmt              # auto-fix ruff format + import sort
./dev.sh check            # ruff format/lint/import-sort + full pytest (== CI)

CI runs the same on every PR to main: .github/workflows/ruff-format.yml (ruff) and .github/workflows/tests.yml (pytest).

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.

Gateway hardening (environment variables)

The gateway middleware is tuned entirely through environment variables on the ontology-gateway container — no code change or rebuild, just set and restart.

Rate limiting (fixed-window throttle, keyed on the authenticated subject and falling back to client IP):

To loosen limits for higher traffic, raise ONTOLOGY_RATELIMIT_MAX / ONTOLOGY_RATELIMIT_TOOLS_CALL_MAX. Two caveats:

• The window is fixed, not sliding — a client can burst up to 2×MAX across a window boundary. Size the limit accordingly.
• Counting is per worker process on the default in-memory cache, so with N workers the effective limit is ≈ N × MAX. Set ONTOLOGY_CACHE_URL to a redis://… URL so all workers share one counter and the configured number is the true global limit.

Transport security & response headers:

HSTS is only emitted over HTTPS. TLS terminates at the Caddy edge, so the gateway trusts the proxy's X-Forwarded-Proto (SECURE_PROXY_SSL_HEADER) to decide whether a connection is secure — keep the gateway reachable only via the proxy, never directly on :8080.

JWT replay protection:

The token jti (a required, validated claim) is checked against a cache-backed replay store keyed on the jti, with each entry expiring exactly when the token does (exp - now).

Entra ID access tokens are bearer tokens designed for reuse within their lifetime — the ibl.ai platform forwards the same token across many MCP requests — so blind single-use would break the integration. The modes:

• bind (default): on first sight, bind the jti to the request's client IP; the same jti presented from a different IP is rejected as replay. Legitimate reuse from the platform's stable egress passes; a token stolen and replayed from elsewhere is caught. (IP is read from X-Forwarded-For set by Caddy; deployments with multiple platform egress IPs may need off or strict.)
• strict: single-use — any second presentation of a jti is rejected. Only for deployments that mint one-time tokens.
• off: no replay checking.

As with rate limiting, the store is the Django cache: set ONTOLOGY_CACHE_URL to a redis://… URL so the check holds across all worker processes (on the default per-process cache a replay is only caught on the worker that first saw the token). Replay detection is best-effort; short token lifetimes and sender-constrained tokens (DPoP / mTLS) remain the strongest defences.

Vector store authentication:

The vector-store container runs ChromaDB's TokenAuthenticationServerProvider, so every request must present CHROMA_TOKEN; without it no container on ontology-internal can read or write embeddings. The same value is passed to the sync-engine and ontology-gateway services, and the shared VectorSearch client presents it automatically. Generate a strong random value (e.g. openssl rand -hex 32) and set it in the root .env; the compose stack fails to start if it is unset. When CHROMA_TOKEN is absent (e.g. a local or air-gapped run against an unauthenticated store) the client connects without auth.

Documentation

License

MIT — see LICENSE.