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	`vector-search:<catalog>.<schema>`
Unity Catalog functions in a schema	`uc-functions:<catalog>.<schema>`
Genie Agent	`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 workspace MCP endpoints governed by resource permissions. Calls bypass Unity Gateway tracing, MCP grants, policies, and guardrails. A workspace administrator must enable Managed MCP Servers.

Use the AI Search and functions selectors when your coding agent needs MCP tools for those resources. These endpoints and the Genie Agent MCP are in Public Preview. For SQL queries, use system.ai.dbsql through Unity Gateway.

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 manual OAuth setup, have an account admin register a custom OAuth application with the client's exact redirect URLs and the ai-gateway scope. Desktop and CLI clients use a public client without a client secret. Server-side clients that can securely store a secret can use a confidential client. Azure Databricks MCP endpoints don't support dynamic client registration, so the client must accept a preconfigured client ID. Use Streamable HTTP and request offline_access for refresh tokens.

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>?o=<workspace-id>

Replace the hostname, workspace ID, and MCP name. For example, use system.ai.genie_one_mcp for Genie One or system.ai.dbsql for Databricks SQL. You need permission to call the MCP, and for per-user MCPs, a provider sign-in.

ChatGPT

Enable Developer Mode in ChatGPT. Availability depends on your account and workspace policy.
Follow the linked ChatGPT instructions to add an MCP connection with your MCP URL and choose OAuth.
For the OAuth client ID, enter the default ChatGPT client ID, https://chatgpt.com/oauth/client.json. Save the connection and complete sign-in.

To use your own OAuth app instead, 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, then enter its client ID and secret, if applicable. See ChatGPT OAuth redirect URLs.
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:

In your Replit workspace, click Add MCP Server and enter the MCP URL.
Add the custom header Authorization with value Bearer <databricks-pat>.
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.

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

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

Feedback

Was this page helpful?

Last updated on 2026-10-26