Genie One MCP server

The Genie One MCP server is a Databricks-provided MCP Service that exposes Genie as a conversational tool over the Model Context Protocol (MCP), leveraging Chat in Genie One. An MCP client or agent sends a natural-language question, and Genie searches your enterprise data, writes SQL, and returns an answer grounded in Genie Ontology with deep links back to your cited Databricks sources.

Connect any MCP client or agent to ground its data questions in Genie's trusted insights. Clients that support MCP Apps can render an interactive View that shows Genie's progress, visualizations, and results inline.

Unity Catalog permissions are always enforced, so users and agents can only query data they're allowed to access.

Use this server for analytics across your workspace: business questions asked in natural language, where accuracy depends on understanding what your data means. Genie resolves business terms, metric definitions, and table relationships through Genie Ontology, your governed semantic layer, which produces more accurate answers than an agent writing SQL directly against raw tables.

tip

To scope analytics to one curated Genie Agent, use the Genie Agent MCP server.

Access through Unity Gateway

The Genie One MCP server is a Databricks-provided MCP Service, system.ai.genie_one_mcp, governed through Unity Gateway. Unity Catalog grants control who can invoke it, service policies allow or deny individual tool calls, and every invocation is recorded for usage and audit.

Invoke the service at its Unity Gateway URL, with its fully qualified Unity Catalog name in the path:

Text

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp

Account users hold EXECUTE on system.ai by default, so no extra grant is usually required. When connecting with on-behalf-of user authentication, include the ai-gateway OAuth scope. To govern who can invoke the service and which tools it exposes, and to apply a service policy, see Govern an MCP service. To add the service to an agent, see Use MCP servers in Custom Agents. To connect external clients such as Cursor or Claude Desktop, see Connect MCPs to AI assistants and coding agents.

The previous version of Genie One MCP Service has been deprecated

The new Genie One MCP Service, system.ai.genie_one_mcp, is generally available. The previous Beta endpoint, https://<workspace-hostname>/api/2.0/mcp/genie, is deprecated and will be sunset on October 31, 2026. Move all workloads to the MCP Service before then. The deprecated endpoint uses the genie OAuth scope. To govern access with MCP Service policies, use the system.ai.genie_one_mcp MCP Service in Unity Gateway.

Connect a client such as Claude or ChatGPT

To use Genie One from an MCP client such as Claude, Claude Code, ChatGPT, or Cursor, point the client at the MCP Service URL above and authenticate with OAuth. For per-client, step-by-step setup, see OAuth examples.

To view your MCP Services and their URLs, go to your workspace and select Unity Gateway > MCPs.

Available tools

The Genie One MCP server exposes the following tools. In practice, an agent invokes genie_ask (or view_ask on MCP Apps clients) to ask a question; the agent manages the remaining tools on your behalf as it works through the response.

Tool	Description
genie_ask	Ask Genie a natural-language data question and start a response. Returns conversation_id, response_id, and status. Pass a conversation_id to continue a previous conversation.
genie_poll_response	Fetch the latest state of an in-flight or completed response, including progress steps, the final answer, and deep links to your Databricks sources.
genie_get_query_result	Fetch the full SQL result, including column schema and rows, for a query Genie ran.
genie_cancel_response	Request cancellation of an in-flight Genie turn.
view_ask	Ask Genie a question and open the interactive View. Offered instead of genie_ask to MCP Apps clients, and preferred when available.

Tool	Description
genie_ask	Ask Genie a natural-language data question and start a response. Returns conversation_id, response_id, and status. Pass a conversation_id to continue a previous conversation.
genie_poll_response	Fetch the latest state of an in-flight or completed response, including progress steps, the final answer, and deep links to your Databricks sources.
genie_get_query_result	Fetch the full SQL result, including column schema and rows, for a query Genie ran.
genie_cancel_response	Request cancellation of an in-flight Genie turn.
view_ask	Ask Genie a question and open the interactive View. Offered instead of genie_ask to MCP Apps clients, and preferred when available.

Ask a question

Because Genie runs an agent that searches data and executes SQL, answers are asynchronous. You (or your agent) invoke genie_ask with a question; the agent then manages the rest of the exchange automatically. A typical flow looks like this:

1. genie_ask starts the response and returns a conversation_id and response_id with status: in_progress. Genie continues working in the background.
2. The agent polls genie_poll_response until the response completes, surfacing progress_steps and a narration_instruction along the way to keep you informed.
3. When status is completed (or incomplete / failed), the agent returns the rendered answer, including an Explore in Databricks deep link to the full conversation and any visualizations Genie produced.

To continue the same conversation, the follow-up question reuses the previous conversation_id.

MCP App

The Genie One MCP server provides an MCP App, an extension that lets a server return an interactive view instead of plain text. On clients that support MCP Apps, the server returns an interactive View: a panel embedded in the client that shows Genie's progress, visualizations, and final answer as the conversation unfolds, rather than a text-only reply.

The Genie One MCP App rendering a bar chart, summary metrics, and Genie Ontology citations inside Claude Desktop.

No additional setup is required. Clients that support MCP Apps automatically get the interactive View. Clients that don't continue to receive text results.

Considerations

• Permissions: Unity Catalog permissions are enforced on every request, so results are scoped to what the user can access.
• User authentication: On-behalf-of user OAuth authentication is recommended, following data governance best practices and allowing for smooth clickthrough to Genie sources. Service principal authentication is also supported for programmatic and automated workloads.
• Configuration: The server honors your Genie One configuration in Databricks. Tune and configure Genie's behavior there. See Chat in Genie One.
• Polling cadence: Wait for the prior genie_poll_response call to complete before polling again.
• Result size: To protect the model's context window, genie_ask and genie_poll_response return truncated query results. When an agent needs the complete result, it can call genie_get_query_result to retrieve the full schema and rows. Very large results are still subject to a size limit; if it's exceeded, the response is truncated.
• SQL warehouse: To run queries on a specific SQL warehouse, pass the warehouse_id _meta parameter on genie_ask or view_ask.
• Pricing: The Genie One MCP server uses Chat in Genie One. See Genie pricing.

Additional resources

• Connect MCPs to AI assistants and coding agents to connect an MCP client such as Claude, ChatGPT, or Cursor, with per-client OAuth setup.
• Use MCP servers in Custom Agents to add the Genie One MCP Service to an agent you build in code, then deploy it.
• Govern an MCP service to grant access, select tools, and apply a service policy.
• Connect agents to tools with MCP Services for an overview of MCP Services on Databricks.