Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Use Claude Code or the Claude desktop app with models, MCP tools, and skills through Unity Gateway. For Claude Code, use the Unity Gateway CLI (ug) or configure the connection manually. For the desktop app, configure the connection in the app's settings.
Before you begin
You need your Azure Databricks workspace URL and access to the models you want to use. For desktop setup, install the latest Claude desktop app and ask your account admin for an OAuth client ID, as described below.
If your admin has already configured your device, follow your organization's sign-in and launch instructions.
Claude Code
Use the Unity Gateway CLI (recommended)
Install ug, then run this command from your project directory:
ug claude
Follow the prompts to select your workspace and sign in. ug configures the connection and opens Claude Code in your terminal. Start working with the same prompts and commands you already use. To change models, enter /model.
To add MCP tools or skills, run these commands in your terminal, then restart Claude Code:
ug mcp add
ug skills add
Each command lets you select what to add. See Add tools and skills for details.
Configure Claude Code manually
Merge the following settings into ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_MODEL": "<model-api-name>",
"ANTHROPIC_BASE_URL": "https://<workspace-hostname>/ai-gateway/anthropic",
"ANTHROPIC_AUTH_TOKEN": "<databricks-personal-access-token>",
"ANTHROPIC_CUSTOM_HEADERS": "x-databricks-use-coding-agent-mode: true",
"CLAUDE_CODE_USE_GATEWAY": "1",
"ENABLE_PROMPT_CACHING_1H": "1",
"ENABLE_TOOL_SEARCH": "true"
}
}
Replace <workspace-hostname> with your workspace hostname, without https://. Set <model-api-name> to the full Unity Catalog name of a Claude model API you can access, and supply your Azure Databricks personal access token.
Run claude from your project directory. For other settings, see Claude Code settings.
Add MCP tools manually
Find the MCP service's three-part name under Unity Gateway > MCPs in your workspace, then register it with Claude Code:
claude mcp add --transport http --scope user \
--client-id claude-code --callback-port 3118 \
databricks-tools \
"https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>"
Replace the hostname and service name. Open Claude Code, enter /mcp, and authenticate the server with your Azure Databricks account. Repeat with a different server name for each service you want to add.
Connect skills manually
To expose published Unity Gateway skills as tools, register the skill registry as an HTTP MCP server:
claude mcp add --transport http --scope user \
--header "Authorization: Bearer <databricks-personal-access-token>" \
databricks-skill-registry \
"https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>"
Replace the placeholders with your workspace, token, and skill schema. Keep the trailing slash before ?schema. To include multiple schemas, repeat the parameter: ?schema=main.default&schema=ml.prod.
Restart Claude Code and check the connection with /mcp. Ask Claude to use a skill by its full name, such as Use <catalog>.<schema>.<skill-name> to review this query. This connection exposes skills as MCP tools; ug skills add downloads skills for native discovery instead.
Claude desktop app
1. Get an OAuth client ID
Ask your account admin to create an OAuth application connection. In the Azure Databricks account console, open Settings > App connections > Add connection and use:
| Setting | Value |
|---|---|
| Identity type | Standard application |
| Application name | claude-desktop |
| Generate a client secret | Unchecked (public client) |
| Redirect URL | http://127.0.0.1:53180/callback |
| Access scopes | ai-gateway |
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 the desktop app'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 | https://<workspace-hostname>/ai-gateway/anthropic |
| Client ID | Your OAuth client ID |
| Issuer URL | https://<workspace-hostname>/oidc |
| Bearer token | Access token |
| Scopes | ai-gateway |
Append offline_access |
Enabled |
| Redirect port | 53180 |
Replace <workspace-hostname> with your Azure Databricks workspace hostname. Leave other settings at their defaults. See Anthropic's gateway configuration for field details.
Click Test connection and sign in to Azure 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 service 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 | ["https://<workspace-hostname>/oidc"] |
| Scope | ai-gateway |
Request offline_access |
Enabled |
| Callback host | 127.0.0.1 |
For an MCP service, 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>
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, click 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.
Troubleshooting
Claude Code does not connect: Run ug doctor if you use ug. For manual setup, check your workspace hostname, token, model name, and model permissions.
Desktop sign-in fails: Check the client ID, /oidc issuer, and ai-gateway scope. The registered redirect URL must match the connector's host and port: 53180 for models and MCP services, or 53280 for skills in this guide. OAuth application changes can take up to 30 minutes to take effect.
A desktop model is missing: Check your model permissions. Under Connection > Models > Model list, add the model's full Unity Catalog name. An explicit list replaces automatic discovery, so include all models you want to use. Apply the changes and restart.
An MCP or skill connector fails: Check its URL and permissions. The Authorization server field must contain the JSON array shown above. Click Sign in & test to inspect the error.