Skip to main content
Last updated on

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, Replit, or other MCP-enabled tools

Prerequisites​

  • Server URLs: Get the appropriate server URLs for the Databricks MCP server you want to use:
  • 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

Connect clients using OAuth authentication​

OAuth provides secure authentication with scoped permissions and automatic token refresh.

note

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

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

Get your client's OAuth redirect URL​

Each MCP client requires specific OAuth redirect URLs for authentication callbacks. Common redirect URL patterns include:

  • Web-based clients: https://<domain>/oauth/callback or https://<domain>/api/mcp/auth_callback
  • Local development tools: http://localhost:<port>/oauth/callback

Check your client's documentation to find the exact redirect URLs required.

Create the Databricks OAuth application​

Have an account admin create a Databricks OAuth application. Retrieve its client ID, and if your client requires it, the client secret.

Create a Databricks OAuth application using the account console:

  1. In the Databricks account console, go to Settings > App Connections > Add connection.

  2. Configure the application settings:

    • Name: Enter a descriptive name for your OAuth application (for example, claude-mcp-client, mcp-inspector)
    • Redirect URLs: Add the redirect URLs required by your external client
    • Client type: For public clients (browser-based, mobile), uncheck Generate a client secret. For confidential clients (server-side), keep it checked.
    • Scopes: Configure the API scopes (see Configure OAuth scopes below)
    • Token expiration: Set appropriate token access and refresh times

Configure OAuth scopes​

OAuth scopes control which Databricks APIs your client can access. For most use cases, use the all-apis scope, which grants access to all Databricks APIs and is the simplest option.

For more granular control, you can specify MCP-specific scopes instead of all-apis:

MCP server type

Required scope(s)

MCP Genie spaces

mcp.genie

MCP Unity Catalog functions

mcp.functions

MCP Vector Search

mcp.vectorsearch

MCP Databricks SQL

mcp.sql, sql.warehouses, sql.statement-execution

MCP external functions

mcp.external

For more information about declaring REST API scopes and using them with agents, see Declare REST API scopes when logging the agent.

Configure network access (optional)​

If your Databricks workspace has IP access restrictions, add your client's outbound IP addresses to the workspace allowlist. Otherwise, the workspace blocks authentication requests from your client. See Manage IP access lists.

Configure your client​

After creating the OAuth application in Databricks, configure your specific MCP client with the OAuth credentials. Each client has its own configuration method. See the following platform-specific examples for detailed instructions for popular MCP clients.

OAuth examples​

The following examples show how to configure specific MCP clients with OAuth authentication. Follow the generic OAuth setup steps in the previous section first, then use these examples to configure your specific client.

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

MCP Inspector

Follow the OAuth authentication setup above with these Inspector-specific settings:

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

Configure MCP Inspector:

  1. Run the inspector: npx @modelcontextprotocol/inspector.
  2. Set Transport Type to Streamable HTTP.
  3. Enter your Databricks 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.

MCP Inspector Authentication Flow

Connect clients using personal access token (PAT) authentication​

Personal access tokens provide a simpler authentication method suitable for individual development, testing, and short-term access to Databricks MCP servers.

note

Personal access tokens are only supported for managed and external MCP servers. Custom MCP servers require OAuth authentication.

  1. Generate a personal access token in your Databricks workspace. See Authenticate with Databricks personal access tokens (legacy).

  2. Configure network access (optional).

    If your Databricks workspace has IP access restrictions, add your client's outbound IP addresses to the allowlist. Consult your client's documentation or your deployment environment's network configuration to obtain the required IP addresses.

  3. Configure your client.

    After generating the PAT, configure your MCP client to use it for authentication. Each client has its own configuration method. See the platform-specific examples below for detailed instructions for popular MCP clients.

PAT examples​

The following examples show how to configure specific MCP clients with personal access token authentication. Follow the PAT authentication setup above first, then use these examples to configure your specific client.

Cursor supports MCP through its settings configuration.

  1. Open your Cursor settings.

  2. Add the following configuration (adapt the URL for your chosen MCP server):

    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"
        }
      }
    }

  3. Replace <your-workspace-hostname> with your Databricks workspace hostname.

  4. Replace <YOUR_TOKEN> with your personal access token.

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.

Next steps​