Connect Claude Code

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.

To connect tools to an existing Claude Code setup, go to Add MCP tools. For Claude on the web or a desktop session using your Claude account, use Claude connectors.

Prerequisites

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.

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.

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

To use system.ai.dbsql, system.ai.sandbox, or system.ai.web_search, an account admin must enable the Unity Gateway beta from the account console Previews page. See Manage account previews.

1. Open Unity Gateway > MCPs in your workspace. Choose a built-in MCP or register your external MCP server.

2. Copy the MCP's full name, such as system.ai.github or <catalog>.<schema>.<service>.

3. Confirm that you have access to the MCP.

4. 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 built-in OAuth client below, or configure your own OAuth app. To add an MCP with the built-in client, run:

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 MCP name. This uses the built-in claude-code OAuth client. 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

1. Have an account admin open Settings > App connections > Add connection in the account console.

2. 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.

3. Register the MCP using that client ID and the matching callback port:

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

4. 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

1. In Claude Code, enter /mcp and check that the server is connected.
2. 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.
3. If a tool call prompts you to sign in, open the login link returned by the MCP, complete provider consent, then retry the call.
4. 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.

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 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, 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.

Claude connectors

For system.ai.dbsql, first enable the Unity Gateway beta.

Use a custom connector to add Azure Databricks MCP tools to Claude on the web or desktop using your Claude account.

1. 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_callback
   • https://claude.com/api/mcp/auth_callback

2. In Claude, open Settings > Connectors > Add custom connector.

3. Enter the MCP URL:

   https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>
   

4. Enter the OAuth client ID and, for a confidential client, its secret. Click Add and complete sign-in.

5. In a conversation, enable the connector and ask Claude to call one of its tools. For system.ai.dbsql, try SELECT 1 AS result.

If your workspace restricts incoming IPs, allow Claude's outbound IPs. See MCP authentication and networking for permissions, provider login, and troubleshooting.

Use a personal access token in Claude desktop for local testing

This option requires Node.js with npx and a personal access token. It works for Databricks-provided and registered MCPs, and legacy workspace 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>",
        "--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

• 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 MCPs, 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.

• 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.

• 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

• ug CLI reference
• Add tools and skills