Genie One MCP server: setup and migration

Databricks announced general availability of the Genie One MCP server on 22 September 2026. The documentation adds a deadline the announcement does not mention: the earlier Beta endpoint at /api/2.0/mcp/genie is deprecated and will be sunset on 31 October 2026, and every workload has to move to the new MCP Service before then.

Our read of the Databricks sources on 23 September 2026, inferences marked; if you sit on the old path, go straight to the migration.

What the Genie One MCP server is

The Genie One MCP server is a Databricks-provided MCP Service, system.ai.genie_one_mcp, governed through Unity Gateway. It exposes Genie over the Model Context Protocol: an MCP client sends a natural-language question, Genie searches the data, writes the SQL and returns an answer grounded in Genie Ontology, with links to its sources.

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

An MCP Service is a Unity Catalog securable named catalog.schema.mcp_service: Unity Gateway checks EXECUTE on it, narrows which tools it exposes, evaluates any service policy and records every call. We cannot wrap Genie in one of our own, since there is no SQL DDL for MCP Services. Five tools:

Clients that support MCP Apps, an optional extension of the open protocol, get an interactive view of progress and charts; the rest receive text. Genie Ontology, the semantic layer behind the business terms, is still labeled a preview; see the Genie Ontology explainer, the three Genie products compared and, for people rather than agents, the Genie One desktop app.

Status on the day we checked

The documentation page, last updated 21 September 2026, states general availability with no preview banner. The blog announcement and its companion post are dated 22 September. The release note is dated 25 September, a forward date already published on 23 September.

The managed MCP servers overview still wears a Public Preview banner while listing this server; Databricks says those servers sit at different release stages, so the specific page wins.

Before you connect

The last two items are inferred rather than documented for MCP callers.

• A Unity Catalog-enabled workspace in a region where Model Serving is supported.
• EXECUTE on the service, plus USE CATALOG and USE SCHEMA on the parents. Account users hold all three on system.ai by default, so usually there is nothing to grant.
• An OAuth application carrying the ai-gateway scope, created by an account admin, or the Unity Gateway CLI, which needs none. On-behalf-of user OAuth is recommended, service principals serve automated workloads, and a personal access token sent as Authorization: Bearer <YOUR_TOKEN> works for local testing.
• A client that does not require dynamic client registration, which Databricks does not support, with its outbound IP addresses allowlisted if the workspace restricts access by IP.
• CAN USE on at least one SQL warehouse. Inferred. Chat in Genie One requires it and picks a warehouse automatically; the MCP server runs on Chat in Genie One, but its page does not say so.
• Access to the underlying Genie Agent. Documented for the other server. The client-setup page lists it in a sentence that reads as the per-agent server, so we satisfy both.

Connect a client

The Databricks client examples all show the older /api/2.0/mcp/ URL; each block below has the Genie One URL substituted, with your hostname and credential left to fill in. We could not run them against a workspace.

Claude Code, Cursor and Codex: the Unity Gateway CLI

No OAuth application: the CLI signs in through an existing Databricks CLI login and registers the server as a local proxy that refreshes tokens from the CLI profile. Prerequisites: the Databricks CLI, authenticated with databricks auth login, and uv; the repository adds Python 3.12 or newer. ug is a launcher: it prompts for a workspace on first launch, and for Claude Code manages ~/.claude.json and the enterprise managed settings path, backing up every file it overwrites; ug revert restores the backups.

uv tool install git+https://github.com/databricks/unity-gateway
ug mcp add --agents claude --names system.ai.genie_one_mcp
ug mcp list
ug claude

Swap claude for cursor or codex in the second and last lines; ug mcp list shows each server's connection status.

The OAuth application, for everything else

An account admin creates it under Settings, then App Connections, then Add connection in the account console, or with the CLI; the documented least-privilege example targets this service:

databricks account custom-app-integration create --json '{
  "name": "mcp-public-oauth-app",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["ai-gateway", "offline_access"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

Account-level, so authenticate the CLI against the account console first. "confidential": false makes a public client, with an empty client_secret in the response; in the console, leave the Generate a client secret box unchecked.

Claude Code, without the CLI

Register http://localhost:8080/callback as the redirect URL, matching the callback port below.

claude mcp add-json genie-one '{
  "type": "http",
  "url": "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp",
  "oauth": {
    "clientId": "<your-client-id>",
    "callbackPort": 8080
  }
}'

The documented command ends with --client-secret, for a confidential client per Databricks; ours is public, so the flag comes off.

Claude, as a custom connector

Register https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback as redirect URLs, then in Claude go to Settings, then Connectors, then Add custom connector, with the Genie One URL and the client id.

Claude Desktop

It goes through mcp-remote; the file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Restart the app afterwards.

{
  "mcpServers": {
    "genie-one": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp",
        "--header",
        "Authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}

Cursor and Windsurf

Cursor's file is ~/.cursor/mcp.json, Windsurf's ~/.codeium/windsurf/mcp_config.json. With a personal access token the editor reaches the server directly over Streamable HTTP.

{
  "mcpServers": {
    "genie-one": {
      "type": "streamable-http",
      "url": "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

With OAuth, both editors go through mcp-remote and a static client. The Databricks page names no redirect URL here and defers to the mcp-remote repository, so two details come from that README, not from Databricks. Port: mcp-remote derives its callback port from the server URL unless one is passed after the URL; host and path default to localhost and /oauth/callback, so we pass 3334 and register http://localhost:3334/oauth/callback. Placeholders: the README expands ${ENV_VAR} with braces, and the $MCP_REMOTE_CLIENT_ID form on the Databricks page is shell syntax an editor reading JSON will not expand. The variables must be visible to the editor process, not only to a terminal.

{
  "mcpServers": {
    "genie-one": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp",
        "3334",
        "--static-oauth-client-info",
        "{ \"client_id\": \"${MCP_REMOTE_CLIENT_ID}\" }"
      ]
    }
  }
}

The public-client form. For a confidential client, Databricks adds "client_secret": "${MCP_REMOTE_CLIENT_SECRET}" and that variable alongside the first.

ChatGPT

ChatGPT needs Developer Mode and a Business, Enterprise or Edu workspace. Register https://chatgpt.com/connector_platform_oauth_redirect as the redirect URL, then Settings, then Apps, then Create App, with the Genie One URL and the client id.

How a question flows through the server

Answers are asynchronous, because Genie searches data and runs SQL; code written against a single request and reply will not work.

1. genie_askStarts a response; returns conversation_id and response_id, status in_progress.
2. genie_poll_responsePolled until the status is completed, incomplete or failed, surfacing progress.
3. genie_get_query_resultFor the full schema and rows rather than the truncated preview.
4. genie_askThe follow-up reuses the same conversation_id.

First results are truncated to protect the context window, so an agent summarizing the first payload may be summarizing a fragment. genie_get_query_result returns the full schema and rows, though very large results are still capped and Databricks publishes no number for the cap. Let one genie_poll_response call finish before issuing the next.

Three things belong in code, not with the model: the warehouse_id _meta parameter on genie_ask or view_ask picks the SQL warehouse, and _meta parameters are presets set in code, not arguments the model writes; the tools return a typed JSON object in structuredContent; and tools/list at runtime, rather than hardcoded tool names, also confirms which server we reached.

Migrate off the Beta endpoint before 31 October

The notice is on the Genie One MCP page and in the release note, and in neither blog post: the Beta endpoint at https://<workspace-hostname>/api/2.0/mcp/genie will be sunset on 31 October 2026.

1. Start the OAuth scope change first; it waits on an account admin. Add ai-gateway and offline_access to the existing application or create a new one, keeping genie if the same application also serves per-agent Genie Agent clients.
2. Inventory everything containing api/2.0/mcp/genie: client configuration files, agent code, notebooks, Databricks Apps, source control.
3. Split the matches. The bare path migrates; anything with a space id after it is the per-agent server and stays, per the caveat above.
4. Confirm the service exists in each workspace, under Unity Gateway, then MCPs. If system.ai.genie_one_mcp is not there yet, wait.
5. Repoint the bare-path clients to https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp.
6. Confirm EXECUTE on the service and the two parent privileges. Account users usually hold all three on system.ai.
7. Re-authenticate each client and run one question end to end; the flow section covers the poll loop, truncation and tools/list.
8. Decide who is billed. User usage is free through 31 January 2027; a service principal is billed, so moving an agent onto one changes the bill.
9. Check whether service policies and tool selection apply here at all: they are Beta, and the documentation disagrees on whether a built-in service accepts them; see below.

The gaps. Databricks publishes no migration guide, tooling, shim or redirect. It does not say what a client on the old path will see after 31 October, so we plan for it to stop working rather than fail gracefully. And the managed servers once sat behind a workspace preview toggle; nothing published says whether the old endpoint still depends on one.

Which Databricks MCP path is which

Databricks lists five managed MCP servers, plus the built-in MCP Services in system.ai and custom servers on Databricks Apps, all with Databricks as server and our agent as client.

Two features with MCP in the name point the other way: Genie Code MCP makes Databricks the client, reaching out to external tools, and Unity Gateway Skills, a separate Beta with its own databricks-skill-registry server, shares governed agent skills rather than answering data questions; see our Skills explainer.

Between the two Genie servers: Genie One picks a matching Genie Agent per question, and Databricks warns routing accuracy may drop with many agents, the case for the per-agent server on one curated domain. We track Genie One, Unity AI Gateway and Genie Code on the roadmap, and everything Genie under the Genie topic.

Governance, limits and cost

The page on governing an MCP Service says tool selection and service policies cover Databricks-provided services too, and the Genie One page agrees on service policies; the page listing Databricks-provided services says built-in services ship with platform-managed tools and a built-in policy and are governed with grants alone. Confirm in the Unity Gateway UI before planning a policy rollout on Genie One.

Where they agree: service policies, Beta, switched on by an account admin from the account console Previews page, inspect each tool call and optionally its result, then allow, deny or hold it for human approval. Tool selection takes prefix and exact-match patterns, not exclusions. Rate limits are in requests per minute, none until an admin sets one, at most 20 per service, 5 of them group-specific.

Every invocation lands in system.ai_gateway.usage and, as an mcpCall action, in system.access.audit.

SELECT * FROM system.ai_gateway.usage
WHERE service_type = 'MCP_SERVICE'

Two gotchas for automation. A bundle cannot express a grant on an MCP Service: the securable resource covers only volumes, tables, functions and connections, and databricks bundle validate does not flag the omission, so an agent deploys cleanly and fails on its first call. Grant through the permissions API instead.

databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/system.ai.genie_one_mcp" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'

data-team is the placeholder principal in the Databricks example.

And a Databricks App calling the service on behalf of a user declares user_api_scopes: [ai-gateway] on the app resource and calls through the per-user client, get_user_workspace_client().

Cost: it bills as Chat in Genie One, not a separate meter; the DBU-to-dollar anchor is in our Genie comparison.

Frequently asked questions

Is the Genie One MCP server generally available?

Yes, as of 23 September 2026, per the documentation, the blog and the release note. Rollout is staged, so check Unity Gateway, then MCPs.

Does the 31 October sunset affect the Genie Agent MCP server?

The notice names the bare /api/2.0/mcp/genie path; the per-agent server carries no deprecation notice but no exemption either, so unaffected is our reading, to confirm with support.

Can we use a personal access token?

Yes, as Authorization: Bearer <YOUR_TOKEN>, with OAuth recommended for production. No documented example uses it against the Unity Gateway URL and we have not, so test first.

Why does our client fail with an OAuth registration error?

Most likely it wants dynamic client registration, unsupported on managed MCP servers, MCP Services and Databricks-hosted servers. The other common cause is an IP access list missing the client's outbound addresses.

Do we pay extra for the MCP server?

No. It bills as Chat in Genie One: user usage free through 31 January 2027, service principals billed, compute billed separately.

Which clients show the interactive Genie view?

Those that support MCP Apps; the rest get text. Databricks publishes no list, nor does the extension's repository, so connect and look.

Is this the same thing as the MCP connectors announced on 10 September?

No. Those let Genie One and Genie Code reach outward into Slack, GitHub and Google Drive; this server lets an outside agent reach into Genie.

Sources

1. Genie One MCP server, AWS: status, URL, tools, flow, considerations, deprecation notice
2. Genie One MCP server, Azure: cross-cloud agreement
3. Genie One MCP server, Google Cloud: cross-cloud agreement
4. Connect agents to tools with MCP Services: securable model, requirements, tool selection, bundle gotcha, networking
5. Connect MCPs to AI assistants and coding agents: OAuth application, every client configuration, limitations
6. Databricks managed MCP servers: the server table, Genie One versus Databricks SQL
7. Databricks-provided MCP Services: the built-in list, the second general availability statement, the grants-not-policies position
8. Genie Agent MCP server: per-agent URL, read-only posture, table limit
9. Custom MCP servers: Databricks Apps, naming rule
10. Govern an MCP service: service policies, usage and audit tables
11. Rate limits: requests per minute, per-service limits
12. Unity Gateway Skills: the adjacent Beta and its own MCP server
13. Genie Code MCP: the outbound direction
14. Chat in Genie One: warehouse requirement, routing accuracy, Beta extras
15. Genie: the product family, free usage through 31 January 2027
16. September 2026 platform release notes: the general availability note, staged releases
17. AI/BI and Genie release notes 2026: May Beta, July MCP App, September connectors
18. Unity Gateway release notes: general availability, service policies still Beta, August connector move
19. The Genie One MCP is now Generally Available, Databricks blog, 22 September 2026: the announcement, vendor-authored
20. Genie One MCP: give any AI agent the right business context, Databricks blog, 22 September 2026: the per-agent recommendation, vendor-authored
21. Genie pricing, Databricks product page, vendor-authored: billing model
22. Genie One MCP Guide: Connect Governed Data to Any Agent, Databricks video, 17 September 2026, vendor-authored
23. databricks/unity-gateway: the ug CLI, its prerequisites, the files it manages and its local proxy
24. geelen/mcp-remote, the project the Databricks page points to, third-party: the OAuth callback port, host and path defaults and the ${ENV_VAR} expansion
25. Model Context Protocol specification: the protocol and the MCP Apps extension
26. modelcontextprotocol/ext-apps: the MCP Apps extension repository

Every status, URL, scope, date and configuration above was checked against the Databricks documentation on AWS, Azure and Google Cloud, the September 2026 platform release notes, the AI/BI and Unity Gateway release notes, both Databricks blog posts, the Genie pricing page and the linked GitHub repositories on 23 September 2026. We could not test a connection in a workspace, so the configurations are the documented patterns with the Genie One URL substituted, and the two uncertain requirements are labeled in the text. One detail is not Databricks': the callback port and the braced environment-variable syntax in the mcp-remote block come from that project's own repository, which the Databricks page refers readers to without naming a redirect URL. Databricks moves dates and release stages without notice, so verify before the 31 October sunset rather than after it. brickster.ai is an independent community project, not affiliated with, endorsed by, or sponsored by Databricks, Inc.