Skip to content

Add MCP service discovery, known services and naming for aitools - #7538

Merged
simonfaltum merged 1 commit into
mainfrom
aitools-mcp/02-discovery
Nov 19, 2026
Merged

simonfaltum merged 1 commit into
mainfrom
aitools-mcp/02-discovery

Conversation

@simonfaltum

@simonfaltum simonfaltum commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

This is part of a stack that adds the hidden databricks aitools mcp command group, on top of #7539. This PR adds the helpers that group needs to find Databricks managed MCP services, name their servers and build their URLs. No command calls them yet.

Changes

  • Discover lists the services in a catalog.schema location with ListMcpServicesAll and view=FULL, so each source connection comes back. Other locations are refused before a request. Services with a deleted source connection are dropped.
  • Service.SignInRequired() is true when the source connection has an oauth_provider option. The schema and leaf come from the name the API returns, which Unity Catalog lowercases.
  • system.ai services get a label, summary and note from a static table of 11 services. Notes say which services need the Enhanced Unity Gateway preview, and the GitHub note names the GovCloud app. Other services carry only the API comment.
  • ServerName returns <leaf>-<profile> in system.ai and <catalog>-<schema>-<leaf>-<profile> elsewhere. Parts are sanitized to [a-z0-9_-] with _ runs collapsed, so no name contains __, which agents split tool names on. A leaf with no usable characters returns ErrNoServerName.
  • A name over 32 characters is cut and ends in 6 hex characters of the sha256 of the full name. UniqueName appends -2, -3, ... and stays within the cap.
  • ServiceURL builds the endpoint from mcpconfig.MCPServicesPathPrefix. SignInURL refuses an empty or none workspace ID, passes a numeric ID as o= and any other ID as w=. Its path and the schema parent prefix are the signInPath and schemaParentPrefix constants.
  • Listing failures return *ListError with kinds MCP_LOCATION_NOT_FOUND, MCP_PERMISSION_DENIED and RATE_LIMITED. Each keeps the server's message, since the SDK maps every 404, and a private-link 403, to the same sentinels. The 403 hint names USE_CATALOG and USE_SCHEMA and says an invalid access token gets the same error. ENDPOINT_NOT_FOUND, FEATURE_DISABLED and private-link failures get no hint.
  • The testserver serves the list endpoint, filtering by parent in any casing and omitting source connections unless view is FULL.

Why

Adding, listing and removing servers all need the same service list, names and sign-in check. With view=FULL the list response carries oauth_provider, so sign-in detection needs no per-service request. Built-in service docs: https://docs.databricks.com/aws/en/agents/mcp-tools/built-in-mcp-services

Decisions to review

  • Discovery does not retry on HTTP 429. The SDK already retries for up to five minutes, so another retry would double the wait.
  • The known table holds labels and notes only. Sign-in comes from the API, so a table entry cannot hide a service. Known is set only for system.ai, so a customer schema's github service gets no table entry.
  • UniqueName takes a taken function, so this package does not depend on the state file.

Tests

  • Discovery tests run against an httptest server: one call per page, pagination, sign-in detection, deleted connections, mixed-case locations, non-catalog.schema locations (no request), and 404 and 403 mapping with their messages.
  • TestKnownSystemAITable, TestSanitize, TestServerName*, TestUniqueName*, TestServiceURLEscapesTheName and TestSignInURL* cover naming, URLs and the workspace ID cases. Testserver tests cover FULL and BASIC output and parent filtering.
  • go test on both packages, golangci-lint and GOOS=windows go vet pass.
  • A read-only listing of schemas/System.AI on a real workspace returned the same 11 services, with lowercase names, as schemas/system.ai.

This pull request and its description were written by Isaac.

@simonfaltum
simonfaltum changed the base branch from main to aitools-mcp/01-agentconfig November 12, 2026 11:48
@simonfaltum
simonfaltum force-pushed the aitools-mcp/02-discovery branch from 0510ae3 to 27c9441 Compare November 12, 2026 11:49
@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: b5f9653

Run: 44517726534

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 272 19 10:36
💚​ aws-windows-latest-4core-16gb 1 274 17 8:38
💚​ azure linux-2core-8gb 1 271 19 10:18
💚​ azure-windows-latest-4core-16gb 1 273 17 8:42
💚​ gcp linux-2core-8gb 1 272 19 14:20
💚​ gcp-windows-latest-4core-16gb 1 274 17 11:56
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 9 slowest tests (at least 2 minutes):
duration env testname
4:04 gcp-windows-latest-4core-16gb TestAccept
3:43 gcp linux-2core-8gb TestFilerReadDir/workspace_files
3:22 gcp-windows-latest-4core-16gb TestFsCpFileToFileWithOverwriteFlag/dbfs_to_dbfs
2:57 aws-windows-latest-4core-16gb TestAccept
2:49 azure-windows-latest-4core-16gb TestAccept
2:39 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir
2:29 gcp-windows-latest-4core-16gb TestFilerReadWrite/dbfs
2:17 azure-windows-latest-4core-16gb TestFilerRecursiveDelete/workspace_files
2:01 aws-windows-latest-4core-16gb TestFilerRecursiveDelete/dbfs

@simonfaltum
simonfaltum force-pushed the aitools-mcp/02-discovery branch from 773f68b to 93a7090 Compare November 12, 2026 14:24
@simonfaltum
simonfaltum force-pushed the aitools-mcp/01-agentconfig branch from 6f07e48 to 07cc225 Compare November 13, 2026 15:05
@simonfaltum
simonfaltum force-pushed the aitools-mcp/02-discovery branch from 93a7090 to a4521da Compare November 13, 2026 15:05
@pietern pietern added the aitools AI tools (databricks aitools) related changes label Nov 16, 2026
@simonfaltum
simonfaltum force-pushed the aitools-mcp/01-agentconfig branch from 07cc225 to f178f46 Compare November 16, 2026 12:47
@simonfaltum
simonfaltum force-pushed the aitools-mcp/02-discovery branch 6 times, most recently from 5fedd5e to f1ff0ee Compare November 17, 2026 12:36
@simonfaltum
simonfaltum marked this pull request as ready for review November 18, 2026 16:20
@simonfaltum
simonfaltum requested review from a team and lennartkats-db as code owners November 18, 2026 16:20

@review-oss-bot review-oss-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me — no issues found.

@anton-107 anton-107 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed only what this PR adds on top of aitools-mcp/01-agentconfig. Unit tests, go vet (including GOOS=windows) and golangci-lint pass on libs/aitools/mcp and libs/testserver. I found nothing that blocks the merge.

Non-blocking notes:

  1. Sign-in detection (discovery.go, oauthProvider). The SDK documents source_connection.options as "options needed to build the U2M authorize request; when set, it includes authorization_endpoint, token_endpoint, oauth_scope, client_id, and oauth_provider". The test case where {"client_id": "abc"} means no sign-in describes a shape that contract says can't happen. That's fine for system.ai, which you checked live. Before add and login rely on SignInRequired() for customer schemas, it would help to check one service backed by a custom per-user U2M connection, to confirm it really reports oauth_provider.
  2. The w= branch in SignInURL. Downstream, auth.ResolveWorkspaceID formats an int64 unless the config has a workspace_id set by hand. So w= only applies to a hand-typed non-numeric ID. That's fine if the page really accepts it. If not, it's a fallback nobody needs.
  3. Testserver McpServicesList. It returns an empty list for an unknown parent, where the real API returns 404. Fine for now, but acceptance tests for the not-found path will need it.
  4. Naming stability. ServerName and capServerName are frozen once 03/04 persist names into agent configs (mcp__<name>__<tool>), so any later change renames tools for existing installs. That's worth a line in the 03-state PR.

@simonfaltum

Copy link
Copy Markdown
Member Author

Thanks for the review! On the notes:

  1. Agreed. SignInRequired() keys on oauth_provider and has only been checked against system.ai. None of the workspaces I can use has a service on a custom per-user U2M connection, so that case is untested. If such a connection doesn't report oauth_provider, add doesn't offer the sign-in and serve passes the gateway's challenge through unchanged, so it fails visibly rather than silently.
  2. Right, w= is only reached with a hand-set non-numeric workspace_id. It follows libs/auth/hostparams.go, which documents w= as the spelling that carries non-numeric IDs (o= stays numeric-only), and Add sign-in challenges and the authenticate tool to aitools mcp serve #7553 accepts either in challenge URLs. I haven't opened a w= sign-in link on a live workspace.
  3. Agreed. The fake doesn't tie MCP services to its schemas: the tests register system.ai services without creating that schema, so returning 404 for an unknown parent means seeding schemas first. I'll leave it until a not-found test needs it.
  4. Added to the decisions in Add MCP state records, drift check and profile binding checks #7537.

Base automatically changed from aitools-mcp/01-agentconfig to main November 19, 2026 11:05
One commit for the restack onto main. The individual commits, up to 09e8767, are in the pull request's history.

Co-authored-by: Isaac <no-reply@databricks.com>
@simonfaltum
simonfaltum force-pushed the aitools-mcp/02-discovery branch from 09e8767 to b5f9653 Compare November 19, 2026 11:42
@simonfaltum
simonfaltum added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit c0399aa Nov 19, 2026
28 checks passed
@simonfaltum
simonfaltum deleted the aitools-mcp/02-discovery branch November 19, 2026 12:24
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
…icks#7537)

This pull request is part of a stack, on top of databricks#7538, that adds the
hidden `databricks aitools mcp` command group. It adds MCP state
records, drift checks and profile binding checks. Nothing calls them
yet.

## Changes
- MCP records are the `mcp` section of the aitools state file (schema
v3). A file with only MCP records counts as no install. Installer saves
keep the section. Uninstall and `SaveMCPState` remove the file once
nothing remains.
- `Reconcile` reports `profile_missing` and `host_changed`, using the
host and workspace the SDK resolves, with no network.
- `Bind` checks the profile before it resolves credentials, so a
re-pointed host is never contacted.
- SDK configuration errors are `UNCATEGORIZED`. Only failed
authentication is `AUTH_FAILED`. `BindError.ExitCode()` returns 2, which
the `serve` PR maps to the process exit status.

## Why
A proxy must refuse to start when its profile was deleted or re-pointed,
or an agent would silently use the wrong workspace. It must never send
another workspace's credential.

## Decisions to review
- MCP records share the skills state file. A CLI older than schema v3
drops the `mcp` section on its next save, and its `uninstall` deletes a
file that holds only MCP records.
- An entry pinned to another config file fails the bind with
`PROFILE_HOST_CHANGED`, rather than printing the no-record notice,
because binding through this file would switch the server silently.
Changing `DATABRICKS_CONFIG_FILE` means removing and adding the server
again.
- An entry with no pinned config file is checked against
`~/.databrickscfg`, not `DATABRICKS_CONFIG_FILE`.
- Binding never reads `DATABRICKS_TOKEN` or other auth variables into
the profile. A profile without a token uses the SDK chain for its host.
- Host comparison ignores case, unlike `profile.WithHost`. A profile
that drops its workspace selector is not detected, since the recorded ID
may come from the API.
- Server names are frozen once records and agent entries hold them.
`ServerName` and `capServerName` from databricks#7538 produce them, and agents
name tools `mcp__<name>__<tool>`, which users' allow rules match, so
changing either function later renames the tools of every existing
install.

## Tests
- `TestBindHostChangedDoesNotContactNewHost` fails if a re-pointed host
gets a request. `TestBindWorkspaceFollowsSDKResolution` covers the host
query.
- `TestBindEntryInOtherConfigFileFailsClosed` and
`TestBindNeverUsesEnvTokenForProfileWithoutToken` cover the config-file
and credential rules.
- `TestUninstallRemovesLeftoverFilesWithoutSkills`,
`TestUpdateAfterPruningEverySkillAddsNewSkills` and
`TestInstallSpecificSkillWithEmptyStateFile` pass on main's behavior,
which users without MCP records keep.
- `TestLoadStateHidesOnlyMCPOnlyFiles` and
`TestUninstallKeepsStateFileWithMCPRecords` cover the shared file.
- Ran: race tests on the touched packages, `experimental/aitools` and
`cmd/aitools` acceptance tests (goldens unchanged), `GOOS=windows go
vet`, `golangci-lint` and `task checks`.
- Not run: the Windows and macOS test suites. No acceptance test covers
MCP-only output, since no CLI path writes MCP records yet.

This pull request and its description were written by Isaac.

Co-authored-by: Isaac <no-reply@databricks.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

aitools AI tools (databricks aitools) related changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants