feat(skill): add databricks-custom-mcp-server#550
Draft
dgokeeffe wants to merge 1 commit into
Draft
Conversation
Captures the end-to-end recipe for building a custom MCP server on
Databricks Apps and governing it through Unity Catalog + Supervisor
Agents — including the four-layer workaround for the (currently common)
case where the workspace OAuth server doesn't enable Dynamic Client
Registration.
Files
-----
- databricks-skills/databricks-custom-mcp-server/SKILL.md
Entry point. Frontmatter description packs failure-mode phrases a
developer will paste verbatim ("Authorization Server does NOT support
Dynamic Client Registration", "Duplicate tool name detected",
"redirect_uri not registered for OAuth application") so the skill
fires precisely when someone hits the same gauntlet.
- 1-build-fastmcp-server.md
FastMCP + FastAPI server skeleton, tool-design rules (type hints,
one-line docstring summaries, validate at the tool boundary),
Lakebase OAuth credential rotation, warehouse query helper, user-token
passthrough via x-forwarded-access-token.
- 2-deploy-as-databricks-app.md
app.yaml / manifest.yaml shape, SDK + CLI deploy paths, the SP grants
block that every tool downstream needs, smoke tests, restart-as-
recovery for the zombie-app state.
- 3-register-in-unity-catalog.md (the big one)
Path 1: register_mcp_server_via_dcr() with the Apps-SSO
requests.get monkey-patch needed for the discovery 401 handshake.
Path 2: the manual four-layer recipe when DCR isn't enabled
(account-admin custom OAuth integration → UC HTTP connection with
is_mcp_connection:true → detach duplicate tool_type=app → per-user
consent click). Includes the verification check that distinguishes
UC routing (underscore-style server_label) from app routing
(dash-style server_label).
- 4-attach-to-supervisor-agent.md
tool_type=app vs tool_type=uc_connection auth-model tradeoff,
duplicate-tool-name conflict resolution, mcp_approval_request
human-in-the-loop pattern, OpenAI-compatible serving-endpoint
invocation shape ("input" not "messages").
- scripts/register_mcp_in_uc.py
Idempotent four-layer registration script — drops + recreates the
UC connection, detaches duplicate app tools, attaches the
uc_connection tool on a supervisor. Supports --rotate-secret.
Registration
------------
- Added to DATABRICKS_SKILLS list in install_skills.sh
- Added get_skill_description + get_skill_extra_files cases
- Added to README.md under Development & Deployment
Tested
------
End-to-end against a workspace where DCR is disabled (the recipe was
distilled while wiring an ontology-bound MCP server for a real customer
demo). The verification check at the bottom of section 3 — server_label
shape — is what confirms catalog-native routing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a new skill
databricks-custom-mcp-servertodatabricks-skills/. Captures the end-to-end recipe for building a custom MCP server on Databricks Apps and governing it through Unity Catalog + Supervisor Agents — including the four-layer workaround for the (currently common) case where the workspace OAuth server doesn't yet enable Dynamic Client Registration.Why
There's no single Databricks doc page covering the full lifecycle: build → deploy → register in UC → attach to a Supervisor Agent. Each layer has at least one non-obvious gotcha:
Expected HTTP 401 from MCP URL for OAuth discovery, got 200registration_endpointAuthorization Server does NOT support Dynamic Client RegistrationMCPconnection type in UCCONNECTION_TYPE_NOT_SUPPORTEDonCREATE CONNECTION TYPE MCPinvalid_request: redirect_uri 'https://.../login/oauth/http.html' not registered for OAuth applicationtool_type=appandtool_type=uc_connectionregister the same MCP serverDuplicate tool name 'X' detected for agent 'main'The skill documents the workaround for each and bundles a reusable
scripts/register_mcp_in_uc.pythat codifies the four-layer recipe (account-admin custom OAuth integration → UC HTTP connection withis_mcp_connection:true→ detach duplicatetool_type=app→ user consent click).Files
SKILL.md— entry point with critical rules, surface-decision table, lifecycle diagram, validation checklist1-build-fastmcp-server.md— FastMCP + FastAPI skeleton, tool-design rules, user-token passthrough2-deploy-as-databricks-app.md—app.yaml, SDK + CLI deploy, SP grants, restart-as-recovery3-register-in-unity-catalog.md— Path 1 (DCR) + Path 2 (manual four-layer); verification viaserver_labelunderscore-vs-dash check4-attach-to-supervisor-agent.md—tool_type=appvstool_type=uc_connection,mcp_approval_requestflowscripts/register_mcp_in_uc.py— idempotent reference implementation of the four-layer recipeWiring:
DATABRICKS_SKILLSlist ininstall_skills.shget_skill_description+get_skill_extra_filescasesREADME.mdunder Development & DeploymentHow tested
Recipe distilled while wiring an ontology-bound MCP server for a real customer demo on a workspace where DCR is disabled. The verification check at the bottom of section 3 (
server_labelshape:_= UC route,-= app route) is what confirms catalog-native routing. All registration steps run via theregister_mcp_in_uc.pyscript idempotently.Status
Draft — opening for visibility / review queue. Ready to mark ready-for-review when the team has bandwidth.