Share over MCP

Data MCP tools

Once you’ve exposed an ontology over MCP, your AI assistant sees the endpoint as a set of tools. Most are free lookups. Two of them, ask_data and refine, hand the question to Kenseme’s Data Agent, which uses your organization’s AI allowance. This page lists every tool, what it returns, and which setting on the MCP Server page controls it.

In the app: Data Context › Ontologies › your ontology › More › MCP Server

The tools at a glance¶

Every tool answers as you: it sees only what your own Kenseme account can see. Every call, answered or refused, is recorded under Recent activity on the MCP Server page.

Tool	What it returns	Cost	Turned on by
`who_am_i`	Who you’re signed in as, which organization and ontology the endpoint serves, and your effective access on it.	Free	Always on
`get_capabilities`	What the endpoint can do right now: answer mode, row cap, database dialect, pinned environment, ontology size, how fresh the search index and schema snapshot are, and which optional tools are on. Call this first.	Free	Always on
`list_subject_areas`	The top-level groups of concepts, with how many concepts each holds and how many are bound to data.	Free	`Concept search`
`search_concepts`	Concepts (classes, relationships, attributes) matching a search by business meaning, and whether each is bound to data. Never includes physical names.	Free	`Concept search`
`describe_concept`	One concept in full: label, definition, parent, attributes, relationships, and whether it’s bound. Physical table and column names appear only when `Schema explorer` is also on.	Free	`Concept search`
`get_binding_overview`	Every class bound to a table in the pinned environment, with its table, key and display columns, and counts of bound attributes and relationships.	Free	`Schema explorer`
`describe_binding`	The full mapping of one bound class: each attribute’s column and SQL type, and each relationship as a ready-to-use join with its cardinality.	Free	`Schema explorer`
`find_bound_entities`	A case-insensitive search across bound class, attribute, and relationship labels and IRIs, with the owning class and physical name of each match.	Free	`Schema explorer`
`ask_data`	An answer to a business question. If the question is ambiguous, a clarification request with a `sessionId`.	Uses the Data Agent (counts toward AI usage)	Always on
`refine`	Continues an `ask_data` call that asked for clarification. You pass the `sessionId` and your answers.	Uses the Data Agent (counts toward AI usage)	Always on
`get_answer`	The outcome of an `ask_data` or `refine` call that returned `{ status: "running" }`. Returns `running` again until it’s done.	Free	Always on
`cancel`	Stops an `ask_data` or `refine` call that’s still running, so it stops using AI allowance. Safe to call on a session that already finished.	Free	Always on
`get_sql`	The exact SQL behind a previous answer, with its dialect and the endpoint’s mode.	Free	Always on
`explain`	A plain-language explanation of how a previous answer was reached: which concepts were used and how they were joined.	Free	Always on
`get_chart_spec`	The chart the agent suggested for a previous answer (type, axes, series, title), or `not_available` if it suggested none.	Free	Always on

Free tools never call an AI model and never query your database; they read what Kenseme already knows. Only ask_data and refine count toward your AI token allowance.

A typical call sequence¶

A newly connected assistant usually works through the tools in this order:

who_am_i — confirm the organization, the ontology, and its access.
get_capabilities — learn the mode, the row cap, and which optional tools are on.
list_subject_areas and search_concepts — find the concepts the question is about (with Concept search on).
get_binding_overview and describe_binding — see how those concepts map to tables and joins (with Schema explorer on).
ask_data, then refine if it asks for clarification.
get_sql, explain, and get_chart_spec — pull the query, the reasoning, and the chart for the answer.

MCP clients usually cut a single call off after about a minute. If a question takes longer, ask_data or refine returns { status: "running", sessionId } and Kenseme keeps working. Call get_answer with that sessionId every few seconds until it returns the result, or cancel to stop it. A run still unfinished after a few minutes returns run_timed_out; ask again.

Discovery tools¶

list_subject_areas, search_concepts, and describe_concept let an assistant learn your business vocabulary before it asks a question. They read a search index Kenseme builds from the ontology and its bindings, so they’re instant. They’re off until you switch on Concept search.

Binding-map tools¶

get_binding_overview, describe_binding, and find_bound_entities show the same binding map the Data Agent reasons with: which class sits on which table, which attribute is which column, and how classes join. They’re for assistants that want to understand the data model or write their own SQL. Because they reveal physical table and column names, they need Schema explorer.

Anything under Never return raw values is removed from the map first. A redacted class doesn’t appear, and neither does any relationship that touches it.

Ask, refine, and the result readers¶

ask_data returns one of two things:

An answer (answered) with the answer text, the SQL, an explanation, the concepts it used, any caveats, and, in Include data mode, the rows.
A clarification request (needs_clarification) with a sessionId, a whatIsKnown note, and a questions list.

Each question has an id (such as q1), a kind (timeRange, grain, metric, entity, filter, or other), the question text, options (each with its own id, such as a, and text), and allowFreeText.

Answer with refine, passing the sessionId and a free-text answer, structured answers, or both. answers is a JSON array of { questionId, optionId?, text? } objects. For example, to answer q1 with option a:

refine(sessionId, "", answers: "[{\"questionId\":\"q1\",\"optionId\":\"a\"}]")

The session remembers what the agent has already worked out, so a follow-up doesn’t start from scratch. A session belongs to the person and endpoint that created it, expires after a period of inactivity, and closes when a conversation gets too long.

get_sql, explain, and get_chart_spec return an answered session’s artifacts without re-running anything. A session still waiting for clarification, or an answer with no chart, returns not_available. A sessionId you don’t own, or one that has expired, returns session_not_found; the server doesn’t say which.

What the server may return¶

The mode on the MCP Server page decides what ask_data and refine return:

SQL and explanation only — the SQL and an explanation, never rows. The server doesn’t connect to your database in this mode, so get_chart_spec has nothing to return.
Include data — the server runs the query against the pinned Binding environment and returns rows, up to Maximum rows per answer. This is the only mode that produces chart suggestions.

Every answer is also capped by a server-wide ceiling, 1,000 rows by default. A person set to Force SQL-only under Per-user access gets SQL-only answers even when the endpoint is set to Include data, and a per-person Row limit lowers their cap. who_am_i and get_capabilities both report the policy you actually get.

Per-endpoint switches¶

The four Discovery checkboxes on the MCP Server page map to the tools like this. All start off.

Switch	What it turns on
`Concept search`	`list_subject_areas`, `search_concepts`, `describe_concept`.
`Glossary lookups`	Lets the Data Agent consult your business glossary while it interprets `ask_data` and `refine`. No tool of its own.
`Schema explorer`	`get_binding_overview`, `describe_binding`, `find_bound_entities`, and physical names inside `describe_concept`.
`Named instances`	Lets the Data Agent list the ontology’s named individuals while it reasons. No tool of its own.

get_capabilities reports these under tools (conceptSearch, glossary, schemaExplorer, instances, and bindingMap, which mirrors schemaExplorer). Calling a tool whose switch is off returns tool_not_available, and nothing else.

Troubleshooting¶

get_capabilities includes a notes list explaining anything that stops the endpoint answering in full:

Note	What to do
“This endpoint has no pinned binding environment, so it cannot answer data questions.”	Pick a `Binding environment` on the `MCP Server` page. Until then, `ask_data` and the binding-map tools return `endpoint_not_configured`.
“The pinned binding environment is no longer available.”	The environment was removed or no longer belongs to this ontology. Pin another one.
“The pinned environment’s connection is unavailable.”	The database connection behind the environment was removed. Check it on the `Database Connections` page.
“No schema snapshot has been captured for the pinned environment yet.”	Capture one from the binding workspace. Answers still work meanwhile, with a caveat that the SQL wasn’t checked against your tables.
“The concept search index has not been built yet.”	Kenseme builds the index automatically after a binding change and on a schedule. If it never appears, check Organization Settings › `Background Jobs`.

Two other codes you may see:

not_enabled — the Ontology Data MCP feature, or the Data Agent feature it depends on, is off for your organization. See Feature flags.
quota_exhausted — your organization’s AI allowance is used up. See AI token allowance and usage.