Connect Claude desktop
Use Claude desktop in Code or Cowork with models, MCP tools, and skills through Unity Gateway. Claude desktop also supports Anthropic subscription relay.
Prerequisites
You need your Databricks workspace URL, access to the models and tools you want to use, and the latest version of Claude desktop.
On Windows, open Claude desktop at least one time before running ug configure so the app initializes its local data.
If you plan to use an Anthropic subscription relay, install the Claude Code CLI.
Connect with the Unity Gateway CLI (Recommended)
Install ug, then run this command in an interactive terminal:
ug configure --agents claude
Select your workspace and sign in. This command configures both Claude Code and the installed Claude desktop work agent for the same workspace. ug creates and selects a Claude desktop profile with the models, MCP servers, skills, and credential refresh settings available through your workspace.
Open or restart Claude desktop, then start a conversation in Code or Cowork. Use the model picker to change models.
Deploy with MDM
To deploy Claude desktop across your organization with mobile device management (MDM), see Anthropic's MDM deployment guide.
Supported features and limitations
This setup uses Claude desktop's third-party inference mode.
Feature | Support |
|---|---|
Code and Cowork tabs | Supported with model inference through Unity Gateway. |
MCP servers, tools, and skills | Supports the MCP servers, tools, and shared skills from Unity Gateway. |
Scheduled tasks | Supported. Scheduled tasks work the same way as in standard Claude desktop. |
Anthropic subscription relay | Supported. Install the Claude Code CLI before configuring the relay. |
Smart Routing | Not supported. |
Manual setup
Use this setup only if you can't use ug. It requires an OAuth client ID and a manually configured Claude desktop profile.
1. Get an OAuth client ID
Use the default Claude client ID, https://claude.ai/oauth/mcp-oauth-client-metadata. An account admin doesn't need to create an OAuth app. See Default OAuth client IDs.
Use your own OAuth app
Ask your account admin to create an OAuth application connection. In the Databricks account console, open Settings > App connections > Add connection and use:
Setting | Value |
|---|---|
Identity type | Standard application |
Application name |
|
Generate a client secret | Unchecked (public client) |
Redirect URL |
|
Access scopes |
|
Save the connection and copy the Client ID. If you plan to connect skills, also register http://127.0.0.1:53280/callback.
2. Connect to Unity Gateway
From Claude desktop's sign-in screen, select Help > Troubleshooting > Enable Developer Mode, then Developer > Configure Third-Party Inference.
On the Connection page, select Gateway and enter:
Setting | Value |
|---|---|
Credential kind | Interactive sign-in |
Gateway base URL |
|
Client ID | Your OAuth client ID |
Issuer URL |
|
Bearer token | Access token |
Scopes |
|
Append | Enabled |
Redirect port |
|
Replace <workspace-hostname> with your Databricks workspace hostname. Leave other settings at their defaults. See Anthropic's gateway configuration for field details.
Select Test connection and sign in to Databricks. Select Apply Changes, then Save & Restart. On the sign-in screen, choose the third-party configuration and start a conversation in Code or Cowork.
3. Add MCP tools and skills
Open Developer > Configure Third-Party Inference > Connectors. Under Managed MCP servers, add an entry for each MCP or skill registry you want to use.
Use these settings for both types of connector:
Setting | Value |
|---|---|
Transport | Streamable HTTP |
OAuth | Bring your own client |
Client ID | Your OAuth client ID |
Client secret | Leave blank |
Authorization server |
|
Scope |
|
Request | Enabled |
Callback host |
|
For an MCP, find its three-part name under Unity Gateway > MCPs in your workspace. Give the connector a descriptive name, set Callback port to 53180, and use this URL:
https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>?o=<workspace-id>
For skills, name the connector databricks-skill-registry, set Callback port to 53280, and use:
https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>
Keep the trailing slash before ?schema. To include multiple schemas, repeat the parameter: ?schema=main.default&schema=ml.prod. These skills are exposed to Claude as tools through the connector.
For each connector, select Sign in & test and complete sign-in. Select Apply Changes, then Save & Restart. Ask Claude to use a connected tool or a skill by its full name. See Add tools and skills for access requirements and more options.
Connect MCP tools with your Claude account
For system.ai.dbsql, first enable the Unity Gateway beta.
Use a custom connector to add Databricks MCP tools to Claude on the web or desktop using your Claude account.
-
In Claude, open Settings > Connectors > Add custom connector.
-
Enter the MCP URL:
Texthttps://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id> -
For the OAuth client ID, enter the default Claude client ID,
https://claude.ai/oauth/mcp-oauth-client-metadata. Select Add and complete sign-in. -
In a conversation, enable the connector and ask Claude to call one of its tools. For
system.ai.dbsql, trySELECT 1 AS result.
Use your own OAuth app
Have an account admin create an OAuth client. For an MCP, select the ai-gateway scope and register both redirect URLs:
https://claude.ai/api/mcp/auth_callbackhttps://claude.com/api/mcp/auth_callback
In step 3, enter that client ID and, for a confidential client, its secret.
If your workspace restricts incoming IPs, allow Claude's outbound IPs. See MCP authentication for permissions, provider login, and troubleshooting.
Use a personal access token for local testing
This option requires Node.js with npx and a personal access token. It works for Databricks-provided and registered MCPs, and workspace MCP endpoints. Servers hosted on Databricks Apps require OAuth.
Merge this entry into claude_desktop_config.json at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:
{
"mcpServers": {
"databricks-tools": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>",
"--header",
"Authorization: Bearer <databricks-pat>"
]
}
}
}
Replace the placeholders, keep tokens out of source control, and restart Claude desktop. Ask Claude to call a read-only tool to verify the connection.
Troubleshooting
-
Sign-in fails: For manual setup, check the client ID,
/oidcissuer, andai-gatewayscope. The registered redirect URL must match the connector's host and port:53180for models and MCPs, or53280for skills in this guide. OAuth application changes can take up to 30 minutes to take effect. -
A model is missing: Check your model permissions and rerun
ug configure --agents claudeto refresh the desktop model list. For manual setup, add the model's full Unity Catalog name under Connection > Models > Model list. An explicit list replaces automatic discovery, so include the models you want to use. Apply the changes and restart. -
An MCP or skill connector fails: Check its URL and permissions. For manual setup, the Authorization server field must contain the JSON array shown above. Select Sign in & test to inspect the error.
-
Workspace sign-in works, but a tool asks you to log in: Open the login link returned by the MCP, sign in to the external provider, then retry the call. Workspace and provider sign-in are separate steps.