Skip to main content

Ontology & Knowledge Graph for AI Agents

An agent with search can find candidates. An agent with a knowledge graph can find the answer — and show its work. OpenMetadata exposes the graph to AI assistants through its MCP Server, so any MCP client — Claude, Cursor, VS Code, Goose, or your own agent — can traverse it directly.

Why This Changes What an Agent Can Do

Three ways an agent can look for something, in increasing order of reliability: The third is the only one where the agent’s answer is checkable. When an assistant says “these six dashboards depend on this column,” it can hand you the SPARQL and the triples. When it says it from memory, you cannot tell the difference between a correct answer and a fluent one. Grounding agents in a graph converts a trust problem into an auditing problem — which is a much better problem to have.

The Tools

Five MCP tools cover the graph.
Access model. sparql_query, entity_neighborhood, find_by_tag, and ontology_describe called with a resource require the ExecuteSparqlQuery permission. Administrators have it, and so do non-admin users and bots that hold it. The Data Consumer policy grants it by default through the DataConsumerPolicy-ExecuteSparqlQuery-Rule rule, so ordinary users and bots can call these tools unless an administrator removes the rule. ontology_describe without a resource needs no permission. shacl_validate remains administrator-only and returns 403 for everyone else. Four of the five tools (sparql_query, entity_neighborhood, find_by_tag, shacl_validate) are not advertised at all when RDF is disabled, so a client never sees a tool it cannot call. ontology_describe is always advertised, because its default path serves the bundled ontology document from the classpath and works with RDF off.For non-administrators, sparql_query runs through a restricted read-only profile with these limits:
  • SELECT queries only.
  • JSON output only.
  • No inference.
  • No FROM, GRAPH, SERVICE, or CALL.
  • Bounded result size and runtime.
The other graph tools check that the knowledge graph is ready before they read it. If the graph is being rebuilt, the tool returns a 429 so the client can retry later. If it is degraded, the tool returns a 400 and an administrator must run a full rebuild of the RDF index. See Enable RDF (Knowledge Graph).
Results from these tools are not filtered by asset or domain policies. If you restrict who can view assets through custom policies or domains, remove DataConsumerPolicy-ExecuteSparqlQuery-Rule from the Data Consumer policy so ordinary users and bots can’t read the graph. Removal can take effect late for principals that are already connected over MCP.

ontology_describe — Start Here

Returns the OpenMetadata ontology: the full canonical document, or a SPARQL DESCRIBE for a single class or property URI. The full ontology is roughly 65 KB, so prefer a focused DESCRIBE.
Make this the agent’s first call. An LLM asked to write SPARQL against an unfamiliar schema will invent predicate names that sound right — om:hasOwnerName, om:parentTable — and get zero rows with no error. One ontology_describe call replaces that guessing with the actual declarations. Put it in your system prompt.

sparql_query

Read-only SPARQL (SELECT, ASK, DESCRIBE, CONSTRUCT) against the knowledge graph. Non-administrators are limited to SELECT queries with JSON output, as described in the access model above. UPDATE, INSERT, DELETE, DROP, LOAD, CLEAR, and CREATE are rejected. SERVICE clauses against external endpoints are rejected unless the target is on the federation allowlist — which is empty and disabled by default, so in a stock deployment this tool never reaches outside the local graph. One response field matters for agent behavior:
  • truncated: true with a byteCount when the body exceeds maxBytes. Narrow the query with LIMIT rather than raising maxBytes — values above the maximum are clamped, because a larger body is discarded wholesale by the response budget.
A request for rdfs or owl inference fails with a 503 error instead of returning un-inferred results, so an agent never gets an answer that silently skipped inference.

entity_neighborhood

The n-hop neighborhood of one entity: hasColumn, belongsToSchema, hasTag, owners, lineage, and so on. Ontology and SHACL definition graphs are excluded so schema triples do not consume result slots. Returns the full 1..depth-hop subgraph as Turtle in triples, plus an edges array that is a flat direct (1-hop) adjacency summary of the start entity only — direction, predicate, neighbor URI, neighbor label. For second- and third-hop traversal, parse triples, not edges. Each traversal branch gets its own share of limit, so deeper hops are always represented rather than being crowded out by a high-degree start node.

find_by_tag

Every entity carrying a classification tag or glossary term, walking om:hasTag and om:hasGlossaryTerm. This is the “show me everything classified PII” tool, and it is a single call rather than a SPARQL round trip.

shacl_validate

SHACL validation of a single entity’s subgraph or the whole dataset. conforms and violationCount are always returned in full even when the report body is truncated — so an agent can act on the verdict without parsing a partial report. Read-only; never blocks writes.

Complementary Tools

The graph tools sit alongside the rest of the MCP tool set. The ones that pair best:
The pattern that works: semantic search to find candidates, graph traversal to decide between them, entity details to read the winner. Search is recall; the graph is precision.

Agent Recipes

  1. search_metadata or get_entity_details → resolve the table and column IDs.
  2. entity_neighborhood at depth 2 → immediate structural context.
  3. sparql_query with prov:wasDerivedFrom+ → the full downstream set at any depth.
  4. find_by_tag on any tier or PII tag found → who needs to be told.
Ask the agent to return the query alongside the answer. That is the artifact a reviewer checks.
  1. find_by_tag with PII.Sensitive → the asserted set.
  2. sparql_query (administrators) with inferenceLevel: custom → the propagated set, if the PII-propagation rule is materialized.
  3. Diff the two → columns that are sensitive by inference but not yet tagged. That diff is the remediation list.
  1. find_context → which concept the question is actually about.
  2. get_concept_context → the definition and the exact tables and columns bound to it.
  3. sparql_query following om:hasGlossaryTerm → any other assets bound to it.
  4. Filter by tier, owner, or contract → the governed one, not merely a matching one.
This is the flow that stops an agent from answering a revenue question off revenue_v2_final_DONOTUSE.
  1. sparql_query → tables with no owner, no description, no glossary term.
  2. shacl_validate with fullGraph: true → structural violations.
  3. sparql_query → concepts with no bound data assets (ontology debt).
Three queries, one report, no dashboard to build.

Prompting Notes

Things that measurably improve results:
  • Force schema discovery first. “Before writing any SPARQL, call ontology_describe for the classes involved.” Predicate hallucination is the dominant failure mode and this eliminates most of it.
  • Always scope the named graph (administrators). Tell the agent to wrap instance patterns in GRAPH <https://open-metadata.org/graph/knowledge> { … }. Unscoped queries return ontology triples and confuse the model about its own results. Non-administrators can’t use GRAPH, because their queries run against the default graph.
  • Require the query in the answer. “Show the SPARQL you ran.” Cheap, and it makes every answer auditable.
  • Teach it to read truncated. An agent that ignores it reports partial results as complete.
  • Budget with LIMIT, not maxBytes. maxBytes is clamped to the maximum above. The fix for a large result is a narrower query.

Setting It Up

1

Enable RDF and index the graph

See Enabling Ontology & Knowledge Graph. Until the initial index runs, the tools return empty results.
2

Connect an MCP client

Follow Connect Your MCP Client. OAuth 2.0 is recommended; a Personal Access Token works where browser login is unavailable.
3

Authenticate with a principal that can run SPARQL

The graph tools require the ExecuteSparqlQuery permission, which administrators and, by default, Data Consumer users and bots hold. shacl_validate requires an administrator. If the tools are missing from the client’s tool list, that is the gating working. Check GET /api/v1/rdf/status and your principal.
4

Verify

Ask the assistant to call ontology_describe with no arguments. If it returns the ontology, the wiring is correct.
Ontology content reaches the graph from the active release of each ontology. Activating a release queues an update to the knowledge graph in the background, so a newly activated release can take a moment to appear in query results.

Troubleshooting

Expected when rdf.enabled is false — the four RDF-dependent tools are withheld rather than advertised and failing. Check GET /api/v1/rdf/status. ontology_describe should still be listed.
The principal does not hold the ExecuteSparqlQuery permission, for example because DataConsumerPolicy-ExecuteSparqlQuery-Rule was removed. shacl_validate returns 403 for every principal that is not an administrator.
A 429 means the knowledge graph is being rebuilt or has not run yet, so retry later. A 400 means the graph is degraded and retrying will not help. Ask an administrator to run a full rebuild of the RDF index.
For administrators, usually a missing GRAPH clause or an invented predicate. For non-administrators, usually an invented predicate, because GRAPH isn’t allowed. Have the agent call ontology_describe and re-derive the query.
Check for truncated: true. It means the answer is partial. Narrow the query with LIMIT and page through the rest.
The admission guard allows 8 concurrent queries globally and 2 per principal, with a 30-second timeout. Narrow the query, or materialize the traversal as an inference rule.

Next

MCP Server

Installation, authentication, and clients.

SPARQL cookbook

Queries worth putting in an agent’s prompt.