Connect Claude Code

Use Claude Code with models, MCP tools, and skills through Unity Gateway. Use the Unity Gateway CLI (ug) to configure access, or configure the connection manually.

Use Claude Code with supported open-source models through Unity Gateway to help reduce coding agent costs.

To connect tools to an existing Claude Code setup, go to Add MCP tools.

Prerequisites

You need your Azure Databricks workspace URL, access to the models you want to use, and the latest Claude Code.

If your admin has already configured your device, follow your organization's sign-in and launch instructions.

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.

Continue to Add MCP tools to connect data and services. To download shared skills, run ug skills add and select the skills you want. See Add tools and skills for more options.

Bring your own Claude subscription

To run Claude Code on your own Claude Pro, Max, Enterprise, or Team subscription through Unity Gateway, ask your admin for a Claude Max/Enterprise model provider service. See Claude Max and Anthropic Enterprise support for requirements, admin setup, how it works, and limitations.

Pass the model provider service's fully qualified name (<catalog>.<schema>.<name>) to --provider and the workspace URL to --workspace:

ug claude --provider main.default.claude_subscription --workspace https://<workspace>.databricks.com

ug configures Claude Code to send the Databricks-Model-Provider-Service header and points Claude Code at a local refresh proxy rather than directly at the Unity Gateway endpoint. The proxy forwards each request to https://<workspace-url>/ai-gateway/anthropic and adds the X-Databricks-AI-Gateway-Token header. Because the service stores no credential, ug forwards your Anthropic OAuth token instead of an API key.

If Claude Code prompts you to authenticate, select Option 1 - Claude account with subscription and log in with your Anthropic account. If you run into issues, log out with claude /logout and log in again.

Note

--provider for a Claude Max/Enterprise model provider service is only supported with ug claude.

Configure a Claude subscription manually

Use the manual setup only if you cannot use ug.

Get a Azure Databricks token. The X-Databricks-AI-Gateway-Token header carries a Azure Databricks token that authenticates the request to Unity Gateway. Unity Gateway attributes access control and usage logs to the identity tied to this token, so use a token that belongs to the querying user. Select one of the following:
- OAuth user-to-machine (U2M) with the Databricks CLI (recommended). Log in once with the CLI, then mint a short-lived OAuth token:
```
databricks auth login --host https://<workspace-url>
databricks auth token --host https://<workspace-url> | jq -r .access_token
```
  See Authorize user access to Azure Databricks with OAuth and Authentication for the Databricks CLI. A U2M OAuth token expires in about 1 hour, so for interactive use you must refresh it and re-export the variable when it expires. To automate token refresh, use ug, which runs a local proxy that refreshes the OAuth token for you on every request.
- Personal access token (PAT), as a backup. If you cannot use OAuth, create a PAT and use it as <databricks-token>. A PAT does not expire on the 1-hour OAuth cadence, but it is a long-lived credential tied to your identity. See Authenticate with Azure Databricks personal access tokens (legacy).
Add the following to your shell configuration file (~/.zshrc or ~/.bashrc):
```
export ANTHROPIC_BASE_URL="https://<workspace-url>/ai-gateway/anthropic"
export ANTHROPIC_CUSTOM_HEADERS="X-Databricks-AI-Gateway-Token: Bearer <databricks-token>
Databricks-Model-Provider-Service: <catalog>.<schema>.<name>"
```
- Replace <workspace-url> with your workspace URL.
- Replace <databricks-token> with the Azure Databricks token from the previous step.
- Replace <catalog>.<schema>.<name> with the fully qualified name of your model provider service.
Start Claude Code:
```
claude
```
If you are not already logged in, Claude Code prompts you to authenticate. Select Option 1 - Claude account with subscription and log in with your Anthropic account. If you run into issues, log out with claude /logout and log in again.

Your Claude Code requests now route through Unity Gateway. Requests are billed against your Anthropic subscription, and you get centralized access, routing, and usage governance.

Run on Azure Databricks compute

To run Claude Code on serverless compute or a dedicated cluster without installing ug, connect with the SSH tunnel and run claude. The agent is preconfigured for Unity Gateway. See Run coding agents in an SSH session.

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 model service you can access that supports the Anthropic Messages API. This can be a Claude model or a compatible open-source model. Supply your Azure Databricks personal access token.

Run claude from your project directory. For other settings, see Claude Code settings.

Auto mode

Auto mode is a Claude Code permission mode that reduces routine permission prompts. A safety classifier reviews proposed tool actions, such as shell commands or file edits, that would otherwise require your approval and decides whether they can proceed.

Anthropic models through Unity Gateway use Anthropic's native auto-mode checks. For non-Anthropic foundation models hosted by Azure Databricks that support function calling, Unity Gateway supplies the classifier. For the maintained model list and per-model capabilities, see Models available through Databricks.

Auto mode and service policies provide complementary checks:

The Auto mode safety classifier decides whether a proposed tool action can proceed based on the conversation and Auto mode rules.
Service policies apply your organization's governance rules to requests and responses on the model, model provider, or MCP services they are attached to, including MCP tool calls and results. Some built-in service policies also use a model as a safety classifier, but their decisions concern the governed service interaction.

Auto mode approval does not override an enforcing service policy. For example, a policy on an MCP service can require human approval for a destructive tool call even when Auto mode permits the action.

Claude Code evaluates explicit permissions.deny rules and content-scoped permissions.ask rules before consulting the classifier. A matching deny rule blocks the action, and a matching ask rule requires a permission prompt. Auto mode can also block actions based on the conversation and classifier rules, or when a check cannot produce a valid verdict.

After configuring your connection with ug, start Claude Code in auto mode:

ug claude -- --permission-mode auto

With a manual connection, run claude --permission-mode auto. For ug argument forwarding, see ug CLI reference.

Configure trusted infrastructure

Describe your organization's trusted repositories, domains, and services in autoMode.environment. These entries help the classifier distinguish expected access to your infrastructure from actions it should block. Merge an autoMode block into your user settings at ~/.claude/settings.json, for example:

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/example-org and its repositories",
      "Trusted internal services: builds.internal.example.com"
    ]
  }
}

Replace the example entries with your organization's infrastructure. Entries are natural-language descriptions. Keep "$defaults" to preserve the built-in environment entries when adding your own.

The classifier reads autoMode from user settings, managed settings, or inline --settings configuration. It does not read this block from project .claude/settings.json or .claude/settings.local.json. Admins can distribute shared configuration through managed settings.

For rule customization, managed settings, and reviewing blocked actions, see Configure auto mode.

Track classifier usage

The Unity Gateway checks send proposed tool arguments and conversation context to a separate classifier model. Classifier requests incur additional model charges and can add latency.

Classifier requests appear in system.ai_gateway.usage with invocation_metadata.source set to SAFEGUARD_CLASSIFIER. Use this value to distinguish safety-check requests and their token usage and latency from your coding model's requests. See Usage tracking for access requirements and the usage-table schema.

Add MCP tools

system.ai.dbsql, system.ai.sandbox, and system.ai.web_search are in Beta. To use them, an account admin must enable the Enhanced Unity Gateway preview from the account console Previews page. Unity Gateway itself is generally available. See Manage account previews.

Open Unity Gateway > MCPs in your workspace. Choose a built-in MCP or register your external MCP server.
Copy the MCP's full name, such as system.ai.github or <catalog>.<schema>.<service>.
Confirm that you have access to the MCP.
After installing ug, add the MCP to Claude Code:
```
ug mcp add --agents claude --names <catalog>.<schema>.<service>
```
Replace the placeholder with the name you copied. For example, use --names system.ai.github for GitHub. To choose services interactively, omit --names.

On first setup, follow the prompts to select your workspace, sign in, and choose a model. ug configures both model and MCP access and refreshes credentials. Restart Claude Code with ug claude, then test a tool.

Add MCP tools manually

Use the default Claude Code client ID below, or configure your own OAuth app. To add an MCP with the default client ID, run:

claude mcp add --transport http --scope user \
  --client-id https://claude.ai/oauth/claude-code-client-metadata --callback-port 3118 \
  databricks-tools \
  "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>?o=<workspace-id>"

Replace the hostname, workspace ID, and MCP name. Open Claude Code, enter /mcp, and sign in to the server with your Azure Databricks account. Repeat with a different server name for each MCP you want to add, then test a tool.

Use your own OAuth app

Have an account admin open Settings > App connections > Add connection in the account console.
Enter a name such as claude-code-mcp, clear Generate a client secret for a public client, set the redirect URL to http://localhost:8080/callback, and select the ai-gateway scope. Save and copy the Client ID. See Create an OAuth app.

claude mcp add --transport http --scope user \
  --client-id <client-id> --callback-port 8080 \
  databricks-tools \
  "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>"

Open Claude Code, enter /mcp, and sign in. If your organization requires a confidential client, add --client-secret to the command and enter the secret when prompted.

Test an MCP tool

In Claude Code, enter /mcp and check that the server is connected.
Ask Claude to list that server's tools, then request a read operation. For GitHub, ask it to find an issue in a repository you can access. For a custom server, use a tool and inputs you tested during registration.
If a tool call prompts you to sign in, open the login link returned by the MCP, complete provider consent, then retry the call.
Check that Claude makes a tool call and returns its result. A text answer alone doesn't verify the connection.

To use Azure Databricks data, connect system.ai.genie_one_mcp for business questions or system.ai.dbsql for SQL. For example, ask the SQL MCP to run SELECT 1 AS result.

For permissions, policies, and usage, see Govern an MCP.

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.

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.
Claude Code OAuth reports a redirect mismatch or the connection times out: For a custom OAuth app, match its redirect URL to the callback host and port, and check network access. OAuth app changes can take up to 30 minutes to take effect.

Next steps

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Τελευταία ενημέρωση στις 2026-11-11