Skip to main content
Last updated on

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.

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

Prerequisites​

You need your 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.

Install ug, then run this command from your project directory:

Bash
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:

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 Databricks personal access token.

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

Auto mode​

Auto mode reduces routine permission prompts by checking proposed tool calls with a safety classifier.

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

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:

Bash
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:

JSON
{
  "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​

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:

    Bash
    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:

Bash
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 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:

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

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

Bash
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​

On this page