Skip to main content
Last updated on

Genie One MCP server

The Genie One MCP server is a Databricks-provided MCP 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 query one curated Genie Agent from Python, use AI Bridge tool examples. To query a specific agent over MCP, see the Genie Agent MCP server. To call Genie One from an application without MCP, use the Genie One API.

Requirements​

To call the Genie One MCP server, a user or service principal needs the following:

  • EXECUTE on system.ai.genie_one_mcp. Its securable type is mcp_service.
  • USE CATALOG on the system catalog and USE SCHEMA on the system.ai schema.
  • Assignment to the workspace.

To check a caller's effective permissions with the Databricks CLI, run:

Bash
databricks grants get-effective mcp_service system.ai.genie_one_mcp --principal someone@example.com

To grant EXECUTE, run:

Bash
databricks grants update mcp_service system.ai.genie_one_mcp \
  --json '{"changes": [{"principal": "someone@example.com", "add": ["EXECUTE"]}]}'

To grant access to a Databricks-provided MCP, a metastore admin must first grant themselves MANAGE on the system.ai schema. See Share an MCP.

Access through Unity Gateway​

The Genie One MCP server is a Databricks-provided MCP, system.ai.genie_one_mcp, governed through Unity Gateway.

Invoke the MCP at its Unity Gateway URL, with its fully qualified Unity Catalog name in the path and your workspace ID in the o query parameter:

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>

To get the workspace ID without the UI, use one of the following:

  • The o= value in your workspace URL.
  • The x-databricks-org-id header on any Databricks REST API response.
  • WorkspaceClient().get_workspace_id() in the Databricks SDK for Python.

When connecting with on-behalf-of user authentication, include the ai-gateway OAuth scope. To control access and apply policies, see Govern an MCP. To add the MCP to an agent, see Call MCP tools from a Python agent. To connect external clients such as Cursor or Claude Desktop, see Supported coding and work agents.

Deprecated

The Beta endpoint, https://<workspace-hostname>/api/2.0/mcp/genie, is deprecated and reaches end of life on November 30, 2026. After that date, requests to the Beta endpoint fail. Move all workloads to the generally available system.ai.genie_one_mcp MCP before then.

Tool names and arguments are the same on both endpoints. To move a client from the Beta endpoint, update its MCP configuration:

  • Replace the server URL with https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>.
  • If the client uses OAuth, request the ai-gateway scope instead of the genie scope.
  • Make sure callers have the permissions in Requirements.

Connect AI agents to Genie One MCP​

To connect a coding agent or another MCP client, configure the client to connect to the Unity Gateway MCP URL https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>. Follow the setup for coding agents or other MCP clients.

To view your MCPs and their URLs, go to your workspace and select Unity Gateway > MCPs. To list Databricks-provided MCPs with the REST API, call GET /api/2.1/unity-catalog/mcp-services?parent=schemas/system.ai. See Find an MCP.

Call from Python with the MCP SDK​

The server uses the streamable HTTP transport and accepts a Databricks token in an Authorization: Bearer <token> header. The following example uses the MCP Python SDK and the Databricks SDK for Python to ask a question, poll until Genie finishes, and then ask a follow-up question in the same conversation.

Install the packages:

Bash
pip install mcp databricks-sdk

Run the example:

Python
import asyncio

from databricks.sdk import WorkspaceClient
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

w = WorkspaceClient()
url = (
    f"{w.config.host}/ai-gateway/mcp-services/system.ai.genie_one_mcp"
    f"?o={w.get_workspace_id()}"
)


async def ask(session, question, conversation_id=None):
    args = {"question": question}
    if conversation_id:
        args["conversation_id"] = conversation_id
    state = (await session.call_tool("genie_ask", args)).structuredContent

    # Poll until Genie finishes: completed, incomplete, or failed.
    while state["status"] == "in_progress":
        poll = await session.call_tool(
            "genie_poll_response",
            {
                "conversation_id": state["conversation_id"],
                "response_id": state["response_id"],
            },
        )
        state = poll.structuredContent
    return state


async def main():
    # w.config.authenticate() returns {"Authorization": "Bearer <token>"}.
    async with streamablehttp_client(url, headers=w.config.authenticate()) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([tool.name for tool in tools.tools])

            first = await ask(session, "What were total sales last month?")
            print(first["status"], first.get("final_answer"))

            follow_up = await ask(
                session, "Break that down by region.", first["conversation_id"]
            )
            print(follow_up["status"], follow_up.get("final_answer"))


asyncio.run(main())

The example doesn't request progress notifications, so genie_ask returns right away with status: in_progress, and the client polls genie_poll_response for the answer.

Databricks Genie plugins for ChatGPT, Claude, and Grok Bot/Cursor​

The Databricks Genie plugins connect ChatGPT, Claude, and Grok Bot/Cursor to the Genie One MCP. They use default OAuth apps, so users sign in with their Databricks account and an admin doesn't need to create an OAuth app.

An admin sets up the plugin first. Then each user connects to it and signs in.

note

If your workspace restricts inbound network access, a Databricks admin must allow ChatGPT or Claude traffic, or the plugin can't connect. See Allow partner platforms in context-based ingress policies.

To set up the plugin, a ChatGPT admin does the following:

  1. In your ChatGPT workspace settings, click Plugins.
  2. Search for Databricks Genie.
  3. Click Create from template.
  4. Enter your Databricks workspace URL. If you use a custom URL, include your workspace ID as ?o=<workspace-id>.
  5. Click Create draft.
  6. Click Publish.

To connect, each user does the following:

  1. In ChatGPT, open the Plugins page.
  2. Search for Databricks Genie.
  3. On the plugin your admin set up, click Connect.
  4. When ChatGPT redirects you, sign in with your Databricks account.

For more information, see the ChatGPT Genie plugin.

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. Call it after genie_poll_response reports status: completed. Takes the conversation_id and response_id you polled with, plus the query's item_id from genie_poll_response, in structuredContent.query_items[].item_id.

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. Call it after genie_poll_response reports status: completed. Takes the conversation_id and response_id you polled with, plus the query's item_id from genie_poll_response, in structuredContent.query_items[].item_id.

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.

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. Any Databricks token sent in an Authorization: Bearer header works, including OAuth user-to-machine (U2M), OAuth machine-to-machine (M2M), and personal access tokens, so a browser OAuth flow isn't required. See Supported inbound authentication.
  • 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 warehouse_id in the _meta parameters on genie_ask or view_ask.
  • Pricing: The Genie One MCP server uses Chat in Genie One. See Genie pricing.

Troubleshooting​

  • Routine or Model ... does not exist or MCP is not a valid securable type when you check or grant permissions: Use mcp_service as the securable type, not function or mcp. The function and mcp types don't resolve the MCP.
  • genie_poll_response returns no query_items after the response completes: Get the item_id from the Tool-call IDs comment at the end of the poll text, or capture structuredContent.query_items[].item_id from an earlier poll while the response was in flight.
  • item_id doesn't resolve in genie_get_query_result: A valid item_id looks like pub_..._output. Don't pass a query_... embed ID from the result-table comment markers as item_id because it won't resolve.

Additional resources​

On this page