Connecting Genie One to the Query MCP Server

Register the Query MCP server in Unity Catalog, then ask in plain English from Genie One or from a job

📘

TL;DR

Optional. One script registers the Query MCP server as a Unity Catalog connection and wraps it in an MCP service. Then ask the mesh in Genie One, or run ask_mcp_agent as a job. Each person authorizes for themselves, and authorization lasts a day.

What This Adds

The other pages have you write FSQL, or hand a detection to a Query Worker. This one lets you ask in plain English and have something else work out the query.

Query's MCP server exposes the mesh as a set of tools — list the connectors, search the schema, draft a statement, validate it, run it. Registered as a Unity Catalog connection, those tools become available to anything in Databricks that can call them.

Databricks Genie One is the one most people want. It is already in the workspace, it needs no code, and once the mesh is added as a source it will discover the schema, write the FSQL, validate it and run it on its own — so an analyst can ask "has this host talked to anything unusual this week" and get an answer from platforms that were never ingested.

The same connection also backs the ask_mcp_agent job, for the same question asked on a schedule or from a workflow.

This page is optional. The jobs and dashboard work without it, and run_fsql_query remains the path for unattended runs — see the limits below for why.

Register the Connection

./agent/deploy_connection.sh <profile>

Creates two Unity Catalog objects: an HTTP connection to the Query MCP server registered by Dynamic Client Registration, and an MCP service wrapping it. Databricks performs the registration itself — you supply a host and a path, and no token, header or client secret is stored anywhere.

Then authorize, once per person:

Catalog → External Data → Connections → query_mesh_mcp → Sign in

Add It to Genie One

Genie One home → + at the bottom left of the search bar → More connections → <catalog>.<schema>.query_mesh → Sign in

Each person signs in individually; OAuth tokens are not shared between users, which is what a per-user connection requires. After that, ask in the Genie One chat as you would of any other source.

Two things to expect. Genie One will not always reach for the mesh unprompted, so name it in the question — "using the Query mesh, find …". And a question that makes it search the schema before writing FSQL will take longer than one it can answer from a wildcard query.

Ask From a Job

For the same question on a schedule or from a workflow:

databricks bundle run ask_mcp_agent --profile <profile> \
  --params question="Which users signed in over the last 30 days?"

A Databricks foundation model drives the mesh's own MCP tools and writes the answer to mcp_agent_answers, with the tools it called and the turns it took.

What It Reaches

The server exposes the mesh's tools — listing connectors, searching the schema, generating a statement, validating it, executing it. The model chains them itself, so nothing in the job needs to know the statement. See the MCP Tool Reference.

tools_called is the evidence an answer came from the live mesh. An answer with no tools called is not a mesh answer.

Limits Worth Knowing First

❗

Authorization does not last

Query's refresh tokens expire 24 hours after issue, or after 12 hours idle. Expect to re-authorize daily and after any overnight gap. The failure is invalid_grant: Unknown or invalid refresh token; signing in again is the whole fix, and nothing needs recreating.

  • Per-user OAuth. A service principal cannot authorize. A job runs as whoever triggers it, so that identity must have signed in.
  • No scheduled mesh job. No schedule outlives the 24-hour ceiling. For unattended runs use run_fsql_query, which reads its token from the secret scope.
  • Genie One does not warn you when authorization expires. It simply stops reaching the mesh.
  • Name the mesh in your question. Tools do not always fire on their own.

Granting Access

Two grants, neither with a SQL form:

databricks grants update connection query_mesh_mcp --profile <profile> \
  --json '{"changes":[{"principal":"security-readers","add":["USE_CONNECTION"]}]}'
databricks grants update mcp_service my_catalog.my_schema.query_mesh --profile <profile> \
  --json '{"changes":[{"principal":"security-readers","add":["EXECUTE"]}]}'

One EXECUTE covers all the mesh's tools. A grant makes the connection visible; it does not lend your credential. Each person still signs in.

Checking the Connection

One call, no agent involved:

curl -sX POST "$HOST/api/2.0/mcp/external/query_mesh_mcp" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A tool list means healthy. Credential … is not found for the connection means that identity has not authorized.

🚧

Recreating the connection means recreating the service

Unity Catalog will not update a Dynamic Client Registration connection, so changing it means delete and recreate. That orphans the MCP service's binding, which keeps the stale client id — recreate the service too.


Did this page help you?