MCP Server

Connect Onta to AI agents via the Model Context Protocol.

What is MCP?

The Model Context Protocol (MCP) lets AI agents call tools on external systems. Onta exposes an MCP server so agents like Claude, Cursor, Windsurf, and custom agents can query your context graphs (your Onta knowledge graphs) directly.

Setup

Grab an API key from your dashboard, then add this to your MCP client configuration (e.g., Claude Code settings, Cursor config, or ~/.claude/mcp.json):

json

{
  "mcpServers": {
    "onta": {
      "command": "npx",
      "args": ["-y", "@onta/mcp"],
      "env": {
        "ONTA_API_KEY": "sk_live_..."
      }
    }
  }
}

The server connects to https://api.onta.sh by default. Override with ONTA_API_URL if self-hosting. Legacy COGRAPH_* / OMNIX_* env names still work.

Available Tools

The Onta MCP server exposes 15 tools. Read tools never mutate a graph; write tools do. The agent tool spans both — it plans mutating work and executes only on confirmation.

Read tools · never mutate a graph

list_knowledge_graphs

List all available context graphs and their descriptions. No parameters. Call it first when you do not yet know which graph to query.

ask

Ask a natural-language question against a context graph and get an exact answer with a plain-language explanation of how it was derived.

Parameters

question	string, required	The question to ask
kg_name	string, optional	Target context graph name

search

Hybrid semantic + keyword search over the entities in a graph — retrieve matching records by fuzzy description when you do not have an exact analytical question.

view_ontology

View the ontology (types, attributes, relationships) across all context graphs. No parameters.

list_jobs

List recent asynchronous jobs (ingestion, enrichment, and other long-running operations) with their status. No parameters.

get_job

Fetch the status and result of a single job by id.

wait_for_job

Block until a job reaches a terminal state and return its result — use it to wait for an ingest or enrichment before the next step.

Write tools · mutate a graph

ingest_csv

Ingest a CSV file into a context graph. Schema is automatically inferred. Set join_on to merge rows onto existing entities instead of minting duplicates.

Parameters

file_path	string, required	Absolute path to the CSV file
kg_name	string, required	Name for the context graph
join_on	string, optional	Key column to merge onto existing entities

create_knowledge_graph

Create a new, empty context graph to populate deliberately.

delete_knowledge_graph

Permanently delete a graph and its data. Destructive and irreversible — confirm before calling.

evolve_ontology

Evolve the ontology by describing a schema change in plain English — no exact type, attribute, or relationship names required. Onta matches your request against the existing ontology, auto-applies high-confidence changes, and returns ambiguous or new-type changes as proposals to confirm.

Parameters

ask	string, required	The schema change in plain English (e.g. "track which company a person works for")
knowledge_graph	string, optional	Target context graph name

Returns a summary, the applied changes, and any proposals to confirm.

apply_ontology_change

Commit a single proposal returned by evolve_ontology. Use this to confirm changes that were not auto-applied.

Parameters

proposal

object, required

One proposal object returned by evolve_ontology

apply_ontology_changes

Commit several evolve_ontology proposals at once — the batch form of apply_ontology_change.

schedule

Set up a recurring job that watches a source and notifies on change — for ongoing monitoring rather than a one-shot operation.

Reads and writes · the conversational front door

agent

Describe a goal in plain language and the agent plans the work — including enrichment, cleaning, deduplication, and web ingestion. Nothing mutates on the planning call; it returns a confirm_plan_id, and the plan executes only when you call agent again with it. This plan-then-confirm loop is the mutating path for enrichment, dedupe, cleaning, and web-ingest.

Example Usage

Once configured, you can interact with your context graphs from any MCP-compatible agent:

> "What context graphs do I have?"
  → calls list_knowledge_graphs()

> "How many events in San Francisco are free?"
  → calls ask(question="...", kg_name="events-sf")

> "Find venues that sound like jazz clubs"
  → calls search(query="jazz club", kg_name="events-sf")

> "Ingest this sales data"
  → calls ingest_csv(file_path="/path/to/sales.csv", kg_name="sales-2026")

> "Track which company a person works for"
  → calls evolve_ontology(ask="track which company a person works for")
    reuses the existing Person type, adds a works_at relationship to
    Company (creating Company if absent), and returns applied changes
    plus any proposals to confirm

> "Yes, apply that proposal"
  → calls apply_ontology_change(proposal=<the proposal from evolve_ontology>)

> "Enrich these companies with their industry from the web"
  → calls agent(...) which returns a plan + confirm_plan_id
  → on approval, calls agent(confirm_plan_id="...") to execute the writes