Databricks integrations

@fabric-harness/databricks exposes composable factories and a databricks() bundle. Use the bundle for the common governed stack; use individual exports when you need a narrower integration.

Resource lifecycle APIs are covered in Databricks resource authoring.

To scaffold project wiring (managed files, env stubs, dependencies), use Databricks recipes:

fh add databricks sql
fh add lakebase
fh add ai-search
fh add lakeflow
fh add agent-services

Data and AI

Managed MCP and MCP Services

Use databricksWithManagedMcp() when a bundle consumes Databricks managed MCP servers or a Unity Catalog MCP Service through Unity AI Gateway. Discovery is asynchronous, so the synchronous databricks() factory rejects a configuration containing mcp rather than silently omitting its tools.

import {
  databricksPrincipalFromEnv,
  databricksWithManagedMcp,
} from '@fabric-harness/databricks';

const dbx = await databricksWithManagedMcp({
  host: process.env.DATABRICKS_HOST!,
  principal: databricksPrincipalFromEnv(process.env),
  governance: {
    catalogs: ['main'],
  },
  mcp: [
    {
      name: 'support_genie',
      endpoint: { kind: 'genie', spaceId: process.env.DATABRICKS_GENIE_SPACE_ID! },
    },
    {
      name: 'delivery',
      endpoint: { kind: 'mcp-service', name: 'main.agents.fabric_runway' },
      effects: {
        'runway_catalog': 'read',
        'runway_request_*': 'write',
      },
    },
  ],
});

// Remote names are stable and collision-safe.
console.log(dbx.tools.map((tool) => tool.name));
// mcp__support_genie__ask_genie, mcp__delivery__runway_catalog, ...

try {
  // Use dbx.modelProvider, dbx.tools, and dbx.policy with init().
} finally {
  await dbx.managedMcp.close();
}

The adapter builds the documented workspace URLs for Genie, AI Search, SQL, Unity Catalog functions, and /ai-gateway/mcp-services/<catalog.schema.name>. It obtains a fresh bearer token from the bundle's PAT, OAuth M2M, CLI-profile, or OBO provider on every transport request and refuses to send that token to another origin. Tokens are absent from tool metadata and redacted from connection and tool errors.

Genie and AI Search are classified read-only. SQL, Unity Catalog functions, registered MCP Services, and custom workspace URLs must supply effects globs or defaultEffect; otherwise discovery fails closed. Write/execute tools receive a static governed MCP resource, lineage, catalog policy, and approval binding through the same withGovernanceTools() path as native tools. Request-scoped Apps must call forPrincipalWithManagedMcp() and close the returned bundle after the request; the synchronous forPrincipal() method rejects principal reuse for remote connections.

Authentication requires a workspace bearer credential accepted by the selected managed server. A registered MCP Service also needs EXECUTE on the service and USE CATALOG / USE SCHEMA on its parents. Missing Preview enrollment, OAuth authorization, UC privilege, effect classification, or approval is returned as an error before the underlying mutation can execute.

Dynamic agents can mount the same governed connection conditionally. The connector is lazy: token resolution and tool discovery occur only when the current render declares it, and the runtime closes the connection after the interaction.

import { connectDatabricksManagedMcpServer } from '@fabric-harness/databricks';
import {
  createAgent,
  defineMcpConnection,
  useMcpConnection,
  usePersistentState,
} from '@fabric-harness/sdk';

const server = {
  name: 'catalog',
  endpoint: { kind: 'functions', catalog: 'main', schema: 'agent_tools' },
  defaultEffect: 'execute',
} as const;
const catalogTools = defineMcpConnection({
  name: server.name,
  connect: () => connectDatabricksManagedMcpServer({
    host: process.env.DATABRICKS_HOST!,
    tokenProvider: async () => process.env.DATABRICKS_TOKEN,
    server,
  }),
});

export default createAgent(() => {
  const [approved] = usePersistentState('catalogApproved', false);
  if (approved) useMcpConnection(catalogTools);
  return approved
    ? 'Use the governed catalog functions when needed.'
    : 'Complete approval before using catalog functions.';
});

For an employee-facing Databricks App, construct the definition with a request-scoped OBO token provider. For shared automation, use a least-privilege OAuth M2M provider. Raw workspace credentials must never enter persistent state or initial data.

Inference names and URLs

Use the workspace origin for DATABRICKS_HOST, not an API path. Fabric selects the inference base from the model name:

DATABRICKS_INFERENCE_MODE=auto is the default. Set ai-gateway or serving-endpoints only when overriding automatic routing. Use DATABRICKS_AI_GATEWAY_BASE_URL for a proxy or explicitly configured Gateway base. Discover services enabled in the current workspace with await bundle.aiGateway.listModelServices() instead of assuming every system.ai.* service is available.

Engineering and operations

Reuse from vertical applications

Application repositories must not create their own Databricks client package. Compose a principal with databricksPrincipalFromEnv(), use databricksSdk() for generated service clients, and use the bundle only for reviewed SDK gaps such as AI Gateway and SQL warehouse discovery.

For libraries that require fetch, createDatabricksAuthenticatedFetch() supplies a rotating workspace credential and bounds authorization retry to one 401/403 response. For SQL, runStatement() uses the generated Statement Execution client with named parameters and bounded polling. Provider-service and warehouse listings are available from bundle.aiGateway and bundle.sqlWarehouses; raw protocol transport remains private to Harness.

Add a standalone tool

import {
  databricksSdk,
  databricksFeatureLookupTool,
  withGovernance,
} from '@fabric-harness/databricks';

const principal = {
  kind: 'service-principal',
  host: process.env.DATABRICKS_HOST!,
  clientId: process.env.DATABRICKS_CLIENT_ID!,
  clientSecret: process.env.DATABRICKS_CLIENT_SECRET!,
} as const;

const sdk = databricksSdk({
  host: process.env.DATABRICKS_HOST!,
  principal,
});

const customerFeatures = withGovernance(
  databricksFeatureLookupTool(sdk.modelServingQuery, {
    endpoint: 'customer-features',
    name: 'lookup_customer_features',
  }),
  {
    principal: `sp:${process.env.DATABRICKS_CLIENT_ID}`,
    onLineage: (record) => auditSink.write(record),
  },
);

Integration boundaries

• Fabric Harness does not replace Unity Catalog permissions or Databricks resource ACLs.
• Managed MCP and Unity AI Gateway are Databricks Preview/Beta surfaces; run the protected live certification in every target workspace before release.
• The SQL tool and SQL sandbox execute statements; they do not provide a Linux shell.
• Workspace files and Unity Catalog Volumes are separate APIs and path spaces.
• databricks-serving is a proxy target, while databricks-app hosts the Node runtime.
• Availability and API behavior can vary by cloud, region, workspace feature enablement, and preview status. Validate each enabled integration in the target workspace.