Skip to main content
Last updated on

Connect Gemini

Use Gemini CLI with models, MCP tools, and skills through Unity Gateway. The Unity Gateway CLI (ug) handles workspace sign-in and configuration, or you can configure the connection manually.

Only the Gemini CLI is supported through Unity Gateway.

Before you begin​

You need your Databricks workspace URL and access to the models, MCP services, and skills you want to use. For manual setup, install a Gemini CLI version compatible with the current Unity Gateway integration and have a Databricks personal access token.

For manual configuration, replace <workspace-hostname> with your Databricks workspace hostname and <databricks-pat> with your token. Use full model names available in your workspace, and merge configuration entries into existing files, keeping unrelated settings.

If your admin has already configured your device, follow your organization's setup instructions.

Use the Unity Gateway CLI​

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

Bash
ug gemini

Select your workspace and sign in when prompted. The command opens Gemini CLI with a configured model, ready for your usual coding workflow.

To start with a different model, use ug gemini --model "<model-name>". To use a Gemini Model Provider Service configured by your admin, use ug gemini --provider "<catalog>.<schema>.<provider-name>".

Configure models manually​

Install a Gemini CLI version compatible with the current Unity Gateway integration:

Bash
npm install -g "@google/gemini-cli@<0.45.0"

Set these variables in your terminal:

Bash
export GEMINI_MODEL="system.ai.gemini-2-5-flash"
export GOOGLE_GEMINI_BASE_URL="https://<workspace-hostname>/ai-gateway/gemini"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"
export GEMINI_API_KEY="<databricks-pat>"

Merge the following into ~/.gemini/settings.json to select API-key authentication:

JSON
{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Then run gemini from the same terminal. See Gemini CLI's configuration documentation for its settings and environment variables.

Add MCP tools​

Use the Unity Gateway CLI​

Run:

Bash
ug mcp add --agents gemini

Select your services, then restart with ug gemini. Enter /mcp inside the agent to see connected servers.

Configure MCP services manually​

Merge this entry into ~/.gemini/settings.json:

JSON
{
  "mcpServers": {
    "dbsql": {
      "httpUrl": "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql",
      "headers": {
        "Authorization": "Bearer <databricks-pat>"
      }
    }
  }
}

For another service, change the server name and replace system.ai.dbsql with its three-part Unity Catalog name. Restart gemini after editing. See Gemini CLI's MCP documentation.

ug gemini uses a separate settings file at ~/.ucode/.gemini-home/.gemini/settings.json. Use that file for manual MCP entries when launching through ug.

Add skills​

Use the Unity Gateway CLI​

From your project directory, download published skills into the project:

Bash
ug skills add --path "$PWD"

Choose your skills, then restart Gemini CLI. It reads the project's .agents/skills/ directory. Enter /skills list to see available skills.

Configure skills manually​

For files you already have, place each complete skill folder in your project's .gemini/skills/. Project skills work with both gemini and ug gemini; ug uses a separate home directory for user settings and skills. See Gemini CLI's skills documentation.

To access the published skill registry through MCP, add a second server using the MCP example above, name it databricks-skill-registry, and set httpUrl to https://<workspace-hostname>/ai-gateway/skills/. Keep the trailing slash and bearer header. Ask the agent to use a skill by its full name.

Unity Gateway skills are in Beta. See Govern skills for enablement and permissions.

Troubleshooting​

A model request fails: Check the gateway URL, token expiration, model name, permissions, and the Gemini CLI version restriction above.

An MCP server is missing: Restart the agent. If you configured it with ug, launch it with ug gemini so it uses the same settings. For manual setup, check ~/.gemini/settings.json and the bearer token.

A downloaded skill is missing: Check that its complete folder contains SKILL.md in a supported directory. When launching through ug, use the project download command above. Re-run ug skills add with the same options to refresh downloaded skills.

For workspace sign-in or ug setup problems, run ug doctor.

Next steps​

On this page