Skip to content
Docs menu

Ask your databases with auto-ontology-mcp

Run the vendored auto-ontology-mcp server so venom, Claude Code or any MCP client can answer questions over your databases with SQL checked against a reviewed ontology, and keep a personal knowledge base.

View .md

auto-ontology-mcp is an MCP server that brings NVIDIA Auto Ontology's semantic layer to any MCP client. It is vendored in this repository at services/auto-ontology-mcp/ (Apache-2.0; the pinned commit and what was left out are in its VENDORED.md).

It does two jobs:

  • Ask your databases. Point it at a database. Your agent's model names the business terms and reviews the joins, and the server checks every SQL query against that ontology and the data before running it read-only. A wrong join, a value in the wrong case or a one-to-many join that inflates a sum is caught before a number comes back.
  • Keep a personal knowledge base. Facts from receipts, papers and notes go into typed tables, ideas into linked concepts, and passages into a full-text index, each with its source. export_wiki writes it out as an Obsidian vault.

The model in your MCP client does every language step, so the server needs no model endpoint and no API key. It keeps its ontology in local SQLite files (~/.auto-ontology-mcp, or AUTO_ONTOLOGY_HOME) and connects only to the databases you register, so it works offline.

Install

Python 3.12 or later. From the repository root:

cd services/auto-ontology-mcp
python3 -m venv .venv && .venv/bin/pip install -e '.[all]'   # [all]: Postgres, MySQL and DuckDB drivers
.venv/bin/auto-ontology-mcp demo                             # optional: a demo retail database and three documents

Register a database of your own with a SQLAlchemy URL. Use a read-only database user:

.venv/bin/auto-ontology-mcp add shop 'postgresql+psycopg://reader@localhost/shop'
.venv/bin/auto-ontology-mcp list

Use it from venom

venom loads Claude Code's .mcp.json. Add the server to a project's .mcp.json, with the absolute path to the venv:

{
  "mcpServers": {
    "auto-ontology": {
      "command": "/path/to/venom/services/auto-ontology-mcp/.venv/bin/auto-ontology-mcp",
      "args": ["serve"]
    }
  }
}

Then ask: "What was revenue for the sushi roll flash drive in Pennsylvania in June 2024?" The agent calls check_answerable, get_query_context, validate_sql and run_sql, in that order.

serve speaks stdio by default. serve --transport http --port 8000 --token … serves Streamable HTTP for a client on another machine. Without a token it accepts requests addressed to localhost only.

Settings

Variable What
AUTO_ONTOLOGY_HOME Where the ontology and knowledge store live (default ~/.auto-ontology-mcp).
AUTO_ONTOLOGY_VAULT An Obsidian vault for the knowledge base's originals and export_wiki.
AUTO_ONTOLOGY_TOOLSETS Which tool groups to expose.
AUTO_ONTOLOGY_MCP_TOKEN The HTTP transport's shared secret (same as --token).

The server's own README.md lists every tool, the commands (add, scan, list, remove, export, demo) and the safety rules for read-only execution.

Develop

make test-auto-ontology-mcp installs it into dist/auto-ontology-mcp-venv from PyPI and runs its tests. It is opt-in (not part of make test, which runs offline): run it after changing services/auto-ontology-mcp/. To update the vendored copy, follow VENDORED.md.