From b925a11c4309666e505c6d6fe55977d0fc12b2af Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 11:40:09 +0000 Subject: [PATCH 1/4] Add MCP service discovery, known services and naming for aitools Add the libs/aitools/mcp helpers that the `databricks aitools mcp` commands will use: Discover lists the MCP services in a schema with one paginated call and reports sign-in requirements from the source connection options, a static table describes the system.ai services, and naming and URL helpers build server names and service and sign-in URLs. The testserver gains GET /api/2.1/unity-catalog/mcp-services, which filters by parent and drops source connections unless view is FULL. Co-authored-by: Isaac --- libs/aitools/mcp/discovery.go | 146 ++++++++++++++++ libs/aitools/mcp/discovery_test.go | 245 +++++++++++++++++++++++++++ libs/aitools/mcp/known.go | 64 +++++++ libs/aitools/mcp/known_test.go | 41 +++++ libs/aitools/mcp/naming.go | 42 +++++ libs/aitools/mcp/naming_test.go | 69 ++++++++ libs/aitools/mcp/url.go | 15 ++ libs/aitools/mcp/url_test.go | 19 +++ libs/testserver/handlers.go | 4 + libs/testserver/mcp_services.go | 57 +++++++ libs/testserver/mcp_services_test.go | 68 ++++++++ 11 files changed, 770 insertions(+) create mode 100644 libs/aitools/mcp/discovery.go create mode 100644 libs/aitools/mcp/discovery_test.go create mode 100644 libs/aitools/mcp/known.go create mode 100644 libs/aitools/mcp/known_test.go create mode 100644 libs/aitools/mcp/naming.go create mode 100644 libs/aitools/mcp/naming_test.go create mode 100644 libs/aitools/mcp/url.go create mode 100644 libs/aitools/mcp/url_test.go create mode 100644 libs/testserver/mcp_services_test.go diff --git a/libs/aitools/mcp/discovery.go b/libs/aitools/mcp/discovery.go new file mode 100644 index 00000000000..7c475f90f65 --- /dev/null +++ b/libs/aitools/mcp/discovery.go @@ -0,0 +1,146 @@ +// Package mcp holds the logic behind `databricks aitools mcp`: discovery of Databricks managed +// MCP services, server naming, and service and sign-in URLs. +package mcp + +import ( + "context" + "errors" + "fmt" + "strings" + + "github.com/databricks/databricks-sdk-go" + "github.com/databricks/databricks-sdk-go/apierr" + "github.com/databricks/databricks-sdk-go/listing" + "github.com/databricks/databricks-sdk-go/service/catalog" +) + +// mcpServicePrefix is the resource-name prefix of an MCP service. +const mcpServicePrefix = "mcp-services/" + +// oauthProviderOption is the source connection option that marks a service as needing sign-in. +const oauthProviderOption = "oauth_provider" + +// listPageSize is the largest page the API allows for view=FULL. +const listPageSize = 200 + +// Service is an MCP service in a schema, as the API reports it. +type Service struct { + // FullName is catalog.schema.leaf. + FullName string + Leaf string + // Comment is the user-provided description from the API. + Comment string + // SignInRequired is true for services backed by a per-user connection. + SignInRequired bool + // OAuthProvider is the connection's oauth_provider option, empty when SignInRequired is false. + OAuthProvider string + // Known is the CLI's description of the service. It is nil outside system.ai and for + // system.ai services missing from the table. + Known *KnownService +} + +// Discover lists the MCP services in location (catalog.schema). Services whose source +// connection was deleted are dropped. Listing failures the CLI names are returned as *ListError. +func Discover(ctx context.Context, w *databricks.WorkspaceClient, location string) ([]Service, error) { + list, err := listServices(ctx, w, location) + if err != nil { + return nil, mapListError(location, err) + } + + services := make([]Service, 0, len(list)) + for i := range list { + if isDeletedSource(&list[i]) { + continue + } + services = append(services, newService(location, &list[i])) + } + return services, nil +} + +// ListErrorKind names a listing failure. Each value is the telemetry category name, so a +// caller can map it to telemetry without another table. +type ListErrorKind string + +const ( + ListErrLocationNotFound ListErrorKind = "MCP_LOCATION_NOT_FOUND" + ListErrPermissionDenied ListErrorKind = "MCP_PERMISSION_DENIED" + ListErrRateLimited ListErrorKind = "RATE_LIMITED" +) + +// ListError is a classified failure to list MCP services. It wraps the SDK error, so +// errors.Is(err, apierr.ErrNotFound) and similar still work. +type ListError struct { + Kind ListErrorKind + Location string + Err error +} + +func (e *ListError) Error() string { + switch e.Kind { + case ListErrLocationNotFound: + return e.Location + " is not a schema visible to this profile" + case ListErrPermissionDenied: + return fmt.Sprintf("cannot list MCP services in %s; needs USE on the schema and EXECUTE on the MCP service", e.Location) + default: + return "MCP service listing was rate limited; retry in a minute" + } +} + +func (e *ListError) Unwrap() error { + return e.Err +} + +func listServices(ctx context.Context, w *databricks.WorkspaceClient, location string) ([]catalog.McpService, error) { + return listing.ToSlice(ctx, w.AiGateway.ListMcpServices(ctx, catalog.ListMcpServicesRequest{ + Parent: "schemas/" + location, + View: catalog.ListMcpServicesRequestViewFull, + PageSize: listPageSize, + })) +} + +// mapListError classifies a listing failure. Other errors are returned with context only. +func mapListError(location string, err error) error { + var kind ListErrorKind + switch { + case errors.Is(err, apierr.ErrNotFound): + kind = ListErrLocationNotFound + case errors.Is(err, apierr.ErrPermissionDenied): + kind = ListErrPermissionDenied + case errors.Is(err, apierr.ErrTooManyRequests): + kind = ListErrRateLimited + default: + return fmt.Errorf("cannot list MCP services in %s: %w", location, err) + } + return &ListError{Kind: kind, Location: location, Err: err} +} + +func isDeletedSource(svc *catalog.McpService) bool { + return svc.Config != nil && svc.Config.SourceConnection != nil && svc.Config.SourceConnection.IsDeleted +} + +// oauthProvider returns the OAuth provider of a service's source connection, or "" when it +// has none. A non-empty provider means the user must sign in before the service is usable. +func oauthProvider(svc *catalog.McpService) string { + if svc.Config == nil || svc.Config.SourceConnection == nil { + return "" + } + return svc.Config.SourceConnection.Options[oauthProviderOption] +} + +func newService(location string, svc *catalog.McpService) Service { + fullName := strings.TrimPrefix(svc.Name, mcpServicePrefix) + leaf := strings.TrimPrefix(fullName, location+".") + provider := oauthProvider(svc) + + s := Service{ + FullName: fullName, + Leaf: leaf, + Comment: svc.Comment, + SignInRequired: provider != "", + OAuthProvider: provider, + } + if known, ok := knownSystemAI[leaf]; ok && location == systemAILocation { + s.Known = &known + } + return s +} diff --git a/libs/aitools/mcp/discovery_test.go b/libs/aitools/mcp/discovery_test.go new file mode 100644 index 00000000000..e46b587d9da --- /dev/null +++ b/libs/aitools/mcp/discovery_test.go @@ -0,0 +1,245 @@ +package mcp + +import ( + "encoding/json" + "errors" + "io" + "net/http" + "net/http/httptest" + "sync/atomic" + "testing" + + "github.com/databricks/databricks-sdk-go" + "github.com/databricks/databricks-sdk-go/apierr" + "github.com/databricks/databricks-sdk-go/service/catalog" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const discoveryTestListPath = "/api/2.1/unity-catalog/mcp-services" + +// discoveryTestGitHubProvider is the oauth_provider the API reports for GitHub. +const discoveryTestGitHubProvider = "OAUTH_PROVIDER_GITHUB_MCP" + +// discoveryTestServe starts a fake list endpoint that answers request i with pages[i] and +// returns a client for it. It fails the test on a wrong path or query and counts requests. +func discoveryTestServe(t *testing.T, location string, pages ...string) (*databricks.WorkspaceClient, *atomic.Int32) { + t.Helper() + var calls atomic.Int32 + server := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) { + // The SDK resolves host metadata before the first API call; that is not a list call. + if r.URL.Path != discoveryTestListPath { + http.NotFound(rw, r) + return + } + n := int(calls.Add(1)) + assert.Equal(t, "schemas/"+location, r.URL.Query().Get("parent")) + assert.Equal(t, "FULL", r.URL.Query().Get("view")) + if n > len(pages) { + http.Error(rw, `{"error_code":"INTERNAL_ERROR","message":"unexpected call"}`, http.StatusInternalServerError) + return + } + rw.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(rw, pages[n-1]) + })) + t.Cleanup(server.Close) + + w, err := databricks.NewWorkspaceClient(&databricks.Config{Host: server.URL, Token: "test-token"}) + require.NoError(t, err) + return w, &calls +} + +// discoveryTestPage marshals one list response page. +func discoveryTestPage(t *testing.T, nextPageToken string, services ...catalog.McpService) string { + t.Helper() + body, err := json.Marshal(catalog.ListMcpServicesResponse{McpServices: services, NextPageToken: nextPageToken}) + require.NoError(t, err) + return string(body) +} + +// discoveryTestInternal is a Databricks-owned service with no source connection. +func discoveryTestInternal(fullName string) catalog.McpService { + return catalog.McpService{Name: "mcp-services/" + fullName} +} + +// discoveryTestExternal is a service backed by a source connection with the given options. +func discoveryTestExternal(fullName string, options map[string]string) catalog.McpService { + return catalog.McpService{ + Name: "mcp-services/" + fullName, + Config: &catalog.McpServiceConfig{ + SourceConnection: &catalog.McpServiceConfigSourceConnection{ + Name: "connections/" + fullName, + Options: options, + }, + }, + } +} + +func TestDiscoverMakesOneCallForSingleSchemaPage(t *testing.T) { + w, calls := discoveryTestServe(t, "system.ai", + discoveryTestPage(t, "", discoveryTestInternal("system.ai.genie_one_mcp"), discoveryTestExternal("system.ai.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider})), + ) + + services, err := Discover(t.Context(), w, "system.ai") + require.NoError(t, err) + assert.Len(t, services, 2) + assert.Equal(t, int32(1), calls.Load()) +} + +func TestDiscoverFollowsPagination(t *testing.T) { + w, calls := discoveryTestServe(t, "main.tools", + discoveryTestPage(t, "page-2", discoveryTestInternal("main.tools.crm")), + discoveryTestPage(t, "", discoveryTestInternal("main.tools.billing")), + ) + + services, err := Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 2) + assert.Equal(t, "main.tools.crm", services[0].FullName) + assert.Equal(t, "main.tools.billing", services[1].FullName) + assert.Equal(t, int32(2), calls.Load()) +} + +func TestDiscoverDetectsSignInFromOptions(t *testing.T) { + tests := []struct { + name string + svc catalog.McpService + wantSignIn bool + wantProvider string + }{ + { + name: "internal service has no source connection", + svc: discoveryTestInternal("main.tools.crm"), + wantSignIn: false, + }, + { + name: "source connection with oauth_provider needs sign-in", + svc: discoveryTestExternal("main.tools.crm", map[string]string{"oauth_provider": discoveryTestGitHubProvider}), + wantSignIn: true, + wantProvider: discoveryTestGitHubProvider, + }, + { + name: "source connection without oauth_provider does not need sign-in", + svc: discoveryTestExternal("main.tools.crm", map[string]string{"client_id": "abc"}), + wantSignIn: false, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + w, _ := discoveryTestServe(t, "main.tools", discoveryTestPage(t, "", tt.svc)) + + services, err := Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, tt.wantSignIn, services[0].SignInRequired) + assert.Equal(t, tt.wantProvider, services[0].OAuthProvider) + }) + } +} + +func TestDiscoverDropsDeletedSourceConnections(t *testing.T) { + deleted := discoveryTestExternal("main.tools.old", map[string]string{"oauth_provider": discoveryTestGitHubProvider}) + deleted.Config.SourceConnection.IsDeleted = true + + w, _ := discoveryTestServe(t, "main.tools", + discoveryTestPage(t, "", deleted, discoveryTestInternal("main.tools.crm")), + ) + + services, err := Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, "main.tools.crm", services[0].FullName) + assert.Equal(t, "crm", services[0].Leaf) +} + +func TestDiscoverAttachesKnownOnlyInSystemAI(t *testing.T) { + github := discoveryTestExternal("system.ai.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider}) + github.Comment = "API comment" + custom := discoveryTestInternal("system.ai.custom") + + w, _ := discoveryTestServe(t, "system.ai", discoveryTestPage(t, "", github, custom)) + services, err := Discover(t.Context(), w, "system.ai") + require.NoError(t, err) + require.Len(t, services, 2) + require.NotNil(t, services[0].Known) + assert.Equal(t, "GitHub", services[0].Known.Label) + assert.Equal(t, "API comment", services[0].Comment) + assert.Nil(t, services[1].Known) + + w, _ = discoveryTestServe(t, "main.tools", discoveryTestPage(t, "", discoveryTestExternal("main.tools.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider}))) + services, err = Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Nil(t, services[0].Known) +} + +func TestDiscoverMapsListingErrors(t *testing.T) { + tests := []struct { + name string + status int + body string + wantKind ListErrorKind + wantSDK error + }{ + { + name: "missing schema is location not found", + status: http.StatusNotFound, + body: `{"error_code":"NOT_FOUND","message":"Schema 'main.tools' does not exist"}`, + wantKind: ListErrLocationNotFound, + wantSDK: apierr.ErrNotFound, + }, + { + name: "forbidden is permission denied", + status: http.StatusForbidden, + body: `{"error_code":"PERMISSION_DENIED","message":"User does not have USE SCHEMA"}`, + wantKind: ListErrPermissionDenied, + wantSDK: apierr.ErrPermissionDenied, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, _ *http.Request) { + rw.Header().Set("Content-Type", "application/json") + rw.WriteHeader(tt.status) + _, _ = io.WriteString(rw, tt.body) + })) + t.Cleanup(server.Close) + w, err := databricks.NewWorkspaceClient(&databricks.Config{Host: server.URL, Token: "test-token"}) + require.NoError(t, err) + + _, err = Discover(t.Context(), w, "main.tools") + var listErr *ListError + require.ErrorAs(t, err, &listErr) + assert.Equal(t, tt.wantKind, listErr.Kind) + assert.Equal(t, "main.tools", listErr.Location) + assert.ErrorIs(t, err, tt.wantSDK) + }) + } +} + +func TestMapListError(t *testing.T) { + tests := []struct { + name string + err error + wantKind ListErrorKind + }{ + {name: "rate limited", err: apierr.ErrTooManyRequests, wantKind: ListErrRateLimited}, + {name: "resource exhausted is rate limited", err: apierr.ErrResourceExhausted, wantKind: ListErrRateLimited}, + {name: "resource does not exist is location not found", err: apierr.ErrResourceDoesNotExist, wantKind: ListErrLocationNotFound}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var listErr *ListError + require.ErrorAs(t, mapListError("system.ai", tt.err), &listErr) + assert.Equal(t, tt.wantKind, listErr.Kind) + }) + } +} + +func TestMapListErrorLeavesOtherErrorsUnclassified(t *testing.T) { + err := mapListError("system.ai", apierr.ErrUnauthenticated) + + _, ok := errors.AsType[*ListError](err) + assert.False(t, ok) + assert.ErrorIs(t, err, apierr.ErrUnauthenticated) +} diff --git a/libs/aitools/mcp/known.go b/libs/aitools/mcp/known.go new file mode 100644 index 00000000000..8a8c34998fc --- /dev/null +++ b/libs/aitools/mcp/known.go @@ -0,0 +1,64 @@ +package mcp + +// systemAILocation is the schema that ships the Databricks managed MCP services. +const systemAILocation = "system.ai" + +// builtinServicesDocs is the public documentation page for the system.ai MCP services. +const builtinServicesDocs = "https://docs.databricks.com/aws/en/agents/mcp-tools/built-in-mcp-services" + +// KnownService is the CLI's own description of a system.ai service, keyed by leaf name. +type KnownService struct { + Leaf string + Label string + Summary string + Recommended bool + Beta bool + // Note is printed after install or sign-in. It is empty when there is nothing to add. + Note string + Docs string +} + +// knownSystemAI describes the system.ai services. Discovery from the API decides what is +// offered; this table only adds labels and notes, so an unlisted service still appears. +var knownSystemAI = map[string]KnownService{ + "genie_one_mcp": { + Leaf: "genie_one_mcp", Label: "Genie One", Summary: "Ask questions about your data", + Recommended: true, Docs: builtinServicesDocs, + }, + "dbsql": { + Leaf: "dbsql", Label: "Databricks SQL", Summary: "Run SQL on a SQL warehouse", + Beta: true, Note: "Available with the account-level Unity Gateway.", Docs: builtinServicesDocs, + }, + "web_search": { + Leaf: "web_search", Label: "Web search", Summary: "Search the public web", + Beta: true, Note: "Not for consumer-only users; off in HIPAA workspaces.", Docs: builtinServicesDocs, + }, + "sandbox": { + Leaf: "sandbox", Label: "Sandbox", Summary: "Run Python, SQL or shell in a sandbox", + Beta: true, Docs: builtinServicesDocs, + }, + "github": { + Leaf: "github", Label: "GitHub", Summary: "Repositories, issues, pull requests", + Note: "Public repositories only until a repository owner installs https://github.com/apps/databricks-github-connector", + Docs: builtinServicesDocs, + }, + "slack": { + Leaf: "slack", Label: "Slack", Summary: "Channels and messages", Docs: builtinServicesDocs, + }, + "atlassian": { + Leaf: "atlassian", Label: "Jira and Confluence", Docs: builtinServicesDocs, + }, + "google_drive": { + Leaf: "google_drive", Label: "Google Drive", Summary: "Drive, Docs, Sheets, Slides", Docs: builtinServicesDocs, + }, + "google_calendar": { + Leaf: "google_calendar", Label: "Google Calendar", Docs: builtinServicesDocs, + }, + "gmail": { + Leaf: "gmail", Label: "Gmail", Docs: builtinServicesDocs, + }, + "microsoft_365": { + Leaf: "microsoft_365", Label: "Microsoft 365", Summary: "SharePoint, Outlook, Teams", + Note: "`.All` scopes usually need tenant admin consent.", Docs: builtinServicesDocs, + }, +} diff --git a/libs/aitools/mcp/known_test.go b/libs/aitools/mcp/known_test.go new file mode 100644 index 00000000000..64397a246a6 --- /dev/null +++ b/libs/aitools/mcp/known_test.go @@ -0,0 +1,41 @@ +package mcp + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestKnownSystemAITable(t *testing.T) { + tests := []struct { + leaf string + label string + beta bool + recommended bool + }{ + {leaf: "genie_one_mcp", label: "Genie One", recommended: true}, + {leaf: "dbsql", label: "Databricks SQL", beta: true}, + {leaf: "web_search", label: "Web search", beta: true}, + {leaf: "sandbox", label: "Sandbox", beta: true}, + {leaf: "github", label: "GitHub"}, + {leaf: "slack", label: "Slack"}, + {leaf: "atlassian", label: "Jira and Confluence"}, + {leaf: "google_drive", label: "Google Drive"}, + {leaf: "google_calendar", label: "Google Calendar"}, + {leaf: "gmail", label: "Gmail"}, + {leaf: "microsoft_365", label: "Microsoft 365"}, + } + require.Len(t, knownSystemAI, len(tests)) + for _, tt := range tests { + t.Run(tt.leaf, func(t *testing.T) { + known, ok := knownSystemAI[tt.leaf] + require.True(t, ok) + assert.Equal(t, tt.leaf, known.Leaf) + assert.Equal(t, tt.label, known.Label) + assert.Equal(t, tt.beta, known.Beta) + assert.Equal(t, tt.recommended, known.Recommended) + assert.Equal(t, builtinServicesDocs, known.Docs) + }) + } +} diff --git a/libs/aitools/mcp/naming.go b/libs/aitools/mcp/naming.go new file mode 100644 index 00000000000..be2ac858bad --- /dev/null +++ b/libs/aitools/mcp/naming.go @@ -0,0 +1,42 @@ +package mcp + +import ( + "fmt" + "regexp" + "strings" + "sync" +) + +// invalidNameChars matches each run of characters that a server name cannot contain. +var invalidNameChars = sync.OnceValue(func() *regexp.Regexp { + return regexp.MustCompile(`[^a-z0-9_-]+`) +}) + +// Sanitize lowercases s, replaces each run of characters outside [a-z0-9_-] with "-", and +// trims leading and trailing "-". +func Sanitize(s string) string { + name := invalidNameChars().ReplaceAllString(strings.ToLower(s), "-") + return strings.Trim(name, "-") +} + +// ServerName returns the agent-facing name of a server for a service in location and a profile. +// Tool names in agents are mcp____, so the name must stay stable for the entry's life. +func ServerName(location, leaf, profile string) string { + if location == systemAILocation { + return Sanitize(leaf) + "-" + Sanitize(profile) + } + return Sanitize(location) + "-" + Sanitize(leaf) + "-" + Sanitize(profile) +} + +// UniqueName returns base, or base-2, base-3, ... for the first name that taken reports as free. +func UniqueName(base string, taken func(string) bool) string { + if !taken(base) { + return base + } + for n := 2; ; n++ { + candidate := fmt.Sprintf("%s-%d", base, n) + if !taken(candidate) { + return candidate + } + } +} diff --git a/libs/aitools/mcp/naming_test.go b/libs/aitools/mcp/naming_test.go new file mode 100644 index 00000000000..3de13dc42ff --- /dev/null +++ b/libs/aitools/mcp/naming_test.go @@ -0,0 +1,69 @@ +package mcp + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestSanitize(t *testing.T) { + tests := []struct { + in string + want string + }{ + {in: "logfood", want: "logfood"}, + {in: "Genie_One", want: "genie_one"}, + {in: "My.Profile", want: "my-profile"}, + {in: " --a..b-- ", want: "a-b"}, + {in: "..", want: ""}, + } + for _, tt := range tests { + t.Run(tt.in, func(t *testing.T) { + assert.Equal(t, tt.want, Sanitize(tt.in)) + }) + } +} + +func TestServerName(t *testing.T) { + tests := []struct { + name string + location string + leaf string + profile string + want string + }{ + {name: "system.ai keeps the leaf", location: "system.ai", leaf: "genie_one_mcp", profile: "logfood", want: "genie_one_mcp-logfood"}, + {name: "system.ai github", location: "system.ai", leaf: "github", profile: "dogfood", want: "github-dogfood"}, + {name: "customer schema includes catalog and schema", location: "main.tools", leaf: "crm", profile: "prod", want: "main-tools-crm-prod"}, + {name: "profile is sanitized", location: "system.ai", leaf: "dbsql", profile: "My.Profile", want: "dbsql-my-profile"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert.Equal(t, tt.want, ServerName(tt.location, tt.leaf, tt.profile)) + }) + } +} + +func TestUniqueName(t *testing.T) { + tests := []struct { + name string + base string + taken []string + want string + }{ + {name: "free base", base: "github-logfood", want: "github-logfood"}, + {name: "base taken", base: "github-logfood", taken: []string{"github-logfood"}, want: "github-logfood-2"}, + {name: "suffixes taken", base: "github-logfood", taken: []string{"github-logfood", "github-logfood-2"}, want: "github-logfood-3"}, + {name: "suffix only taken", base: "github-logfood", taken: []string{"github-logfood-2"}, want: "github-logfood"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + takenSet := make(map[string]bool) + for _, name := range tt.taken { + takenSet[name] = true + } + got := UniqueName(tt.base, func(name string) bool { return takenSet[name] }) + assert.Equal(t, tt.want, got) + }) + } +} diff --git a/libs/aitools/mcp/url.go b/libs/aitools/mcp/url.go new file mode 100644 index 00000000000..76b7e31d307 --- /dev/null +++ b/libs/aitools/mcp/url.go @@ -0,0 +1,15 @@ +package mcp + +import "net/url" + +// ServiceURL returns the streamable-HTTP endpoint of an MCP service. host is the workspace +// URL with its scheme, as config.Config.Host holds it. +func ServiceURL(host, fullName string) string { + return host + "/ai-gateway/mcp-services/" + fullName +} + +// SignInURL returns the page where a user signs in to a sign-in-required service. +func SignInURL(host, fullName, workspaceID string) string { + query := url.Values{"name": {fullName}, "o": {workspaceID}} + return host + "/mcp-service-login?" + query.Encode() +} diff --git a/libs/aitools/mcp/url_test.go b/libs/aitools/mcp/url_test.go new file mode 100644 index 00000000000..0f0aea19e86 --- /dev/null +++ b/libs/aitools/mcp/url_test.go @@ -0,0 +1,19 @@ +package mcp + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestServiceURL(t *testing.T) { + assert.Equal(t, + "https://adb-123.azuredatabricks.test/ai-gateway/mcp-services/system.ai.github", + ServiceURL("https://adb-123.azuredatabricks.test", "system.ai.github")) +} + +func TestSignInURL(t *testing.T) { + assert.Equal(t, + "https://adb-123.azuredatabricks.test/mcp-service-login?name=system.ai.github&o=2548836972759138", + SignInURL("https://adb-123.azuredatabricks.test", "system.ai.github", "2548836972759138")) +} diff --git a/libs/testserver/handlers.go b/libs/testserver/handlers.go index a021fd8b53a..00d3e1fc9af 100644 --- a/libs/testserver/handlers.go +++ b/libs/testserver/handlers.go @@ -923,6 +923,10 @@ func AddDefaultHandlers(server *Server) { return req.Workspace.McpServicesCreate(req) }) + server.Handle("GET", "/api/2.1/unity-catalog/mcp-services", func(req Request) any { + return req.Workspace.McpServicesList(req) + }) + server.Handle("GET", "/api/2.1/unity-catalog/mcp-services/{name}", func(req Request) any { return MapGet(req.Workspace, req.Workspace.McpServices, req.Vars["name"]) }) diff --git a/libs/testserver/mcp_services.go b/libs/testserver/mcp_services.go index 41200d06951..b4ae7c00d83 100644 --- a/libs/testserver/mcp_services.go +++ b/libs/testserver/mcp_services.go @@ -3,12 +3,18 @@ package testserver import ( "encoding/json" "fmt" + "maps" "net/http" + "slices" "strings" "github.com/databricks/databricks-sdk-go/service/catalog" ) +// mcpServicesViewFull is the list view that includes source connections. Any other view, +// including unset, omits them, as the API does. +const mcpServicesViewFull = "FULL" + // McpServicesCreate fakes POST /api/2.1/unity-catalog/mcp-services. See // ModelServicesCreate for the shape: the McpService body is sent directly, // parent and mcp_service_id are query parameters, and the map is keyed by the @@ -67,3 +73,54 @@ func (s *FakeWorkspace) McpServicesUpdate(req Request, name string) Response { Body: existing, } } + +// McpServicesList fakes GET /api/2.1/unity-catalog/mcp-services. It filters by parent +// (schemas/{catalog}.{schema}) and drops the source connection unless view is FULL, as the +// real API does. Pagination is not faked: every match is returned in one page. +func (s *FakeWorkspace) McpServicesList(req Request) Response { + defer s.LockUnlock()() + + query := req.URL.Query() + prefix := strings.TrimPrefix(query.Get("parent"), "schemas/") + "." + full := query.Get("view") == mcpServicesViewFull + + var services []catalog.McpService + for _, key := range slices.Sorted(maps.Keys(s.McpServices)) { + if !strings.HasPrefix(key, prefix) { + continue + } + ms := s.McpServices[key] + if !full && ms.Config != nil { + // Copy so the stored service keeps its source connection for later FULL reads. + config := *ms.Config + config.SourceConnection = nil + ms.Config = &config + } + services = append(services, ms) + } + + return Response{ + Body: catalog.ListMcpServicesResponse{McpServices: services}, + } +} + +// SeedMcpService stores an MCP service under fullName (catalog.schema.leaf) for list tests. +// An empty oauthProvider seeds an internal Databricks service with no source connection; +// otherwise the service is backed by a source connection with that OAuth provider. +func (s *FakeWorkspace) SeedMcpService(fullName, comment, oauthProvider string) { + defer s.LockUnlock()() + + ms := catalog.McpService{ + Name: "mcp-services/" + fullName, + Comment: comment, + } + if oauthProvider != "" { + ms.Config = &catalog.McpServiceConfig{ + SourceConnection: &catalog.McpServiceConfigSourceConnection{ + Name: "connections/" + fullName, + Options: map[string]string{"oauth_provider": oauthProvider}, + }, + } + } + s.McpServices[fullName] = ms +} diff --git a/libs/testserver/mcp_services_test.go b/libs/testserver/mcp_services_test.go new file mode 100644 index 00000000000..4801496d863 --- /dev/null +++ b/libs/testserver/mcp_services_test.go @@ -0,0 +1,68 @@ +package testserver + +import ( + "net/url" + "testing" + + "github.com/databricks/databricks-sdk-go/service/catalog" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// mcpServicesTestList calls the list handler with the given query string. +func mcpServicesTestList(t *testing.T, workspace *FakeWorkspace, rawQuery string) []catalog.McpService { + t.Helper() + u, err := url.Parse("/api/2.1/unity-catalog/mcp-services?" + rawQuery) + require.NoError(t, err) + + response := workspace.McpServicesList(Request{URL: u}) + require.Equal(t, 0, response.StatusCode) + body, ok := response.Body.(catalog.ListMcpServicesResponse) + require.True(t, ok) + return body.McpServices +} + +func mcpServicesTestWorkspace(t *testing.T) *FakeWorkspace { + t.Helper() + workspace := NewFakeWorkspace("http://test", "dbapi123") + workspace.SeedMcpService("system.ai.genie_one_mcp", "Genie", "") + workspace.SeedMcpService("system.ai.github", "GitHub", "OAUTH_PROVIDER_GITHUB_MCP") + workspace.SeedMcpService("main.tools.crm", "CRM", "OAUTH_PROVIDER_GITHUB_MCP") + return workspace +} + +func TestMcpServicesListFiltersByParent(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + services := mcpServicesTestList(t, workspace, "parent=schemas/system.ai&view=FULL") + require.Len(t, services, 2) + assert.Equal(t, "mcp-services/system.ai.genie_one_mcp", services[0].Name) + assert.Equal(t, "mcp-services/system.ai.github", services[1].Name) +} + +func TestMcpServicesListViewFullKeepsSourceConnection(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + services := mcpServicesTestList(t, workspace, "parent=schemas/system.ai&view=FULL") + require.Len(t, services, 2) + assert.Nil(t, services[0].Config) + require.NotNil(t, services[1].Config) + require.NotNil(t, services[1].Config.SourceConnection) + assert.Equal(t, "OAUTH_PROVIDER_GITHUB_MCP", services[1].Config.SourceConnection.Options["oauth_provider"]) +} + +func TestMcpServicesListViewBasicOmitsSourceConnection(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + for _, query := range []string{"parent=schemas/system.ai&view=BASIC", "parent=schemas/system.ai"} { + services := mcpServicesTestList(t, workspace, query) + require.Len(t, services, 2, query) + require.NotNil(t, services[1].Config, query) + assert.Nil(t, services[1].Config.SourceConnection, query) + } + + // BASIC must not strip the stored service, or a later FULL read would lose sign-in details. + services := mcpServicesTestList(t, workspace, "parent=schemas/system.ai&view=FULL") + require.NotNil(t, services[1].Config) + require.NotNil(t, services[1].Config.SourceConnection) +} From 0853362520f9ab7e6fa420203194a96551d86c27 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 11:57:01 +0000 Subject: [PATCH 2/4] Fix MCP discovery naming, listing errors and URL escaping Take the schema and leaf from the name the API returns, so a mixed-case --location still finds the leaf and the system.ai table. Name the grants listing needs and keep the server's message in listing errors. Collapse underscore runs in server names so agents cannot split them at "__". Escape the service name in the endpoint path. Use ListMcpServicesAll and drop table fields nothing reads. Co-authored-by: Isaac --- libs/aitools/mcp/discovery.go | 40 +++++++++++++++------------- libs/aitools/mcp/discovery_test.go | 38 ++++++++++++++++++++++++++ libs/aitools/mcp/known.go | 38 +++++++++++--------------- libs/aitools/mcp/known_test.go | 2 -- libs/aitools/mcp/naming.go | 16 ++++++++--- libs/aitools/mcp/naming_test.go | 6 +++++ libs/aitools/mcp/url.go | 2 +- libs/aitools/mcp/url_test.go | 6 +++++ libs/testserver/mcp_services.go | 14 +++++++--- libs/testserver/mcp_services_test.go | 9 ++++--- 10 files changed, 116 insertions(+), 55 deletions(-) diff --git a/libs/aitools/mcp/discovery.go b/libs/aitools/mcp/discovery.go index 7c475f90f65..607b39c301b 100644 --- a/libs/aitools/mcp/discovery.go +++ b/libs/aitools/mcp/discovery.go @@ -10,7 +10,6 @@ import ( "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/apierr" - "github.com/databricks/databricks-sdk-go/listing" "github.com/databricks/databricks-sdk-go/service/catalog" ) @@ -20,9 +19,6 @@ const mcpServicePrefix = "mcp-services/" // oauthProviderOption is the source connection option that marks a service as needing sign-in. const oauthProviderOption = "oauth_provider" -// listPageSize is the largest page the API allows for view=FULL. -const listPageSize = 200 - // Service is an MCP service in a schema, as the API reports it. type Service struct { // FullName is catalog.schema.leaf. @@ -52,13 +48,12 @@ func Discover(ctx context.Context, w *databricks.WorkspaceClient, location strin if isDeletedSource(&list[i]) { continue } - services = append(services, newService(location, &list[i])) + services = append(services, newService(&list[i])) } return services, nil } -// ListErrorKind names a listing failure. Each value is the telemetry category name, so a -// caller can map it to telemetry without another table. +// ListErrorKind names a listing failure. type ListErrorKind string const ( @@ -75,15 +70,20 @@ type ListError struct { Err error } +// Error names the likely cause and keeps the server's message, because the SDK maps +// different failures to the same sentinel (any 404, or a private link 403). func (e *ListError) Error() string { switch e.Kind { case ListErrLocationNotFound: - return e.Location + " is not a schema visible to this profile" + return fmt.Sprintf("%s is not a schema visible to this profile: %v", e.Location, e.Err) case ListErrPermissionDenied: - return fmt.Sprintf("cannot list MCP services in %s; needs USE on the schema and EXECUTE on the MCP service", e.Location) - default: - return "MCP service listing was rate limited; retry in a minute" + // Listing needs these two grants; services the caller cannot use are left out + // of the result instead of failing it. + return fmt.Sprintf("cannot list MCP services in %s (listing needs USE_CATALOG on the catalog and USE_SCHEMA on the schema): %v", e.Location, e.Err) + case ListErrRateLimited: + return fmt.Sprintf("MCP service listing in %s was rate limited; retry in a minute: %v", e.Location, e.Err) } + return fmt.Sprintf("cannot list MCP services in %s: %v", e.Location, e.Err) } func (e *ListError) Unwrap() error { @@ -91,11 +91,10 @@ func (e *ListError) Unwrap() error { } func listServices(ctx context.Context, w *databricks.WorkspaceClient, location string) ([]catalog.McpService, error) { - return listing.ToSlice(ctx, w.AiGateway.ListMcpServices(ctx, catalog.ListMcpServicesRequest{ - Parent: "schemas/" + location, - View: catalog.ListMcpServicesRequestViewFull, - PageSize: listPageSize, - })) + return w.AiGateway.ListMcpServicesAll(ctx, catalog.ListMcpServicesRequest{ + Parent: "schemas/" + location, + View: catalog.ListMcpServicesRequestViewFull, + }) } // mapListError classifies a listing failure. Other errors are returned with context only. @@ -127,9 +126,12 @@ func oauthProvider(svc *catalog.McpService) string { return svc.Config.SourceConnection.Options[oauthProviderOption] } -func newService(location string, svc *catalog.McpService) Service { +func newService(svc *catalog.McpService) Service { fullName := strings.TrimPrefix(svc.Name, mcpServicePrefix) - leaf := strings.TrimPrefix(fullName, location+".") + // The API returns lowercase names whatever casing the caller used for the location, so + // the schema and leaf come from the returned name. Unity Catalog names cannot contain ".". + dot := strings.LastIndex(fullName, ".") + namespace, leaf := fullName[:max(dot, 0)], fullName[dot+1:] provider := oauthProvider(svc) s := Service{ @@ -139,7 +141,7 @@ func newService(location string, svc *catalog.McpService) Service { SignInRequired: provider != "", OAuthProvider: provider, } - if known, ok := knownSystemAI[leaf]; ok && location == systemAILocation { + if known, ok := knownSystemAI[leaf]; ok && namespace == systemAILocation { s.Known = &known } return s diff --git a/libs/aitools/mcp/discovery_test.go b/libs/aitools/mcp/discovery_test.go index e46b587d9da..5468cf2d92d 100644 --- a/libs/aitools/mcp/discovery_test.go +++ b/libs/aitools/mcp/discovery_test.go @@ -173,6 +173,23 @@ func TestDiscoverAttachesKnownOnlyInSystemAI(t *testing.T) { assert.Nil(t, services[0].Known) } +func TestDiscoverTakesLeafFromReturnedNameForMixedCaseLocation(t *testing.T) { + w, _ := discoveryTestServe(t, "System.AI", discoveryTestPage(t, "", discoveryTestExternal("system.ai.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider}))) + services, err := Discover(t.Context(), w, "System.AI") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, "github", services[0].Leaf) + require.NotNil(t, services[0].Known) + assert.Equal(t, "GitHub", services[0].Known.Label) + + w, _ = discoveryTestServe(t, "Main.Tools", discoveryTestPage(t, "", discoveryTestInternal("main.tools.crm"))) + services, err = Discover(t.Context(), w, "Main.Tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, "crm", services[0].Leaf) + assert.Nil(t, services[0].Known) +} + func TestDiscoverMapsListingErrors(t *testing.T) { tests := []struct { name string @@ -180,6 +197,7 @@ func TestDiscoverMapsListingErrors(t *testing.T) { body string wantKind ListErrorKind wantSDK error + wantMsg string }{ { name: "missing schema is location not found", @@ -187,6 +205,7 @@ func TestDiscoverMapsListingErrors(t *testing.T) { body: `{"error_code":"NOT_FOUND","message":"Schema 'main.tools' does not exist"}`, wantKind: ListErrLocationNotFound, wantSDK: apierr.ErrNotFound, + wantMsg: "main.tools is not a schema visible to this profile: Schema 'main.tools' does not exist", }, { name: "forbidden is permission denied", @@ -194,6 +213,7 @@ func TestDiscoverMapsListingErrors(t *testing.T) { body: `{"error_code":"PERMISSION_DENIED","message":"User does not have USE SCHEMA"}`, wantKind: ListErrPermissionDenied, wantSDK: apierr.ErrPermissionDenied, + wantMsg: "cannot list MCP services in main.tools (listing needs USE_CATALOG on the catalog and USE_SCHEMA on the schema): User does not have USE SCHEMA", }, } for _, tt := range tests { @@ -213,6 +233,7 @@ func TestDiscoverMapsListingErrors(t *testing.T) { assert.Equal(t, tt.wantKind, listErr.Kind) assert.Equal(t, "main.tools", listErr.Location) assert.ErrorIs(t, err, tt.wantSDK) + assert.EqualError(t, err, tt.wantMsg) }) } } @@ -236,6 +257,23 @@ func TestMapListError(t *testing.T) { } } +func TestListErrorMessages(t *testing.T) { + cause := errors.New("server said no") + tests := []struct { + kind ListErrorKind + want string + }{ + {kind: ListErrRateLimited, want: "MCP service listing in system.ai was rate limited; retry in a minute: server said no"}, + {kind: "", want: "cannot list MCP services in system.ai: server said no"}, + } + for _, tt := range tests { + t.Run(string(tt.kind), func(t *testing.T) { + err := &ListError{Kind: tt.kind, Location: "system.ai", Err: cause} + assert.EqualError(t, err, tt.want) + }) + } +} + func TestMapListErrorLeavesOtherErrorsUnclassified(t *testing.T) { err := mapListError("system.ai", apierr.ErrUnauthenticated) diff --git a/libs/aitools/mcp/known.go b/libs/aitools/mcp/known.go index 8a8c34998fc..ba6e61af92d 100644 --- a/libs/aitools/mcp/known.go +++ b/libs/aitools/mcp/known.go @@ -3,62 +3,56 @@ package mcp // systemAILocation is the schema that ships the Databricks managed MCP services. const systemAILocation = "system.ai" -// builtinServicesDocs is the public documentation page for the system.ai MCP services. -const builtinServicesDocs = "https://docs.databricks.com/aws/en/agents/mcp-tools/built-in-mcp-services" - // KnownService is the CLI's own description of a system.ai service, keyed by leaf name. type KnownService struct { - Leaf string Label string Summary string Recommended bool Beta bool // Note is printed after install or sign-in. It is empty when there is nothing to add. Note string - Docs string } // knownSystemAI describes the system.ai services. Discovery from the API decides what is // offered; this table only adds labels and notes, so an unlisted service still appears. var knownSystemAI = map[string]KnownService{ "genie_one_mcp": { - Leaf: "genie_one_mcp", Label: "Genie One", Summary: "Ask questions about your data", - Recommended: true, Docs: builtinServicesDocs, + Label: "Genie One", Summary: "Ask questions about your data", + Recommended: true, }, "dbsql": { - Leaf: "dbsql", Label: "Databricks SQL", Summary: "Run SQL on a SQL warehouse", - Beta: true, Note: "Available with the account-level Unity Gateway.", Docs: builtinServicesDocs, + Label: "Databricks SQL", Summary: "Run SQL on a SQL warehouse", + Beta: true, Note: "Available with the account-level Unity Gateway.", }, "web_search": { - Leaf: "web_search", Label: "Web search", Summary: "Search the public web", - Beta: true, Note: "Not for consumer-only users; off in HIPAA workspaces.", Docs: builtinServicesDocs, + Label: "Web search", Summary: "Search the public web", + Beta: true, Note: "Not for consumer-only users; off in HIPAA workspaces.", }, "sandbox": { - Leaf: "sandbox", Label: "Sandbox", Summary: "Run Python, SQL or shell in a sandbox", - Beta: true, Docs: builtinServicesDocs, + Label: "Sandbox", Summary: "Run Python, SQL or shell in a sandbox", + Beta: true, }, "github": { - Leaf: "github", Label: "GitHub", Summary: "Repositories, issues, pull requests", + Label: "GitHub", Summary: "Repositories, issues, pull requests", Note: "Public repositories only until a repository owner installs https://github.com/apps/databricks-github-connector", - Docs: builtinServicesDocs, }, "slack": { - Leaf: "slack", Label: "Slack", Summary: "Channels and messages", Docs: builtinServicesDocs, + Label: "Slack", Summary: "Channels and messages", }, "atlassian": { - Leaf: "atlassian", Label: "Jira and Confluence", Docs: builtinServicesDocs, + Label: "Jira and Confluence", }, "google_drive": { - Leaf: "google_drive", Label: "Google Drive", Summary: "Drive, Docs, Sheets, Slides", Docs: builtinServicesDocs, + Label: "Google Drive", Summary: "Drive, Docs, Sheets, Slides", }, "google_calendar": { - Leaf: "google_calendar", Label: "Google Calendar", Docs: builtinServicesDocs, + Label: "Google Calendar", }, "gmail": { - Leaf: "gmail", Label: "Gmail", Docs: builtinServicesDocs, + Label: "Gmail", }, "microsoft_365": { - Leaf: "microsoft_365", Label: "Microsoft 365", Summary: "SharePoint, Outlook, Teams", - Note: "`.All` scopes usually need tenant admin consent.", Docs: builtinServicesDocs, + Label: "Microsoft 365", Summary: "SharePoint, Outlook, Teams", + Note: "`.All` scopes usually need tenant admin consent.", }, } diff --git a/libs/aitools/mcp/known_test.go b/libs/aitools/mcp/known_test.go index 64397a246a6..2b8ad314212 100644 --- a/libs/aitools/mcp/known_test.go +++ b/libs/aitools/mcp/known_test.go @@ -31,11 +31,9 @@ func TestKnownSystemAITable(t *testing.T) { t.Run(tt.leaf, func(t *testing.T) { known, ok := knownSystemAI[tt.leaf] require.True(t, ok) - assert.Equal(t, tt.leaf, known.Leaf) assert.Equal(t, tt.label, known.Label) assert.Equal(t, tt.beta, known.Beta) assert.Equal(t, tt.recommended, known.Recommended) - assert.Equal(t, builtinServicesDocs, known.Docs) }) } } diff --git a/libs/aitools/mcp/naming.go b/libs/aitools/mcp/naming.go index be2ac858bad..9f577cedc14 100644 --- a/libs/aitools/mcp/naming.go +++ b/libs/aitools/mcp/naming.go @@ -12,17 +12,25 @@ var invalidNameChars = sync.OnceValue(func() *regexp.Regexp { return regexp.MustCompile(`[^a-z0-9_-]+`) }) -// Sanitize lowercases s, replaces each run of characters outside [a-z0-9_-] with "-", and -// trims leading and trailing "-". +// underscoreRuns matches two or more "_" in a row. +var underscoreRuns = sync.OnceValue(func() *regexp.Regexp { + return regexp.MustCompile(`_{2,}`) +}) + +// Sanitize lowercases s, replaces each run of characters outside [a-z0-9_-] with "-", +// collapses runs of "_" into one, and trims leading and trailing "-" and "_". Agents name +// tools mcp____ and split on "__", so a part of a server name must not contain +// "__" or start or end with "_". func Sanitize(s string) string { name := invalidNameChars().ReplaceAllString(strings.ToLower(s), "-") - return strings.Trim(name, "-") + name = underscoreRuns().ReplaceAllString(name, "_") + return strings.Trim(name, "-_") } // ServerName returns the agent-facing name of a server for a service in location and a profile. // Tool names in agents are mcp____, so the name must stay stable for the entry's life. func ServerName(location, leaf, profile string) string { - if location == systemAILocation { + if strings.EqualFold(location, systemAILocation) { return Sanitize(leaf) + "-" + Sanitize(profile) } return Sanitize(location) + "-" + Sanitize(leaf) + "-" + Sanitize(profile) diff --git a/libs/aitools/mcp/naming_test.go b/libs/aitools/mcp/naming_test.go index 3de13dc42ff..d6ac5d98bca 100644 --- a/libs/aitools/mcp/naming_test.go +++ b/libs/aitools/mcp/naming_test.go @@ -16,6 +16,10 @@ func TestSanitize(t *testing.T) { {in: "My.Profile", want: "my-profile"}, {in: " --a..b-- ", want: "a-b"}, {in: "..", want: ""}, + {in: "prod_", want: "prod"}, + {in: "my__ws", want: "my_ws"}, + {in: "__a___b__", want: "a_b"}, + {in: "a_.b", want: "a_-b"}, } for _, tt := range tests { t.Run(tt.in, func(t *testing.T) { @@ -36,6 +40,8 @@ func TestServerName(t *testing.T) { {name: "system.ai github", location: "system.ai", leaf: "github", profile: "dogfood", want: "github-dogfood"}, {name: "customer schema includes catalog and schema", location: "main.tools", leaf: "crm", profile: "prod", want: "main-tools-crm-prod"}, {name: "profile is sanitized", location: "system.ai", leaf: "dbsql", profile: "My.Profile", want: "dbsql-my-profile"}, + {name: "system.ai location is case-insensitive", location: "System.AI", leaf: "github", profile: "prod", want: "github-prod"}, + {name: "trailing underscore cannot form __ before the tool name", location: "system.ai", leaf: "github", profile: "prod_", want: "github-prod"}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { diff --git a/libs/aitools/mcp/url.go b/libs/aitools/mcp/url.go index 76b7e31d307..609c0626cd4 100644 --- a/libs/aitools/mcp/url.go +++ b/libs/aitools/mcp/url.go @@ -5,7 +5,7 @@ import "net/url" // ServiceURL returns the streamable-HTTP endpoint of an MCP service. host is the workspace // URL with its scheme, as config.Config.Host holds it. func ServiceURL(host, fullName string) string { - return host + "/ai-gateway/mcp-services/" + fullName + return host + "/ai-gateway/mcp-services/" + url.PathEscape(fullName) } // SignInURL returns the page where a user signs in to a sign-in-required service. diff --git a/libs/aitools/mcp/url_test.go b/libs/aitools/mcp/url_test.go index 0f0aea19e86..2939dc2ad08 100644 --- a/libs/aitools/mcp/url_test.go +++ b/libs/aitools/mcp/url_test.go @@ -12,6 +12,12 @@ func TestServiceURL(t *testing.T) { ServiceURL("https://adb-123.azuredatabricks.test", "system.ai.github")) } +func TestServiceURLEscapesTheName(t *testing.T) { + assert.Equal(t, + "https://adb-123.azuredatabricks.test/ai-gateway/mcp-services/main.tools.crm%23v2", + ServiceURL("https://adb-123.azuredatabricks.test", "main.tools.crm#v2")) +} + func TestSignInURL(t *testing.T) { assert.Equal(t, "https://adb-123.azuredatabricks.test/mcp-service-login?name=system.ai.github&o=2548836972759138", diff --git a/libs/testserver/mcp_services.go b/libs/testserver/mcp_services.go index b4ae7c00d83..e43726ec2d0 100644 --- a/libs/testserver/mcp_services.go +++ b/libs/testserver/mcp_services.go @@ -11,6 +11,12 @@ import ( "github.com/databricks/databricks-sdk-go/service/catalog" ) +// Resource-name prefixes of MCP services and their parent schemas. +const ( + mcpServicesNamePrefix = "mcp-services/" + mcpServicesParentPrefix = "schemas/" +) + // mcpServicesViewFull is the list view that includes source connections. Any other view, // including unset, omits them, as the API does. const mcpServicesViewFull = "FULL" @@ -30,10 +36,10 @@ func (s *FakeWorkspace) McpServicesCreate(req Request) Response { } } - schema := strings.TrimPrefix(req.URL.Query().Get("parent"), "schemas/") + schema := strings.TrimPrefix(req.URL.Query().Get("parent"), mcpServicesParentPrefix) key := schema + "." + req.URL.Query().Get("mcp_service_id") - ms.Name = "mcp-services/" + key + ms.Name = mcpServicesNamePrefix + key ms.CreatedBy = s.CurrentUser().UserName ms.UpdatedBy = s.CurrentUser().UserName ms.EffectiveOwner = s.CurrentUser().UserName @@ -81,7 +87,7 @@ func (s *FakeWorkspace) McpServicesList(req Request) Response { defer s.LockUnlock()() query := req.URL.Query() - prefix := strings.TrimPrefix(query.Get("parent"), "schemas/") + "." + prefix := strings.TrimPrefix(query.Get("parent"), mcpServicesParentPrefix) + "." full := query.Get("view") == mcpServicesViewFull var services []catalog.McpService @@ -111,7 +117,7 @@ func (s *FakeWorkspace) SeedMcpService(fullName, comment, oauthProvider string) defer s.LockUnlock()() ms := catalog.McpService{ - Name: "mcp-services/" + fullName, + Name: mcpServicesNamePrefix + fullName, Comment: comment, } if oauthProvider != "" { diff --git a/libs/testserver/mcp_services_test.go b/libs/testserver/mcp_services_test.go index 4801496d863..cbc2fe96ce9 100644 --- a/libs/testserver/mcp_services_test.go +++ b/libs/testserver/mcp_services_test.go @@ -9,6 +9,9 @@ import ( "github.com/stretchr/testify/require" ) +// mcpServicesTestGitHubProvider is the oauth_provider the API reports for GitHub. +const mcpServicesTestGitHubProvider = "OAUTH_PROVIDER_GITHUB_MCP" + // mcpServicesTestList calls the list handler with the given query string. func mcpServicesTestList(t *testing.T, workspace *FakeWorkspace, rawQuery string) []catalog.McpService { t.Helper() @@ -26,8 +29,8 @@ func mcpServicesTestWorkspace(t *testing.T) *FakeWorkspace { t.Helper() workspace := NewFakeWorkspace("http://test", "dbapi123") workspace.SeedMcpService("system.ai.genie_one_mcp", "Genie", "") - workspace.SeedMcpService("system.ai.github", "GitHub", "OAUTH_PROVIDER_GITHUB_MCP") - workspace.SeedMcpService("main.tools.crm", "CRM", "OAUTH_PROVIDER_GITHUB_MCP") + workspace.SeedMcpService("system.ai.github", "GitHub", mcpServicesTestGitHubProvider) + workspace.SeedMcpService("main.tools.crm", "CRM", mcpServicesTestGitHubProvider) return workspace } @@ -48,7 +51,7 @@ func TestMcpServicesListViewFullKeepsSourceConnection(t *testing.T) { assert.Nil(t, services[0].Config) require.NotNil(t, services[1].Config) require.NotNil(t, services[1].Config.SourceConnection) - assert.Equal(t, "OAUTH_PROVIDER_GITHUB_MCP", services[1].Config.SourceConnection.Options["oauth_provider"]) + assert.Equal(t, mcpServicesTestGitHubProvider, services[1].Config.SourceConnection.Options["oauth_provider"]) } func TestMcpServicesListViewBasicOmitsSourceConnection(t *testing.T) { From d88fb85ef04c3a10c56d5c78dba5f81682c56eb8 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 12:10:36 +0000 Subject: [PATCH 3/4] Derive MCP server names from the service full name ServerName now takes the service full name, so the system.ai check comes from one source in any casing, and parts that sanitize to nothing are left out instead of leaving a stray "-". Listing errors for a missing endpoint, a disabled feature or private link keep the server's message without a schema or grants hint. The fake list handler matches the parent in any casing and uses the SDK's view constant; its seed helper moves into the test file. Co-authored-by: Isaac --- libs/aitools/mcp/discovery.go | 26 ++++++++++++++----- libs/aitools/mcp/discovery_test.go | 38 ++++++++++++++++++++++------ libs/aitools/mcp/naming.go | 35 ++++++++++++++++++++----- libs/aitools/mcp/naming_test.go | 18 ++++++------- libs/testserver/mcp_services.go | 36 +++++--------------------- libs/testserver/mcp_services_test.go | 33 +++++++++++++++++++++--- 6 files changed, 122 insertions(+), 64 deletions(-) diff --git a/libs/aitools/mcp/discovery.go b/libs/aitools/mcp/discovery.go index 607b39c301b..cca67957f0f 100644 --- a/libs/aitools/mcp/discovery.go +++ b/libs/aitools/mcp/discovery.go @@ -6,6 +6,7 @@ import ( "context" "errors" "fmt" + "slices" "strings" "github.com/databricks/databricks-sdk-go" @@ -77,8 +78,8 @@ func (e *ListError) Error() string { case ListErrLocationNotFound: return fmt.Sprintf("%s is not a schema visible to this profile: %v", e.Location, e.Err) case ListErrPermissionDenied: - // Listing needs these two grants; services the caller cannot use are left out - // of the result instead of failing it. + // Listing needs these two grants. Services the caller has no privilege on are + // left out of the result instead of failing it. return fmt.Sprintf("cannot list MCP services in %s (listing needs USE_CATALOG on the catalog and USE_SCHEMA on the schema): %v", e.Location, e.Err) case ListErrRateLimited: return fmt.Sprintf("MCP service listing in %s was rate limited; retry in a minute: %v", e.Location, e.Err) @@ -90,6 +91,7 @@ func (e *ListError) Unwrap() error { return e.Err } +// listServices reads every page of the services in location, with source connections. func listServices(ctx context.Context, w *databricks.WorkspaceClient, location string) ([]catalog.McpService, error) { return w.AiGateway.ListMcpServicesAll(ctx, catalog.ListMcpServicesRequest{ Parent: "schemas/" + location, @@ -97,8 +99,17 @@ func listServices(ctx context.Context, w *databricks.WorkspaceClient, location s }) } +// unrelatedErrorCodes are failures that look like a missing schema (404) or missing grants +// (403) but are about the workspace or network: the API is not available, or private link +// blocked the request. They keep the server's message and get no location or grants hint. +var unrelatedErrorCodes = []string{"ENDPOINT_NOT_FOUND", "FEATURE_DISABLED", "PRIVATE_LINK_VALIDATION_ERROR"} + // mapListError classifies a listing failure. Other errors are returned with context only. func mapListError(location string, err error) error { + if apiErr, ok := errors.AsType[*apierr.APIError](err); ok && slices.Contains(unrelatedErrorCodes, apiErr.ErrorCode) { + return fmt.Errorf("cannot list MCP services in %s: %w", location, err) + } + var kind ListErrorKind switch { case errors.Is(err, apierr.ErrNotFound): @@ -113,6 +124,7 @@ func mapListError(location string, err error) error { return &ListError{Kind: kind, Location: location, Err: err} } +// isDeletedSource reports whether the service's source connection was deleted. func isDeletedSource(svc *catalog.McpService) bool { return svc.Config != nil && svc.Config.SourceConnection != nil && svc.Config.SourceConnection.IsDeleted } @@ -126,12 +138,12 @@ func oauthProvider(svc *catalog.McpService) string { return svc.Config.SourceConnection.Options[oauthProviderOption] } +// newService builds a Service from an API service. The API returns lowercase names whatever +// casing the caller used for the location, so the leaf and the system.ai check use the +// returned name. func newService(svc *catalog.McpService) Service { fullName := strings.TrimPrefix(svc.Name, mcpServicePrefix) - // The API returns lowercase names whatever casing the caller used for the location, so - // the schema and leaf come from the returned name. Unity Catalog names cannot contain ".". - dot := strings.LastIndex(fullName, ".") - namespace, leaf := fullName[:max(dot, 0)], fullName[dot+1:] + leaf := leafOf(fullName) provider := oauthProvider(svc) s := Service{ @@ -141,7 +153,7 @@ func newService(svc *catalog.McpService) Service { SignInRequired: provider != "", OAuthProvider: provider, } - if known, ok := knownSystemAI[leaf]; ok && namespace == systemAILocation { + if known, ok := knownSystemAI[leaf]; ok && inSystemAI(fullName) { s.Known = &known } return s diff --git a/libs/aitools/mcp/discovery_test.go b/libs/aitools/mcp/discovery_test.go index 5468cf2d92d..41660b2afc0 100644 --- a/libs/aitools/mcp/discovery_test.go +++ b/libs/aitools/mcp/discovery_test.go @@ -59,13 +59,13 @@ func discoveryTestPage(t *testing.T, nextPageToken string, services ...catalog.M // discoveryTestInternal is a Databricks-owned service with no source connection. func discoveryTestInternal(fullName string) catalog.McpService { - return catalog.McpService{Name: "mcp-services/" + fullName} + return catalog.McpService{Name: mcpServicePrefix + fullName} } // discoveryTestExternal is a service backed by a source connection with the given options. func discoveryTestExternal(fullName string, options map[string]string) catalog.McpService { return catalog.McpService{ - Name: "mcp-services/" + fullName, + Name: mcpServicePrefix + fullName, Config: &catalog.McpServiceConfig{ SourceConnection: &catalog.McpServiceConfigSourceConnection{ Name: "connections/" + fullName, @@ -77,7 +77,7 @@ func discoveryTestExternal(fullName string, options map[string]string) catalog.M func TestDiscoverMakesOneCallForSingleSchemaPage(t *testing.T) { w, calls := discoveryTestServe(t, "system.ai", - discoveryTestPage(t, "", discoveryTestInternal("system.ai.genie_one_mcp"), discoveryTestExternal("system.ai.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider})), + discoveryTestPage(t, "", discoveryTestInternal("system.ai.genie_one_mcp"), discoveryTestExternal("system.ai.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider})), ) services, err := Discover(t.Context(), w, "system.ai") @@ -114,7 +114,7 @@ func TestDiscoverDetectsSignInFromOptions(t *testing.T) { }, { name: "source connection with oauth_provider needs sign-in", - svc: discoveryTestExternal("main.tools.crm", map[string]string{"oauth_provider": discoveryTestGitHubProvider}), + svc: discoveryTestExternal("main.tools.crm", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}), wantSignIn: true, wantProvider: discoveryTestGitHubProvider, }, @@ -138,7 +138,7 @@ func TestDiscoverDetectsSignInFromOptions(t *testing.T) { } func TestDiscoverDropsDeletedSourceConnections(t *testing.T) { - deleted := discoveryTestExternal("main.tools.old", map[string]string{"oauth_provider": discoveryTestGitHubProvider}) + deleted := discoveryTestExternal("main.tools.old", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}) deleted.Config.SourceConnection.IsDeleted = true w, _ := discoveryTestServe(t, "main.tools", @@ -153,7 +153,7 @@ func TestDiscoverDropsDeletedSourceConnections(t *testing.T) { } func TestDiscoverAttachesKnownOnlyInSystemAI(t *testing.T) { - github := discoveryTestExternal("system.ai.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider}) + github := discoveryTestExternal("system.ai.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}) github.Comment = "API comment" custom := discoveryTestInternal("system.ai.custom") @@ -166,7 +166,7 @@ func TestDiscoverAttachesKnownOnlyInSystemAI(t *testing.T) { assert.Equal(t, "API comment", services[0].Comment) assert.Nil(t, services[1].Known) - w, _ = discoveryTestServe(t, "main.tools", discoveryTestPage(t, "", discoveryTestExternal("main.tools.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider}))) + w, _ = discoveryTestServe(t, "main.tools", discoveryTestPage(t, "", discoveryTestExternal("main.tools.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}))) services, err = Discover(t.Context(), w, "main.tools") require.NoError(t, err) require.Len(t, services, 1) @@ -174,7 +174,7 @@ func TestDiscoverAttachesKnownOnlyInSystemAI(t *testing.T) { } func TestDiscoverTakesLeafFromReturnedNameForMixedCaseLocation(t *testing.T) { - w, _ := discoveryTestServe(t, "System.AI", discoveryTestPage(t, "", discoveryTestExternal("system.ai.github", map[string]string{"oauth_provider": discoveryTestGitHubProvider}))) + w, _ := discoveryTestServe(t, "System.AI", discoveryTestPage(t, "", discoveryTestExternal("system.ai.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}))) services, err := Discover(t.Context(), w, "System.AI") require.NoError(t, err) require.Len(t, services, 1) @@ -274,6 +274,28 @@ func TestListErrorMessages(t *testing.T) { } } +func TestMapListErrorLeavesWorkspaceAndNetworkFailuresUnclassified(t *testing.T) { + tests := []struct { + code string + status int + }{ + {code: "ENDPOINT_NOT_FOUND", status: http.StatusNotFound}, + {code: "FEATURE_DISABLED", status: http.StatusNotFound}, + {code: "PRIVATE_LINK_VALIDATION_ERROR", status: http.StatusForbidden}, + } + for _, tt := range tests { + t.Run(tt.code, func(t *testing.T) { + apiErr := &apierr.APIError{ErrorCode: tt.code, StatusCode: tt.status, Message: "server message"} + err := mapListError("system.ai", apiErr) + + _, ok := errors.AsType[*ListError](err) + assert.False(t, ok) + assert.ErrorIs(t, err, apiErr) + assert.EqualError(t, err, "cannot list MCP services in system.ai: server message") + }) + } +} + func TestMapListErrorLeavesOtherErrorsUnclassified(t *testing.T) { err := mapListError("system.ai", apierr.ErrUnauthenticated) diff --git a/libs/aitools/mcp/naming.go b/libs/aitools/mcp/naming.go index 9f577cedc14..36ae7a1ef0a 100644 --- a/libs/aitools/mcp/naming.go +++ b/libs/aitools/mcp/naming.go @@ -27,16 +27,37 @@ func Sanitize(s string) string { return strings.Trim(name, "-_") } -// ServerName returns the agent-facing name of a server for a service in location and a profile. -// Tool names in agents are mcp____, so the name must stay stable for the entry's life. -func ServerName(location, leaf, profile string) string { - if strings.EqualFold(location, systemAILocation) { - return Sanitize(leaf) + "-" + Sanitize(profile) +// ServerName returns the agent-facing name of the server for a service (catalog.schema.leaf) +// and a profile: - in system.ai, --- elsewhere. +// Each part is sanitized and parts that sanitize to nothing are left out. Tool names in +// agents are mcp____, so the name must stay stable for the entry's life. +func ServerName(fullName, profile string) string { + parts := strings.Split(fullName, ".") + if inSystemAI(fullName) { + parts = []string{leafOf(fullName)} } - return Sanitize(location) + "-" + Sanitize(leaf) + "-" + Sanitize(profile) + + var name []string + for _, part := range append(parts, profile) { + if s := Sanitize(part); s != "" { + name = append(name, s) + } + } + return strings.Join(name, "-") +} + +// leafOf returns the service name after the last ".". Unity Catalog names cannot contain ".". +func leafOf(fullName string) string { + return fullName[strings.LastIndex(fullName, ".")+1:] +} + +// inSystemAI reports whether a service full name is in system.ai, in any casing. +func inSystemAI(fullName string) bool { + return strings.HasPrefix(strings.ToLower(fullName), systemAILocation+".") } -// UniqueName returns base, or base-2, base-3, ... for the first name that taken reports as free. +// UniqueName returns base, or base-2, base-3, ... for the first candidate for which taken +// returns false. func UniqueName(base string, taken func(string) bool) string { if !taken(base) { return base diff --git a/libs/aitools/mcp/naming_test.go b/libs/aitools/mcp/naming_test.go index d6ac5d98bca..c3dc35f559b 100644 --- a/libs/aitools/mcp/naming_test.go +++ b/libs/aitools/mcp/naming_test.go @@ -31,21 +31,21 @@ func TestSanitize(t *testing.T) { func TestServerName(t *testing.T) { tests := []struct { name string - location string - leaf string + fullName string profile string want string }{ - {name: "system.ai keeps the leaf", location: "system.ai", leaf: "genie_one_mcp", profile: "logfood", want: "genie_one_mcp-logfood"}, - {name: "system.ai github", location: "system.ai", leaf: "github", profile: "dogfood", want: "github-dogfood"}, - {name: "customer schema includes catalog and schema", location: "main.tools", leaf: "crm", profile: "prod", want: "main-tools-crm-prod"}, - {name: "profile is sanitized", location: "system.ai", leaf: "dbsql", profile: "My.Profile", want: "dbsql-my-profile"}, - {name: "system.ai location is case-insensitive", location: "System.AI", leaf: "github", profile: "prod", want: "github-prod"}, - {name: "trailing underscore cannot form __ before the tool name", location: "system.ai", leaf: "github", profile: "prod_", want: "github-prod"}, + {name: "system.ai keeps the leaf", fullName: "system.ai.genie_one_mcp", profile: "logfood", want: "genie_one_mcp-logfood"}, + {name: "system.ai github", fullName: "system.ai.github", profile: "dogfood", want: "github-dogfood"}, + {name: "customer schema includes catalog and schema", fullName: "main.tools.crm", profile: "prod", want: "main-tools-crm-prod"}, + {name: "profile is sanitized", fullName: "system.ai.dbsql", profile: "My.Profile", want: "dbsql-my-profile"}, + {name: "system.ai is case-insensitive", fullName: "System.AI.github", profile: "prod", want: "github-prod"}, + {name: "trailing underscore cannot form __ before the tool name", fullName: "system.ai.github", profile: "prod_", want: "github-prod"}, + {name: "parts that sanitize to nothing are left out", fullName: "main.tools.\u9867\u5ba2", profile: "prod", want: "main-tools-prod"}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - assert.Equal(t, tt.want, ServerName(tt.location, tt.leaf, tt.profile)) + assert.Equal(t, tt.want, ServerName(tt.fullName, tt.profile)) }) } } diff --git a/libs/testserver/mcp_services.go b/libs/testserver/mcp_services.go index e43726ec2d0..1a2c9c05095 100644 --- a/libs/testserver/mcp_services.go +++ b/libs/testserver/mcp_services.go @@ -17,10 +17,6 @@ const ( mcpServicesParentPrefix = "schemas/" ) -// mcpServicesViewFull is the list view that includes source connections. Any other view, -// including unset, omits them, as the API does. -const mcpServicesViewFull = "FULL" - // McpServicesCreate fakes POST /api/2.1/unity-catalog/mcp-services. See // ModelServicesCreate for the shape: the McpService body is sent directly, // parent and mcp_service_id are query parameters, and the map is keyed by the @@ -81,18 +77,19 @@ func (s *FakeWorkspace) McpServicesUpdate(req Request, name string) Response { } // McpServicesList fakes GET /api/2.1/unity-catalog/mcp-services. It filters by parent -// (schemas/{catalog}.{schema}) and drops the source connection unless view is FULL, as the -// real API does. Pagination is not faked: every match is returned in one page. +// (schemas/{catalog}.{schema}, in any casing, as Unity Catalog names are case-insensitive) and +// drops the source connection unless view is FULL, as the real API does. Pagination is not +// faked: every match is returned in one page. func (s *FakeWorkspace) McpServicesList(req Request) Response { defer s.LockUnlock()() query := req.URL.Query() - prefix := strings.TrimPrefix(query.Get("parent"), mcpServicesParentPrefix) + "." - full := query.Get("view") == mcpServicesViewFull + prefix := strings.ToLower(strings.TrimPrefix(query.Get("parent"), mcpServicesParentPrefix)) + "." + full := query.Get("view") == string(catalog.ListMcpServicesRequestViewFull) var services []catalog.McpService for _, key := range slices.Sorted(maps.Keys(s.McpServices)) { - if !strings.HasPrefix(key, prefix) { + if !strings.HasPrefix(strings.ToLower(key), prefix) { continue } ms := s.McpServices[key] @@ -109,24 +106,3 @@ func (s *FakeWorkspace) McpServicesList(req Request) Response { Body: catalog.ListMcpServicesResponse{McpServices: services}, } } - -// SeedMcpService stores an MCP service under fullName (catalog.schema.leaf) for list tests. -// An empty oauthProvider seeds an internal Databricks service with no source connection; -// otherwise the service is backed by a source connection with that OAuth provider. -func (s *FakeWorkspace) SeedMcpService(fullName, comment, oauthProvider string) { - defer s.LockUnlock()() - - ms := catalog.McpService{ - Name: mcpServicesNamePrefix + fullName, - Comment: comment, - } - if oauthProvider != "" { - ms.Config = &catalog.McpServiceConfig{ - SourceConnection: &catalog.McpServiceConfigSourceConnection{ - Name: "connections/" + fullName, - Options: map[string]string{"oauth_provider": oauthProvider}, - }, - } - } - s.McpServices[fullName] = ms -} diff --git a/libs/testserver/mcp_services_test.go b/libs/testserver/mcp_services_test.go index cbc2fe96ce9..2a048451ae2 100644 --- a/libs/testserver/mcp_services_test.go +++ b/libs/testserver/mcp_services_test.go @@ -28,9 +28,9 @@ func mcpServicesTestList(t *testing.T, workspace *FakeWorkspace, rawQuery string func mcpServicesTestWorkspace(t *testing.T) *FakeWorkspace { t.Helper() workspace := NewFakeWorkspace("http://test", "dbapi123") - workspace.SeedMcpService("system.ai.genie_one_mcp", "Genie", "") - workspace.SeedMcpService("system.ai.github", "GitHub", mcpServicesTestGitHubProvider) - workspace.SeedMcpService("main.tools.crm", "CRM", mcpServicesTestGitHubProvider) + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") + mcpServicesTestSeed(workspace, "system.ai.github", "GitHub", mcpServicesTestGitHubProvider) + mcpServicesTestSeed(workspace, "main.tools.crm", "CRM", mcpServicesTestGitHubProvider) return workspace } @@ -43,6 +43,14 @@ func TestMcpServicesListFiltersByParent(t *testing.T) { assert.Equal(t, "mcp-services/system.ai.github", services[1].Name) } +func TestMcpServicesListMatchesParentInAnyCase(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + services := mcpServicesTestList(t, workspace, "parent=schemas/System.AI&view=FULL") + require.Len(t, services, 2) + assert.Equal(t, "mcp-services/system.ai.genie_one_mcp", services[0].Name) +} + func TestMcpServicesListViewFullKeepsSourceConnection(t *testing.T) { workspace := mcpServicesTestWorkspace(t) @@ -69,3 +77,22 @@ func TestMcpServicesListViewBasicOmitsSourceConnection(t *testing.T) { require.NotNil(t, services[1].Config) require.NotNil(t, services[1].Config.SourceConnection) } + +// mcpServicesTestSeed stores an MCP service under fullName (catalog.schema.leaf). +// An empty oauthProvider seeds an internal Databricks service with no source connection; +// otherwise the service is backed by a source connection with that OAuth provider. +func mcpServicesTestSeed(s *FakeWorkspace, fullName, comment, oauthProvider string) { + ms := catalog.McpService{ + Name: mcpServicesNamePrefix + fullName, + Comment: comment, + } + if oauthProvider != "" { + ms.Config = &catalog.McpServiceConfig{ + SourceConnection: &catalog.McpServiceConfigSourceConnection{ + Name: "connections/" + fullName, + Options: map[string]string{"oauth_provider": oauthProvider}, + }, + } + } + s.McpServices[fullName] = ms +} From a4521dadd7f2ddee90887a0ac8d9395f6a3c74aa Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 12:23:19 +0000 Subject: [PATCH 4/4] Tidy MCP discovery comments, notes and error mapping One return path for unclassified listing errors, doc comments on Unwrap and the testserver helper, the docs URL for the system.ai table, and terminal- friendly service notes. Co-authored-by: Isaac --- libs/aitools/mcp/discovery.go | 13 ++++++++----- libs/aitools/mcp/known.go | 10 ++++++---- libs/testserver/mcp_services_test.go | 1 + 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/libs/aitools/mcp/discovery.go b/libs/aitools/mcp/discovery.go index cca67957f0f..bf34adc7d6b 100644 --- a/libs/aitools/mcp/discovery.go +++ b/libs/aitools/mcp/discovery.go @@ -27,7 +27,8 @@ type Service struct { Leaf string // Comment is the user-provided description from the API. Comment string - // SignInRequired is true for services backed by a per-user connection. + // SignInRequired is true when the service's source connection has an oauth_provider, so + // each user signs in to the provider once. SignInRequired bool // OAuthProvider is the connection's oauth_provider option, empty when SignInRequired is false. OAuthProvider string @@ -87,6 +88,7 @@ func (e *ListError) Error() string { return fmt.Sprintf("cannot list MCP services in %s: %v", e.Location, e.Err) } +// Unwrap returns the SDK error. func (e *ListError) Unwrap() error { return e.Err } @@ -106,19 +108,20 @@ var unrelatedErrorCodes = []string{"ENDPOINT_NOT_FOUND", "FEATURE_DISABLED", "PR // mapListError classifies a listing failure. Other errors are returned with context only. func mapListError(location string, err error) error { - if apiErr, ok := errors.AsType[*apierr.APIError](err); ok && slices.Contains(unrelatedErrorCodes, apiErr.ErrorCode) { - return fmt.Errorf("cannot list MCP services in %s: %w", location, err) - } + apiErr, isAPIErr := errors.AsType[*apierr.APIError](err) var kind ListErrorKind switch { + case isAPIErr && slices.Contains(unrelatedErrorCodes, apiErr.ErrorCode): + // Not about the schema or grants: leave it unclassified. case errors.Is(err, apierr.ErrNotFound): kind = ListErrLocationNotFound case errors.Is(err, apierr.ErrPermissionDenied): kind = ListErrPermissionDenied case errors.Is(err, apierr.ErrTooManyRequests): kind = ListErrRateLimited - default: + } + if kind == "" { return fmt.Errorf("cannot list MCP services in %s: %w", location, err) } return &ListError{Kind: kind, Location: location, Err: err} diff --git a/libs/aitools/mcp/known.go b/libs/aitools/mcp/known.go index ba6e61af92d..9716b6d3c9b 100644 --- a/libs/aitools/mcp/known.go +++ b/libs/aitools/mcp/known.go @@ -13,8 +13,10 @@ type KnownService struct { Note string } -// knownSystemAI describes the system.ai services. Discovery from the API decides what is -// offered; this table only adds labels and notes, so an unlisted service still appears. +// knownSystemAI describes the system.ai services listed at +// https://docs.databricks.com/aws/en/agents/mcp-tools/built-in-mcp-services. Discovery from +// the API decides what is offered; this table only adds labels and notes, so an unlisted +// service still appears. var knownSystemAI = map[string]KnownService{ "genie_one_mcp": { Label: "Genie One", Summary: "Ask questions about your data", @@ -34,7 +36,7 @@ var knownSystemAI = map[string]KnownService{ }, "github": { Label: "GitHub", Summary: "Repositories, issues, pull requests", - Note: "Public repositories only until a repository owner installs https://github.com/apps/databricks-github-connector", + Note: "Public repositories only until a repository owner installs https://github.com/apps/databricks-github-connector.", }, "slack": { Label: "Slack", Summary: "Channels and messages", @@ -53,6 +55,6 @@ var knownSystemAI = map[string]KnownService{ }, "microsoft_365": { Label: "Microsoft 365", Summary: "SharePoint, Outlook, Teams", - Note: "`.All` scopes usually need tenant admin consent.", + Note: "Scopes ending in .All usually need tenant admin consent.", }, } diff --git a/libs/testserver/mcp_services_test.go b/libs/testserver/mcp_services_test.go index 2a048451ae2..c7166bbc908 100644 --- a/libs/testserver/mcp_services_test.go +++ b/libs/testserver/mcp_services_test.go @@ -25,6 +25,7 @@ func mcpServicesTestList(t *testing.T, workspace *FakeWorkspace, rawQuery string return body.McpServices } +// mcpServicesTestWorkspace returns a fake workspace with two system.ai services and one customer service. func mcpServicesTestWorkspace(t *testing.T) *FakeWorkspace { t.Helper() workspace := NewFakeWorkspace("http://test", "dbapi123")