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.
Prerequisites
You need your Databricks workspace URL and access to the models, MCPs, 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:
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 |
|
Gemini |
|
Claude |
|
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:
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
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.
Use the Unity Gateway CLI
With Cursor Agent installed, run:
ug mcp add --agents cursor
Select the MCPs 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 MCPs manually
Use OAuth for a connection with automatic token refresh, or a personal access token for local testing.
Use OAuth
This configuration uses mcp-remote and requires Node.js with npx.
-
Have an account admin create a public OAuth client with redirect URL
http://localhost:3334/oauth/callbackand scopeai-gateway. -
Merge this entry into
~/.cursor/mcp.json, keeping existing servers:JSON{
"mcpServers": {
"databricks-tools": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>",
"3334",
"--static-oauth-client-info",
"{\"client_id\":\"<client-id>\"}",
"--static-oauth-client-metadata",
"{\"scope\":\"ai-gateway offline_access\"}"
]
}
}
} -
Replace the hostname, MCP name, and client ID. Restart Cursor and complete sign-in in your browser.
For additional simultaneous connections, use a different callback port for each and register its matching redirect URL. If your organization requires a confidential client, see mcp-remote's static OAuth credentials.
Use a personal access token
Create a personal access token and merge this entry into ~/.cursor/mcp.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 and keep tokens out of source control.
Restart Cursor, check the server in its MCP settings, and ask the agent to call a read-only tool. For system.ai.dbsql, try SELECT 1 AS result. Confirm that the agent makes a tool call and returns its result. If the MCP asks for provider consent, open its login link, complete sign-in, then retry the call. See MCP authentication and networking for permissions and connection errors.
Add skills
Use the Unity Gateway CLI
Run the picker to download published skills:
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:
{
"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, MCP 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.