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 Tools
Five MCP tools cover the graph.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:SELECTqueries only.- JSON output only.
- No inference.
- No
FROM,GRAPH,SERVICE, orCALL. - Bounded result size and runtime.
ontology_describe — Start Here
Returns the OpenMetadata ontology: the full canonical document, or a SPARQL DESCRIBE for a single class or property URI.
DESCRIBE.
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: truewith abyteCountwhen the body exceedsmaxBytes. Narrow the query withLIMITrather than raisingmaxBytes— values above the maximum are clamped, because a larger body is discarded wholesale by the response budget.
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.
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.
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:Agent Recipes
Impact analysis before a schema change
Impact analysis before a schema change
search_metadataorget_entity_details→ resolve the table and column IDs.entity_neighborhoodat depth 2 → immediate structural context.sparql_querywithprov:wasDerivedFrom+→ the full downstream set at any depth.find_by_tagon any tier or PII tag found → who needs to be told.
Privacy review: where did this sensitive data end up?
Privacy review: where did this sensitive data end up?
find_by_tagwithPII.Sensitive→ the asserted set.sparql_query(administrators) withinferenceLevel: custom→ the propagated set, if the PII-propagation rule is materialized.- Diff the two → columns that are sensitive by inference but not yet tagged. That diff is the remediation list.
Answering a business question correctly
Answering a business question correctly
find_context→ which concept the question is actually about.get_concept_context→ the definition and the exact tables and columns bound to it.sparql_queryfollowingom:hasGlossaryTerm→ any other assets bound to it.- Filter by tier, owner, or contract → the governed one, not merely a matching one.
revenue_v2_final_DONOTUSE.Catalog health audit
Catalog health audit
sparql_query→ tables with no owner, no description, no glossary term.shacl_validatewithfullGraph: true→ structural violations.sparql_query→ concepts with no bound data assets (ontology debt).
Prompting Notes
Things that measurably improve results:- Force schema discovery first. “Before writing any SPARQL, call
ontology_describefor 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 useGRAPH, 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, notmaxBytes.maxBytesis clamped to the maximum above. The fix for a large result is a narrower query.
Setting It Up
Enable RDF and index the graph
Connect an MCP client
Authenticate with a principal that can run SPARQL
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.Verify
ontology_describe with no arguments. If it returns the ontology, the wiring is correct.Troubleshooting
The graph tools do not appear in my client
The graph tools do not appear in my client
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.403 on a graph tool
403 on a graph tool
DataConsumerPolicy-ExecuteSparqlQuery-Rule was removed. shacl_validate returns 403 for every principal that is not an administrator.429 or 400 while the graph is rebuilding
429 or 400 while the graph is rebuilding
Queries return zero rows
Queries return zero rows
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.Results look incomplete
Results look incomplete
truncated: true. It means the answer is partial. Narrow the query with LIMIT and page through the rest.Query capacity or timeout errors
Query capacity or timeout errors