🔗 MCP Integration Patterns

What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI agents to tools and data sources.

Instead of writing custom integrations for each tool, agents use MCP to discover and call tools through a unified interface.

Three Types of MCP Servers

Databricks supports three MCP server types:

• Managed MCP - Databricks-hosted (Genie, Vector Search, UC Functions, DBSQL)
• External MCP - Third-party servers via UC HTTP connections
• Custom MCP - Your own servers hosted on Databricks Apps

All three are governed by Unity Catalog - permissions enforced, scopes validated.

Managed MCP Servers

Databricks-hosted MCP servers expose core platform capabilities:

• Genie - Natural language analytics on structured data
• Vector Search - Retrieval across unstructured content
• UC Functions - Deterministic tools registered in Unity Catalog
• DBSQL - SQL statement execution

URL Patterns

Each managed MCP server has a specific URL pattern:

• /api/2.0/mcp/genie/{space_id}
• /api/2.0/mcp/vector-search/{catalog}/{schema}
• /api/2.0/mcp/functions/{catalog}/{schema}
• /api/2.0/mcp/sql

Note: Genie requires polling for long-running queries.

External MCP Servers

Connect to third-party MCP servers through UC HTTP connections.

UC HTTP connections act as a secure proxy - your agent calls the connection, Databricks forwards to the external server with credentials managed in UC.

• External tools appear under UC governance
• Credentials stored in UC secret scopes
• Access controlled by UC permissions

UC HTTP Connection Pattern

Reference external MCP via UC connection:

uc://connections/{connection_name}

The connection stores:

• External MCP server URL
• Authentication credentials
• Headers and configuration

Custom MCP Servers

Host your own MCP servers on Databricks Apps.

Use cases:

• Organization-specific tools
• Custom data transformations
• Proprietary business logic
• Internal API wrappers

MCP Authentication

The three agent auth methods apply to MCP:

• Automatic Passthrough - Declare MCP servers at logging time, system SP handles auth
• OBO - Agent calls MCP with user's identity via DatabricksMCPClient
• Manual - Required for custom MCP (OAuth only)

Declare MCP URLs and scopes when logging your agent for verification at deploy time.

Required OAuth Scopes

Each MCP server type requires specific scopes:

• mcp.genie - Genie spaces
• mcp.functions - UC functions
• mcp.vectorsearch - Vector Search
• mcp.sql + sql.warehouses + sql.statement-execution - DBSQL
• mcp.external - External MCP via UC connections

Non-Databricks Clients

Connect external AI assistants to Databricks MCP servers:

• Claude - Via Claude Connectors
• Cursor/Windsurf - Via mcp-remote
• ChatGPT - Via Custom Apps
• MCP Inspector - For testing

Authentication options: OAuth (recommended) or PAT (managed/external only).

OAuth Setup for Clients

To connect external clients via OAuth:

1. Create OAuth app in Account Console
2. Configure redirect URLs for your client
3. Set appropriate scopes
4. Configure client with MCP server URL + OAuth credentials

Example redirect URLs:

• Claude: https://claude.ai/api/mcp/auth_callback
• MCP Inspector: http://localhost:6274/oauth/callback

Unity Catalog Governance

All MCP types are governed by Unity Catalog:

• Permissions checked before tool execution
• Scopes validated at deploy time
• Audit logs for all MCP calls
• Row filters and column masks apply to data returned

Key Takeaways

Managed MCP: Ready-to-use Databricks tools (Genie, VS, Functions, SQL).

External MCP: Third-party servers via UC HTTP connections.

Custom MCP: Your servers on Databricks Apps (OAuth only).

All governed by UC - declare dependencies, minimize scopes, permissions enforced.