Add tools and skills

Use the Unity Gateway CLI (ug) to add MCP servers and shared skills to your coding agent. MCP tools provide access to data and services; skills provide instructions for your team's tasks and workflows.

For manual setup, see your coding agent's guide under Supported coding agents.

Prerequisites

Install and configure ug. You need access to the MCP servers or skills you want to use, including any underlying data and services.

You need an installed, configured MCP-capable agent, including for skill downloads. MCP connections apply to all your configured agents that support MCP.

For skills, your admin must enable the Beta feature. See Govern skills.

After changing your setup, restart your agent with its usual ug command.

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.

Choose MCP servers

ug mcp add

Sign in if prompted, then choose servers in the picker. Type to filter, press Space to select, and Enter to confirm.

Existing connections are kept. In your agent, ask it to use a tool by describing the task.

Choose MCP servers by name

To add MCP servers by name, use their full Unity Catalog names (<catalog>.<schema>.<server-name>):

ug mcp add --names system.ai.github,system.ai.slack

To add every MCP server in a schema:

ug mcp add --location "<catalog>.<schema>"

Add other Azure Databricks MCP servers

For resources outside the MCP server picker, use a selector with --names:

Resource Selector
AI Search indexes in a schema (legacy) vector-search:<catalog>.<schema>
Unity Catalog functions in a schema (legacy) uc-functions:<catalog>.<schema>
Genie Agent (legacy) genie-space:<space-id>
MCP server hosted in a Azure Databricks app app:<app-name>

The AI Search, Unity Catalog functions, and Genie Agent selectors connect to legacy workspace MCP endpoints. For new integrations, see the recommended approaches.

For example, connect an existing Genie Agent:

ug mcp add --names "genie-space:<space-id>"

Replace <space-id> with the Genie space ID.

Check and remove connections

List the MCP servers configured by ug:

ug mcp list

To remove connections you added:

ug mcp remove

Select the servers to remove and press Enter. Each selected connection is removed from all agents where you added it. The MCP server itself remains available in the workspace.

Other MCP clients

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

For Claude Code, Codex, or Cursor, use your agent's guide. For Claude on the web or desktop, follow Claude connectors.

For the clients below, choose an MCP under Unity Gateway > MCPs and use this URL:

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

Replace the hostname and MCP name. For example, use system.ai.genie_one_mcp for Genie One or system.ai.dbsql for Databricks SQL. You need MCP permissions and provider sign-in.

ChatGPT

  1. Enable Developer Mode in ChatGPT. Availability depends on your account and workspace policy.
  2. Follow the linked ChatGPT instructions to add an MCP connection with your MCP URL and choose OAuth.
  3. Copy the exact OAuth redirect URL shown by ChatGPT. Have an account admin create a Azure Databricks OAuth client with that URL and the ai-gateway scope. See ChatGPT OAuth redirect URLs for callback details.
  4. Enter the client ID and secret, if applicable, in ChatGPT. Save the connection and complete sign-in.
  5. Select the MCP connection in a conversation and ask it to use a read-only tool.

If IP access lists are enabled, allow ChatGPT's outbound IPs.

Windsurf

Use the manual OAuth configuration for Cursor, saving the JSON in ~/.codeium/windsurf/mcp_config.json. This uses mcp-remote with your registered OAuth client ID.

Restart Windsurf, complete browser sign-in, and ask the agent to call a read-only tool. See Windsurf MCP configuration.

Replit

For local testing with a personal access token:

  1. In your Replit workspace, click Add MCP Server and enter the MCP URL.
  2. Add the custom header Authorization with value Bearer <databricks-pat>.
  3. Save and ask the agent to call a read-only tool.

Keep the token out of source control. For current authentication options, see Replit MCP documentation.

Confirm that the client makes a tool call and returns its result. For system.ai.dbsql, try SELECT 1 AS result. If the connection fails, see MCP authentication and networking.

Add skills

You can use skills in two ways:

  • Download skills: Your agent discovers and uses local skill files through its native skill workflow.
  • Use skills through MCP: Your agent retrieves instructions from the published skill registry when it uses a skill, without local files to manage.

Download skills

ug skills add

Select the skills to download in the picker.

ug downloads each complete skill folder, including SKILL.md and supporting files, into both ~/.claude/skills/ and ~/.agents/skills/. Ask your agent to use the skill by name. See your agent's guide for its skill commands.

To download specific skills, use their full Unity Catalog names:

ug skills add --names "<catalog>.<schema>.<skill-name>"

To download all skills in a schema:

ug skills add --location "<catalog>.<schema>"

Both options accept comma-separated names. Use --names or --location in a command, not both. Re-run the same command to fetch updates; ug prompts before overwriting existing skill folders.

Downloading also enables the skill registry's discovery and loading tools, without changing schemas already connected through MCP.

Download skills into a project

From your project directory, run:

ug skills add --path "$PWD"

Choose your skills. ug writes them under the project's .claude/skills/ and .agents/skills/ directories. You can also combine --path with --names or --location.

--path must point to an existing, absolute project directory. Use project downloads with ug gemini, which uses a separate home directory for agent settings.

Connect to published skills through MCP

To choose schemas whose skills your agent can use through MCP:

ug skills add --via mcp

Select the schemas in the picker. To specify a schema directly:

ug skills add --location "<catalog>.<schema>" --via mcp

ug adds these schemas to the skill registry connection, keeping any already connected. You cannot combine --via mcp with --path or --names.

In your agent, ask it to use a published skill:

Use <catalog>.<schema>.<skill-name> to review this query.

You can also ask the agent to list skills in a schema. Skills loaded through MCP might not appear in the agent's native skill menu.

List skills

ug skills list

Remove skills

To select downloaded skills for removal:

ug skills remove

To remove a particular skill from your current project:

ug skills remove --names "<catalog>.<schema>.<skill-name>" --path "$PWD"

Use --location "<catalog>.<schema>" instead of --names to remove all downloads from a schema. Without --path, removal includes copies downloaded by ug across your user and project directories. Published skills remain in Unity Catalog.

To remove a schema from the live MCP connection:

ug skills remove --location "<catalog>.<schema>" --via mcp

Omit --location to choose schemas in a picker. Removing a schema leaves downloaded files and the registry's discovery tools in place.

Next steps

  • Last updated on