Skip to main content
Last updated on

Connect Cursor

Use Cursor with models, MCP tools, and skills through Unity Gateway. Configure model access in Cursor IDE's settings. Use the Unity Gateway CLI (ug) to add MCP tools and skills, or configure them manually.

Before you begin​

You need your Databricks workspace URL and access to the models, MCP services, and skills you want to use. Install Cursor. To use the ug MCP integration, also install Cursor Agent, which provides the cursor-agent command.

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

Cursor IDE​

1. Configure the base URL and API key​

Open Cursor > Settings > Cursor Settings > Models > API Keys.

Enable Override OpenAI Base URL and enter:

Text
https://<workspace-hostname>/ai-gateway/cursor/v1

Replace <workspace-hostname> with your Databricks workspace hostname. Paste your Databricks personal access token into OpenAI API Key.

2. Add custom models​

Click + Add Custom Model in Cursor Settings. Enter the full name of a foundation model available in your workspace, then enable its toggle. Repeat for each model you want to use.

Example model names:

Provider

Model name

OpenAI

system.ai.gpt-5-5

Gemini

system.ai.gemini-2-5-flash

Claude

system.ai.claude-opus-4-6

Provider

Model name

OpenAI

system.ai.gpt-5-5

Gemini

system.ai.gemini-2-5-flash

Claude

system.ai.claude-opus-4-6

Available models depend on your workspace and permissions. This connection uses Databricks-provided models.

3. Test the connection​

Open Ask mode with Cmd+L on macOS or Ctrl+L on Windows/Linux. Select your model and send a message. Requests using that custom model route through Unity Gateway.

Cursor Agent in the terminal​

Use the Unity Gateway CLI​

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

Bash
ug cursor

This opens Cursor Agent in your terminal. Start working with the same prompts and commands you already use. Models run through your Cursor account; ug does not configure model routing for Cursor Agent.

Add MCP tools​

Use the Unity Gateway CLI​

With Cursor Agent installed, run:

Bash
ug mcp add --agents cursor

Select the services you want to add. ug registers them in ~/.cursor/mcp.json, which the IDE and terminal agent use. Restart Cursor or your agent session, then ask it to use a connected tool.

Configure MCP services manually​

Merge this entry into ~/.cursor/mcp.json:

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

Replace the hostname and token. For another service, use a unique server name and replace system.ai.dbsql with its three-part Unity Catalog name. Keep unrelated server entries.

Restart Cursor and ask the agent to use a tool. For OAuth configuration, see Cursor's MCP documentation.

Add skills​

Use the Unity Gateway CLI​

Run the picker to download published skills:

Bash
ug skills add

Cursor reads the downloaded skills from ~/.agents/skills/. Start a new session to use them. Downloads are local snapshots; re-run the command to get updates.

Connect the skill registry manually​

To load published skills through MCP, merge this entry into ~/.cursor/mcp.json:

JSON
{
  "mcpServers": {
    "databricks-skill-registry": {
      "url": "https://<workspace-hostname>/ai-gateway/skills/",
      "headers": {
        "Authorization": "Bearer <databricks-pat>"
      }
    }
  }
}

Replace the hostname and token, keeping the trailing slash in the URL. Restart Cursor and ask it to use a skill, such as Use <catalog>.<schema>.<skill-name> to review this query.

The registry exposes skills through MCP. To install skill files you already have, place the complete folder, including SKILL.md and bundled files, in ~/.agents/skills/ or your project's .cursor/skills/. See Cursor's skills documentation.

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

Troubleshooting​

ug cursor cannot find Cursor Agent: Install Cursor Agent and check that cursor-agent is available in your terminal.

A custom model fails in the IDE: Check the gateway URL, token expiration, model name, and your model permissions. Select the custom model in the conversation.

An MCP or skill connection fails: Check the URL, service permissions, and connector error. For manual connections, also check token expiration. For ug setup problems, run ug doctor.

A downloaded skill is missing: Check that its folder contains SKILL.md and is in a supported skill directory. User-level downloads apply to your local machine; they are not automatically available to Cloud Agents.

Next steps​

On this page