Skip to main content
Last updated on

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​

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

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

To add every MCP server in a schema:

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

Add other 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 Databricks app

app:<app-name>

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

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

Bash
ug mcp list

To remove connections you added:

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

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

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

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

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​

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

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

To download all skills in a schema:

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

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

Bash
ug skills add --via mcp

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

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

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

Bash
ug skills list

Remove skills​

To select downloaded skills for removal:

Bash
ug skills remove

To remove a particular skill from your current project:

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

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

On this page