> ## Documentation Index
> Fetch the complete documentation index at: https://docs.universalbench.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use with Cursor

> Add UniversalBench to Cursor so your AI editor can run code, query your data, search the web, invoke LLMs, and manage secrets.

Cursor speaks MCP natively. Adding UniversalBench takes about 30 seconds because there is no header config to fight with. The connection is one URL.

## Setup

<Steps>
  <Step title="Get your personal MCP URL">
    Sign up at [universalbench.dev](https://universalbench.dev) and copy your URL from the dashboard. It looks like `https://universalbench-mcp.penantiaglobal.workers.dev/u/ubk_...`
  </Step>

  <Step title="Open Cursor MCP settings">
    Open Settings with `Ctrl+,` (Windows or Linux) or `Cmd+,` (macOS), then go to **Tools & MCP** in the sidebar and click **Add Custom MCP**. Cursor opens your `mcp.json` file (at `~/.cursor/mcp.json`).
  </Step>

  <Step title="Paste the config">
    Replace the contents of `mcp.json` with this, using your own URL:

    ```json theme={null}
    {
      "mcpServers": {
        "universalbench": {
          "url": "https://universalbench-mcp.penantiaglobal.workers.dev/u/ubk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
    ```

    Notice there is no `headers` block. The URL itself is the auth. Save the file.
  </Step>

  <Step title="Confirm the connection">
    Back in **Tools & MCP**, `universalbench` appears under User MCP Servers with a green dot, and three tools are listed: `ub_read`, `ub_write`, and `ub_ai`. The connection is usually instant. If it does not appear, reopen the settings panel or restart Cursor.
  </Step>
</Steps>

## The three tools

UniversalBench exposes three tools, grouped by what they do:

| Tool       | What it does                                                                                                                                                                                                                 |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ub_read`  | Read-only work: read files, run read-only SQL (`db_select`, `db_query`, `db_search`), read from GitHub, check account status                                                                                                 |
| `ub_write` | Anything that changes state: run code and bash, write files, install packages, run parallel jobs, push to GitHub with validation, safe deploys, write to your database, store secrets in the vault, make outbound HTTP calls |
| `ub_ai`    | Web search and LLM calls, with cost caps on by default                                                                                                                                                                       |

## What you can do now

Ask the Cursor Composer things that need execution:

> Run a quick analysis on the test runs in `/tmp/results.csv`. Group failures by file and tell me the top three offenders.

Cursor uses `ub_write` with its `code` capability to read the CSV with pandas, group the failures, and return the analysis as plain text. No CSV dump in the context window.

Or:

> Use the cheapest available LLM via UniversalBench to draft a commit message for my staged diff.

Cursor uses `ub_ai` with `invoke_llm` to route to a cheap model, saving tokens compared to using the editor's primary model for low value text generation.

## When to reach for UniversalBench in Cursor

UniversalBench is not a replacement for Cursor's local tools. For editing files in your repo and running local tests, Cursor's own tools are faster. UniversalBench earns its place when you want:

* The agent to query or change **your database or GitHub** using credentials stored once in the vault, without pasting tokens into chat
* **Validated pushes and safe deploys** with rollback, rather than commit and hope
* An **isolated cloud runtime** when you do not want agent code running on your machine, or your local shell is restricted
* **Cost-capped LLM and web calls** for small bounded subtasks

For plain local edits, stick with Cursor's built in tools.

## Tips

<Tip>
  For multi step pipelines that need state, pass a `session_id` so imports and variables persist across calls.
</Tip>

## Troubleshooting

| Problem                          | Fix                                                                                             |
| :------------------------------- | :---------------------------------------------------------------------------------------------- |
| Tools do not appear after saving | Reopen Tools & MCP, or restart Cursor. The server should show "universalbench" with a green dot |
| 401 or 403 errors                | The token after `/u/` has a typo. Paste the URL again from the dashboard                        |
| Slow first call                  | The first call after idle has a small cold start. Subsequent calls are fast                     |