Engineering·April 23, 2026

MCP-Native Ontology: Connecting AI Agents to Structured Data

By Mac Anderson

MCP
Model Context Protocol
Ontology
AI Agents
Integration
Tutorial

The Model Context Protocol is rapidly becoming the connective tissue between agent runtimes and the data sources they need to reason over. Most teams first encounter MCP as a way to give their agent access to a file system, a database, or a search index. That's a fine starting point. What most teams discover next is that the same protocol is the correct surface for agent memory — a typed, workspace-scoped knowledge graph their agent queries over MCP the same way it calls any other tool.

This tutorial walks the concrete setup. It covers what flows over the protocol, why typed responses matter, and what the agent sees that a flat vector store doesn't expose. By the end, you'll have a working ontology-backed retrieval path installed in your coding agent — Cursor, Claude Code, VS Code, Windsurf, or Codex — with one command.

If you're earlier in the decision process and still weighing whether to use an ontology at all, start with What Is an Ontology for AI Agents? and Knowledge Graphs vs. RAG for AI Agents. This piece assumes you've decided you want structural retrieval and want to plug it into your agent over MCP.

What MCP is, in one paragraph

MCP is an open protocol for connecting an AI agent (or LLM client) to a data source, tool, or prompt template via a small, typed interface. The client speaks the protocol once; any server that implements it — a filesystem server, a GitHub server, a database server, or an ontology server — becomes available to the agent as a first-class capability. Typed responses flow through the protocol, which means the agent sees entities, relationships, and typed tool results instead of raw text blobs it then has to parse.

For agent memory specifically, this changes the shape of what the agent can do. A RAG-style vector store returns chunks. An MCP-native ontology returns typed nodes, typed edges, and the traversal path that produced them. The agent's reasoning improves because the retrieval speaks the domain's vocabulary.

Why MCP matters for ontology specifically

Three practical reasons agent-memory infrastructure should be MCP-native rather than locked behind a custom SDK:

1. Installation is one command. Coding agents — Cursor, Claude Code, VS Code, Windsurf, Codex — all ship with MCP client support and a standard server-registration flow. A developer goes from "I want to try this" to "my agent is querying the graph" in under a minute. Anything that requires integrating a custom SDK adds a day of onboarding friction and drops conversion from evaluators to users.

2. Typed responses survive the protocol boundary. MCP carries structured responses. The agent sees a Person entity with an email property and a works_at edge to an Organization, not a chunk of text that describes the same relationship. Structured retrieval composes into structured reasoning in ways that plain-text chunks can't.

3. Permission scoping composes cleanly. MCP supports scoped credentials per connection. An agent can be given access to one workspace — or a subset of the graph — without any custom ACL code. Multi-tenant isolation becomes a protocol guarantee, not a query-builder invariant you hope holds.

Installing the Oxagen MCP server

The one-line install commands below register the Oxagen MCP server with your coding agent. Each client has its own registration convention; the command handles it.

Cursor

npx -y @oxagen/mcp-install cursor

Claude Code

npx -y @oxagen/mcp-install claude-code

VS Code (with the MCP extension)

npx -y @oxagen/mcp-install vscode

Windsurf

npx -y @oxagen/mcp-install windsurf

Codex

npx -y @oxagen/mcp-install codex

The first run prompts for an authentication token. Follow the OAuth flow (browser window opens, you authorize, the token gets written to your client config). From that point on, your agent has access to your workspace's ontology.

Verifying the install

Once registered, your agent should list oxagen as an available MCP server. In Claude Code, /mcp shows the connected servers. In Cursor, the MCP panel in settings displays each active server with its exposed tools. If oxagen is listed and the tool count shows more than zero, the install worked.

What the agent sees

MCP servers expose a small, typed surface: tools, resources, and prompts. The Oxagen MCP server exposes tools shaped around the ontology operations an agent actually needs.

The exact tool list evolves, but the core shape is:

Search nodes — semantic or structural node search within the workspace
Get node — fetch a typed node by ID, including its properties
Get neighborhood — all neighbors of a node (outgoing and incoming edges, bounded hops)
Traverse — path-based query with typed filters (entity types, relationship types, time window)
Add observation — write a new fact into the graph (structured or natural-language prompt)
Query — one-shot natural-language entry point that decomposes into the right read or write

The agent sees each tool as a typed function signature. It doesn't have to guess how to phrase a query or parse a text blob; it calls the tool, gets a structured result, and composes its response.

A worked interaction

What follows is an annotated trace of a real interaction — the user asks a structural question, the agent composes an MCP query, the protocol returns typed data, the agent answers with provenance.

User: "Show me every active deal over $50k where the account owner left the company in the last quarter."

The agent decomposes this into a structural query:

Tool:       oxagen.traverse
Filter:
  source_type: Deal
  node_properties:
    status: "active"
    amount: gte(50000)
  relationship_type: owned_by
  target_type: Person
  target_properties:
    left_company_at: gte("2026-01-01T00:00:00Z")
      lte("2026-03-31T23:59:59Z")
Return:
  - deal node (id, name, amount, status)
  - owner node (id, name, left_company_at)
  - source_id for the owner-departure fact

MCP returns:

3 results

1. deal_id: d-8e2..., name: "Acme Q3 Renewal", amount: $84,000
   owner: Sarah Chen, left 2026-02-15
   source: gmail msg 18e4f2a3...

2. deal_id: d-a17..., name: "FinCo Platform", amount: $68,000
   owner: Alex Kim, left 2026-03-01
   source: hr.bamboohr.com departure record

3. deal_id: d-c03..., name: "InterCo Expansion", amount: $52,000
   owner: Priya Shah, left 2026-01-28
   source: slack #announcements

The agent composes its answer:

Three active deals over $50k have an account owner who left this quarter. Acme Q3 Renewal ($84k, Sarah Chen, left Feb 15), FinCo Platform ($68k, Alex Kim, left Mar 1), and InterCo Expansion ($52k, Priya Shah, left Jan 28). Each is traceable — the departure facts came from your Gmail, BambooHR, and Slack respectively.

Compare that to the RAG version of the same interaction: the agent retrieves chunks that mention "departure" and "deal" semantically, tries to correlate, and hallucinates connections. The MCP-native version returns three correct results with provenance in under 150ms.

Permission scoping in practice

Multi-tenant isolation is the single most important production property of an agent-memory infrastructure. MCP makes it straightforward.

When your agent authorizes against the Oxagen MCP server, it receives a scoped credential tied to exactly one workspace. Every tool call on that connection implicitly filters on workspace_id = the_scope. The server refuses to return nodes or edges outside the scope — there is no "forgot the WHERE clause" failure mode because the scope is carried at the protocol layer, not the query layer.

For agents serving multiple end-users or tenants, the pattern is one MCP connection per workspace scope. The agent runtime multiplexes as needed. Nothing about this is visible to the agent author beyond "different credential, different connection."

Debugging: reading the trace

When an agent behaves unexpectedly, the MCP trace is the first thing to read. Every tool call and response is logged; the agent's reasoning chain can be traced step by step.

Common things to check:

Wrong tool selected. The agent invoked search_nodes with a structural query that should have used traverse. Usually fixed by tightening the system prompt or refining tool descriptions.
Empty results surprise. The tool ran successfully but returned no nodes. Either the data isn't in the graph yet, the workspace scope is wrong, or the filter is too strict.
Provenance mismatch. The agent cites a source that seems unrelated to the claim. Usually a signal that the extraction pipeline has a misalignment — the fact was attached to the wrong source during ingestion.

In Oxagen, the dashboard also exposes the same trace for every MCP request so you don't have to parse raw logs. A developer debugging a retrieval issue can see the tool call, the filter, the result, and the source path all in one view.

What changes when the ontology is MCP-native

Four concrete shifts for agent teams that switch from custom retrieval integrations to MCP-native ontology:

Onboarding drops from a week to a minute. The one-line install is the full integration. No SDK to import, no custom ACL layer, no retrieval-specific code in the agent.
Agent reasoning improves. Typed responses ride the protocol, so the agent sees entities and relationships instead of text blobs it has to parse.
Multi-tenant isolation becomes a protocol guarantee. Scope is carried at connection time; the "forgot the WHERE clause" class of bug disappears.
Debugging becomes traceable. Every query is a structured tool call with a structured result. "Why did the agent answer this way?" resolves to a trace, not an archaeology dig through embeddings.

The short version

MCP is the correct protocol surface for agent memory — not because it's fashionable, but because it carries typed responses, scopes permissions cleanly, and installs with one command.
Ontology-over-MCP means the agent sees entities and relationships, not text chunks. Reasoning composes better because the retrieval speaks the domain's vocabulary.
Install is one command per coding agent. Cursor, Claude Code, VS Code, Windsurf, Codex — no custom SDK, no glue code.
Permission scoping is a protocol guarantee. Multi-tenant agents get workspace isolation without writing ACL code.

Oxagen ships an MCP-native, typed, workspace-scoped, Neo4j-backed ontology with hybrid vector+structural retrieval built in. Install the MCP server for your coding agent in one line above, or read the docs for API access. For enterprise BYOC, dedicated instances, or onboarding help, book a demo.

FAQ

What is an MCP-native ontology?

An MCP-native ontology exposes a typed, workspace-scoped knowledge graph to AI agents through the Model Context Protocol as a first-class data source. Agents install the MCP server with one command, authenticate against a workspace, and query entities, relationships, and traversals through the protocol — no custom SDK, no glue code. Typed responses flow through, so the agent sees structured entities instead of text blobs.

Which coding agents work with Oxagen's MCP server?

Cursor, Claude Code, VS Code (with the MCP extension), Windsurf, and Codex all support MCP servers. The Oxagen MCP server installs with a single npx -y @oxagen/mcp-install <client> command per client, which handles the client-specific registration config.

How does permission scoping work over MCP?

Each MCP connection carries a credential scoped to exactly one workspace. Every tool call on that connection implicitly filters on workspace_id, and the server refuses to return data outside the scope. Multi-tenant isolation is a protocol guarantee at connection time, not a query-builder invariant — so the "forgot the WHERE clause" class of cross-tenant leak doesn't exist.

What can the agent do over MCP that it can't do with RAG?

Structural retrieval. The agent can traverse relationships (multi-hop), filter by entity type and time window, return typed results with provenance, and compose structured queries that aren't expressible as semantic similarity. RAG handles open-ended text recall; MCP-native ontology handles the structural queries RAG can't answer.

Can I run the ontology in my own infrastructure instead of SaaS?

Yes. Oxagen supports hosted, dedicated-instance, and BYOC (bring-your-own-cloud) deployment models. BYOC runs the ontology inside the customer's VPC with customer-managed keys and private endpoints; the MCP protocol surface is identical across deployment modes, so agent code doesn't change.

How do I debug an MCP query that returned unexpected results?

Start with the MCP trace — every tool call and response is structured and logged. Common causes of unexpected results: wrong tool selected (agent used search instead of traverse), empty results (data isn't ingested yet, or the filter is too strict), or provenance mismatch (a fact attached to the wrong source during extraction). Oxagen's dashboard exposes the trace per request so you don't have to parse raw logs.