NVIDIA Auto Ontology Explained

NVIDIA Auto Ontology is an Apache-2.0 Python framework that generates a semantic, graph-based layer from your database metadata, lets a person review and certify it, and then lets AI agents answer questions through that layer. NVIDIA presented it on October 21, 2026 as part of its Agent Knowledge Foundation, and the code is on GitHub at NVIDIA/auto-ontology.

Agents connect through an MCP server or a REST API (POST /api/chat/completions), and you can start the whole stack with docker compose and try it in the web UI at localhost:3000. This article is based on the GitHub README and docs plus NVIDIA's official blog and developer page, and covers how it works, how to run it, how it differs from similar tools, and what to watch for (as of November 2026). Items we could not confirm are listed separately.

- Semantic layer: a translation table that maps business words such as "revenue" or "customer" to the real tables, columns and formulas. Instead of letting an AI read raw tables, you let it read this table first
- Ontology: a structure of business concepts (customers, products, orders) and the relationships between them. Auto Ontology stores it as a graph
- Certification: the step where someone who knows the business reviews an auto-generated definition and approves it

- What it is: an open-source (Apache-2.0) framework that builds a graph-based semantic layer from metadata and checks the SQL an agent generates against it
- How to use it: start it with docker compose, then use the web UI, MCP or the REST API. An NVIDIA API key (from build.nvidia.com) is required
- Caveat: by default model inference goes to NVIDIA's API catalog. Self-hosted NIMs can be configured instead. Certification is a manual process

Giving an LLM your database schema and asking it to write SQL (text-to-SQL) is easy, but column and table names alone do not carry business meaning. Is amount tax-inclusive? Does status = 3 mean shipped? Which of several revenue tables is authoritative? The model fills such gaps by guessing and can return SQL that is valid but means something else. Because it runs without an error, you just get a plausible-looking wrong number.

Auto Ontology tackles this by first building a layer that defines business terms, metrics and relationships, and tying SQL generation and validation to it. The README describes four functions: Discover, Ground, Validate and Expose.

- Discover: finds ontologies from the metadata of connected databases and builds a knowledge graph
- Ground: ties metrics, entities and relationships to business meaning and reconciles conflicting definitions
- Validate: checks generated queries against certified definitions and lineage, and returns provenance with the answer
- Expose: serves the context through MCP, CLI and API, and folds certified corrections back into the ontology

NVIDIA's developer page calls the output a starting ontology that business experts test, refine and certify. So this is semi-automatic, with human certification built in, not fully automatic. NVIDIA says it reduced ontology creation time by 90% in its own testing; we could not find the test conditions.

According to the README, four model roles are used, each with its own endpoint, API key and model name.

Note that another section of the README (Software Components) names different embedding and reranking models, so the descriptions are inconsistent. Check .env.example before relying on a specific name. The README also warns that the embedding model must stay the same between ingestion and queries.

According to the README and docs/connections.md, ten database engines are supported.

- Docker with Compose v2, and uv
- An NVIDIA API key (nvapi-..., from build.nvidia.com)
- Python 3.12+ for the backend and ingestion services; Next.js 16 (Better Auth, Prisma) for the frontend
- Sources can be narrowed with a schema allowlist and table_allow_regex / table_deny_regex; deny rules win

The README sets up a sample Postgres database (Wide World Importers) and starts the stack. The commands below follow the README; replace the <...> placeholders with your own values.

Set these values in .env. .env.example lists a placeholder nvapi-your-api-key-here per model role, so replace each one or delete those lines.

Next, start Postgres and load the sample data.

Finally, build and start the whole stack.

Open http://localhost:3000 and sign in with AUTO_ONTOLOGY_ADMIN_EMAIL and AUTO_ONTOLOGY_ADMIN_PASSWORD. Enable Settings → Semantic Compilation, then try the sample question from the README in the Chat view. Self-service sign-up is disabled, and the first account is the bootstrap admin (docs/authentication.md).

The MCP server is an HTTP client of Auto Ontology's public API; it holds no database credentials or model configuration. Permission checks happen in the API, and calls run with the signed-in user's permissions. It listens on port 3003 by default, at the /mcp path. Against a running deployment, the README starts it like this.

For Cursor, add this to ~/.cursor/mcp.json.

For Claude Desktop, the README bridges with mcp-remote in claude_desktop_config.json.

All MCP tools are read-only: check_readiness, search_terms, get_term, get_term_columns, get_term_sql_attributes, get_sql_attribute, describe_table, check_answerable and ask_question. According to the docs there is deliberately no tool for browsing raw schemas, so agents reach data through the semantic layer. The main tool is ask_question, which returns the answer, the SQL and rows; it makes many model calls so can take tens of seconds, and results are capped at 100 rows. For MCP basics see our Claude Code MCP integration guide, and for the latest spec changes see MCP 2026-07-28 spec.

The REST API uses a token created under API Tokens in the web UI. The response is a server-sent event stream that ends with data: [DONE].

The README says it exposes context through MCP, CLI and API, but we could not find documentation of standalone CLI commands.

Many tools sound similar, but their roles differ. The table compares their general positioning with what the Auto Ontology README describes.

The main difference is the kind of data. GraphRAG, LightRAG and graphify build graphs from text or code and are not meant to tie "the definition of revenue" to table columns and validate SQL. Auto Ontology focuses on business definitions over SQL databases, and document search is not its subject. dbt Semantic Layer has a similar goal, but there people write the metrics by hand. Per the README, Auto Ontology can import and export models as Apache Ossie YAML, so moving definitions to and from existing semantic models is anticipated. For document-side RAG infrastructure, see also our WeKnora overview.

Apache Ossie is a vendor-neutral JSON/YAML specification for semantic models (metrics, dimensions, relationships). It is the Open Semantic Interchange (OSI) project, renamed when it entered the Apache Incubator on July 10, 2026; the spec itself did not change. Auto Ontology uses Ossie's converter and offers import and export under Settings → Import / Export, or through POST /api/model/import and POST /api/model/export. Other tools may not read Ossie files directly, so test a round trip in your own environment.

- Inference endpoints: by default inference goes to NVIDIA's API catalog (integrate.api.nvidia.com, ai.api.nvidia.com), under each provider's and model's terms. Self-hosted NIMs or other OpenAI-compatible endpoints can be configured. What exactly is sent (metadata only, or row data too) should be checked in the code and settings before use; we could not pin this down
- KumoRFM (optional): only if KUMO_RFM_API_KEY is set, connected tables are uploaded to a hosted service for predictive questions. The README asks you to review what is sent and to complete your organization's data review first
- Network: ports 3001 and 3002 (ingestion) have no authentication of their own, so keep them on a private network
- Stored credentials: without Vault, connection objects including passwords are stored as plaintext JSON in Postgres. Production use assumes configuring Vault
- Permissions: the docs do not mention least-privilege read-only database accounts; prepare one yourself
- Certification workload: someone who knows the business must review definitions, and the effort grows with the number of tables and columns, including re-review after schema changes
- Maturity: at the time of writing the project does not accept external contributions, and the README provides the software AS IS. Verify answers before relying on them

- Business data sits in SQL databases such as Postgres, MySQL, Snowflake or Databricks, and definitions like "revenue" or "customer" differ between teams
- You want an internal agent that answers numeric questions in natural language but worry about wrong aggregations
- You can assign reviewers (a data steward or someone who knows the business)
- If your knowledge lives mainly in documents or PDFs, or the database is small and simple, this is likely overkill

- NVIDIA/auto-ontology (GitHub): README, docs/mcp.md, docs/connections.md, docs/authentication.md
- Building an Agent Knowledge Foundation (NVIDIA Developer)
- NVIDIA Blog, October 21, 2026 (Agent Toolkit)
- Apache Ossie (Incubator proposal)