MCP authentication and networking
For step-by-step setup, use your coding agent's guide or the Python quickstart. Use this page to check shared authentication requirements and network access.
Sign in to Databricks
Use your Databricks user account for interactive work, or a Databricks service principal for an agent that runs unattended. Follow the setup for your agent:
Use case | Recommended setup |
|---|---|
Coding agents | Use the Unity Gateway CLI. It handles sign-in and refreshes credentials. |
Local Python development | |
Other interactive MCP clients | Configure OAuth with a registered client ID. |
Unattended agents | Use a Databricks service principal with OAuth machine-to-machine (M2M). For agents on Databricks Apps, see Agent authentication. |
The user or Databricks service principal needs permission to call the MCP. If a tool asks you to sign in to an external provider, follow External services setup.
For local testing, Databricks-provided and registered MCPs, and legacy workspace endpoints, accept a personal access token in the Authorization: Bearer <token> header. Keep tokens out of source control. Servers hosted on Databricks Apps require OAuth and do not accept personal access tokens.
Configure a custom OAuth client
Use this when your client requires its own OAuth app. The Claude Code and Codex guides include their client-specific settings.
-
Get the exact redirect URL from your client, including its host, port, and path.
-
Have an account admin open Settings in the account console, select App connections, and click Add connection.
-
Enter a name, add the redirect URL, and select the scopes for your server:
Server
URL
Scope
Provided or registered MCP
https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>ai-gatewayServer on Databricks Apps
https://<app-url>/mcpInclude the app's user authorization scopes. You also need CAN USE on the app.
Workspace MCP endpoint (legacy)
The URL on the server's page
Use the scopes listed for that server.
-
Choose whether to generate a client secret:
- Desktop or CLI client (public client): Clear Generate a client secret.
- Server-side client that securely stores secrets (confidential client): Leave Generate a client secret selected.
-
Save the connection and copy the Client ID. If you generated a client secret, copy that value too.
-
Enter the server URL and client credentials in your MCP client. Use Streamable HTTP, request the server's scope and
offline_accessfor refresh tokens, and sign in.
See Create an OAuth app for UI and CLI options. Changes can take up to 30 minutes to take effect. Databricks MCP endpoints don't support dynamic client registration, so use a client that accepts a preconfigured client ID.
Network access
Check access from the client to the workspace and from the workspace to the external server.
Client to workspace
MCP requests must be allowed by your workspace's inbound network controls. If workspace IP access lists are enabled, ask an admin to allow the public IP addresses where the requests originate:
Where the MCP client runs | Addresses to allow |
|---|---|
On your computer, such as Claude Code, Codex CLI, or Cursor | Your network's public outbound IP. If traffic goes through a corporate VPN or proxy, use that network's outbound IP. Your network administrator can provide it. |
In a hosted service, such as a Claude connector or ChatGPT | The provider's published outbound IP ranges. See Claude's outbound IPs and ChatGPT's outbound IPs. |
For hosted clients, browser sign-in comes from your network, while MCP calls come from the provider's servers. Both must be allowed. For example, signing in successfully from your corporate VPN does not mean ChatGPT can reach your MCP.
If your organization also uses context-based ingress controls, the requests must satisfy those policies too. Account IP access lists apply to account console and account API access, such as an admin creating an OAuth app.
Workspace to external MCP server
Calls to external MCP providers through Unity Gateway use the workspace's serverless compute plane. This applies to registered external servers and Databricks-provided MCPs for external services.
If your serverless network policy uses Restricted access, add the server's fully qualified domain name (FQDN) to Allowed domains. Start with the host on the MCP's Unity Catalog connection. Check system.access.outbound_network for additional blocked destinations. See Manage network policies and Outbound network logs.
- A Unity Catalog connection does not automatically allow its destination.
- Full access is the serverless network policy's mode for allowing outbound internet connections by default. Explicitly blocked domains remain denied. For example, a policy that blocks
mcp.example.comprevents calls to that MCP server. Ask an admin to review the policy's blocked destinations. - To test MCP traffic in dry-run mode, select All products. The Databricks SQL and AI model serving options do not put MCP traffic in dry-run.
Private connectivity
To reach an MCP server in your cloud network, choose how Databricks serverless compute connects to it:
- Private endpoint: Use Private Link to keep traffic on a private connection. An account admin adds a private endpoint rule for the server's domain to a network connectivity configuration (NCC) attached to your workspace. Your cloud administrator approves the endpoint connection. See Configure private connectivity.
- Public endpoint with a firewall: Configure the server's firewall to allow Databricks serverless outbound IPs for your workspace's cloud and region. These IPs are shared across Databricks customers, so keep authentication enabled on the server. See Find the outbound IPs and configure your firewall.
Domains added to private endpoint rules are automatically allowed by network policies, so you don't need to add them separately to Allowed domains. For a public endpoint, follow the network policy setup above.