Connect non-Databricks clients to Databricks MCP servers

Beta

This feature is in Beta.

Connect non-Databricks (external) clients, AI assistants, and IDEs that support Model Context Protocol (MCP) to Databricks MCP servers. This provides access to Databricks data and tools directly in your development environment.

By connecting external clients to Databricks MCP servers, you can:

• Access Unity Catalog functions, tables, and vector indexes from your IDE or AI assistant
• Query Databricks data directly from Claude, Cursor, or other MCP-enabled tools
• Use external services through Databricks-managed authentication
• Leverage custom business logic without switching contexts

MCP server types

Databricks provides three types of MCP servers that support external client connections:

• Managed MCP servers: Databricks-hosted servers that provide instant access to Unity Catalog functions, vector search indexes, and Genie spaces.
• External MCP servers: Third-party MCP servers accessed through Databricks-managed proxies with Unity Catalog HTTP connections.
• Custom MCP servers: User-built MCP servers deployed and hosted on Databricks Apps.

Prerequisites

Before connecting clients, ensure you have:

• Server URLs: Get the appropriate server URLs for your chosen MCP server type:
  • Managed MCP servers
  • External MCP servers
  • Custom MCP servers
• Resource access: Verify that your account has access to the Unity Catalog resources you want to use
• Network access: If your workspace has IP restrictions, allowlist your client's IP addresses

Authentication methods

Choose the authentication method that best fits your security requirements:

Method	Managed/External MCP	Custom MCP	Security level	Best for
OAuth	Supported	Supported	High - scoped permissions, automatic token refresh	Production use, team environments, long-term access
Personal access tokens	Supported	Not supported	Medium - token-based access with expiration	Individual development, testing, short-term access

Set up OAuth or PAT authentication

Set up the authentication method that fits your use case:

note

Databricks MCP servers support both client types per the MCP Authorization specification:

• Public clients: No client secret required
• Confidential clients: Include client secret

Set up OAuth

Ask an account admin to create a Databricks OAuth application. You need the client ID and optionally a client secret from this application.

Using Account Console:

1. In the Databricks account console, go to Settings > App Connections > Add connection
2. Configure the application settings:
   • Add redirect URLs required by your external client
   • For public clients (like MCP Inspector), uncheck Generate a client secret
   • Set appropriate token expiration times

Using Databricks CLI:

Bash

databricks account custom-app-integration create --json '{
  "name": "mcp-public-client",
  "redirect_urls": ["https://redirectclient.com/callback"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

If your Databricks workspace has IP access restrictions, add your external client's outbound IP addresses to the allowlist.

Set up PAT

1. Generate a personal access token: Create a PAT in your Databricks workspace. See personal access tokens for detailed instructions.

2. Configure network access (if needed): If your Databricks workspace has IP access restrictions, add your client's outbound IP addresses to the allowlist.

Connect to managed and external MCP servers

Managed MCP servers provide instant access to Databricks resources such as Unity Catalog functions, vector search, and Genie spaces with no setup required.

External MCP servers let you access third-party MCP servers accessed through Databricks-managed proxies using Unity Catalog HTTP connections.

Both managed and external MCP servers support authentication from external clients using OAuth or personal access tokens (PAT).

Connect Claude Connectors using OAuth

Connect Claude to Databricks managed and external MCP servers:

1. Enable Claude Connectors: Set up Claude Connectors using Remote MCP

2. Create Claude-specific OAuth app: Use Claude's redirect URL in your OAuth application:

   Account Console:

   Navigate to Settings > App Connections > Add connection and include:

   • Redirect URL: https://claude.ai/api/mcp/auth_callback
   • Scopes: all-apis (required for Claude)

   Databricks CLI:

   Bash

   databricks account custom-app-integration create --json '{
     "name": "claude-mcp-client",
     "redirect_urls": ["https://claude.ai/api/mcp/auth_callback"],
     "confidential": false,
     "scopes": ["all-apis"],
     "token_access_policy": {
       "access_token_ttl_in_minutes": 60,
       "refresh_token_ttl_in_minutes": 10080
     }
   }'

3. Configure network access: Add Claude's outbound IP addresses to your workspace allowlist if you have IP restrictions

4. Add connector in Claude:

   1. Go to Settings > Connectors
   2. Click Add custom connector
   3. Add your Databricks MCP server URL
   4. Enter your OAuth application's Client ID
   5. Click Add to finish

   

Connect MCP Inspector using OAuth

The MCP Inspector is a developer tool for testing and debugging MCP servers.

Connect MCP Inspector to Databricks managed and external MCP servers:

1. Create Inspector-specific OAuth app: Include the Inspector's localhost redirect URLs:

   Account Console:

   Navigate to Settings > App Connections > Add connection and include:

   • Redirect URLs:
     • http://localhost:6274/oauth/callback
     • http://localhost:6274/oauth/callback/debug
   • Client type: Public (uncheck Generate a client secret)

   Databricks CLI:

   Bash

   databricks account custom-app-integration create --json '{
     "name": "mcp-inspector-client",
     "redirect_urls": [
        "http://localhost:6274/oauth/callback",
        "http://localhost:6274/oauth/callback/debug"
    ],
     "confidential": false,
     "scopes": ["all-apis"],
     "token_access_policy": {
       "access_token_ttl_in_minutes": 60,
       "refresh_token_ttl_in_minutes": 10080
     }
   }'

2. Configure MCP Inspector:

   1. Run the inspector: npx @modelcontextprotocol/inspector
   2. Set Transport Type to Streamable HTTP
   3. Enter your Managed MCP server URL
   4. In the Authentication section, add your OAuth Client ID
   5. Click Open Auth Settings and choose Guided or Quick flow
   6. After successful authentication, paste the access token in Bearer Token under the API Token Authentication section
   7. Click Connect

   

Personal access tokens (PAT) provide a simple way to authenticate with Databricks-managed MCP servers.

Connect Cursor with PAT

Cursor supports MCP through its settings configuration.

Connect Cursor to Databricks managed and external MCP servers:

1. Add server configuration: In your Cursor settings, add the following configuration. The example shows Unity Catalog functions, but adapt it for any managed MCP server URL path:

   JSON

   {
     "mcpServers": {
       "uc-function-mcp": {
         "type": "streamable-http",
         "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
         "headers": {
           "Authorization": "Bearer <YOUR_TOKEN>"
         },
         "note": "Databricks UC function"
       }
     }
   }

2. Replace placeholders: Update <your-workspace-hostname> and <YOUR_TOKEN> with your actual values.

Connect Claude Desktop using PAT

To use Databricks-managed MCP servers in Claude Desktop, use mcp-remote.

Connect Claude Desktop to Databricks managed and external MCP servers:

1. Locate configuration file: Find your claude_desktop_config.json file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add server configuration: Add the following to the configuration file. The example shows Unity Catalog functions, but adapt it for any managed MCP server URL path:

   JSON

   {
     "mcpServers": {
       "uc-function-mcp": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
           "--header",
           "Authorization: Bearer <YOUR_TOKEN>"
         ]
       }
     }
   }

3. Restart Claude Desktop: After updating the configuration, restart Claude Desktop for the changes to take effect.

Connect to custom MCP servers

Custom MCP servers are user-built applications hosted on Databricks Apps. Custom MCP servers only support OAuth authentication.

Connect Claude to custom MCP servers

If you have Claude Connectors using Remote MCP enabled, you can add custom MCP servers hosted on Databricks Apps.

To connect Claude to custom MCP servers, complete the following steps:

In Databricks:

note

OAuth applications must have all-apis scoping for Claude in beta.

1. Create a Claude-specific OAuth App Connection that includes Claude's redirect URLs:

   Account Console:

   Navigate to Settings > App Connections > Add connection

   Databricks CLI:

   Bash

   databricks account custom-app-integration create --json '{
     "name": "claude-mcp-public-client",
     "redirect_urls": ["https://claude.ai/api/mcp/auth_callback"],
     "confidential": false,
     "scopes": ["all-apis"],
     "token_access_policy": {
       "access_token_ttl_in_minutes": 60,
       "refresh_token_ttl_in_minutes": 10080
     }
   }'

2. Configure network access: If you have workspace IP access control list (ACL) restrictions, add Claude's outbound IP addresses to your workspace's allowlist.

In Claude:

1. Navigate to Settings > Connectors
2. Click Add custom connector
3. Add your custom MCP server URL (e.g., https://mcp-my-custom-server.<workspace-hostname>/mcp)
4. Add your OAuth App Integration Client ID and optional secret (if your client is confidential)
5. Click Add to finish configuring your connector

Limitations

• Dynamic client registration: Databricks does not support dynamic client registration OAuth flows for managed, external, or custom MCP servers. External clients and IDEs that mandate Dynamic Client Registration are not supported using OAuth authentication.
• Custom MCP server personal access token support: Custom MCP servers hosted on Databricks Apps do not support personal access tokens for authentication.
• On-behalf-of authorization: Custom MCP servers hosted on Databricks Apps do not support on-behalf-of-user authorization.

What's next

• Use managed MCP servers to connect agents to Unity Catalog data
• Use external MCP servers to access third-party services
• Host custom MCP servers for organization-specific tools