Documentation 34

Tutorial · Cursor · 10 min

Use SandboxAPIs in Cursor.

The other four tutorials hand you a script. This one hands Cursor's agent the same job: install the SandboxAPIs plugin with one click, give it a free key, open the examples repository, and ask the agent to trace one incident across the pinned Slack, Jira and GitHub hosts. Then score the run with the eval pack. Nothing it reads can change under it, and nothing it tries to write can land.

01Install with one click

02Add a key and pin the hosts

03Ask the agent, then score it

01 / Install

One click. No key in the link.

Cursor installs an MCP server from a link in its own URL scheme. This one carries exactly the server command below, base64-encoded as Cursor's docs specify, and Cursor shows it to you before anything is written:

what the link carries

{
  "command": "npx",
  "args": [
    "-y",
    "@sandboxapis/mcp"
  ]
}

Add to Cursor

Opens Cursor and shows you the server config before installing. No key in the link.

The link deliberately carries no key. A link can only hold a literal, so a keyed one would ship a placeholder and install a broken server for everyone who clicks it and never edits it. The key is the next section.

If the link does nothing, Cursor is not installed on this machine or your browser is not handing cursor:// links to it. The manual route is the same config in .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all of them:

.cursor/mcp.json

{
  "mcpServers": {
    "sandboxapis": {
      "command": "npx",
      "args": [
        "-y",
        "@sandboxapis/mcp"
      ]
    }
  }
}

The link installs the server. The plugin installs the rule too.

Cursor's plugin format carries three things the install link cannot: a rule file the agent reads when it judges it relevant, a skill, and the server entry. The SandboxAPIs plugin ships all three. Cursor's docs say a plugin tests locally from ~/.cursor/plugins/local/<name> after a restart, so until it is listed on the marketplace this is how the whole plugin installs:

terminal

git clone https://github.com/driftwork-llc/sandboxapis-examples
mkdir -p ~/.cursor/plugins/local
cp -r sandboxapis-examples/cursor-plugin ~/.cursor/plugins/local/sandboxapis

The rule is short and worth reading once. It tells the agent to call orient first, check_budget before a loop, to pin a snapshot host for anything it will assert, and that a write refusal or a 404 carrying X-SandboxAPIs-Coverage is an answer rather than something to retry. It is alwaysApply: false, so it costs nothing in chats that have nothing to do with this server.

02 / Your key, and the pins

Raise the budget, then hold the hosts still.

With no key the server runs on the anonymous budget, 60 req/hour, shared by every caller on your address. One orient plus the task below fits, but an agent that explores will find the ceiling. A free key raises it to 600 req/hour on your own account. In Cursor the key is an env entry on the server, in Cursor Settings under MCP or in the JSON file directly.

The same env block is where you pin. The live hosts roll their data forward daily, which is right for a demo and wrong for anything you will compare against twice. Each SANDBOXAPIS_BASE_URL_* variable points one service at a pinned host; these three are the ones the agent tutorials use, all serving the generation content addressed at c27f762cc1d2:

.cursor/mcp.json

{
  "mcpServers": {
    "sandboxapis": {
      "command": "npx",
      "args": ["-y","@sandboxapis/mcp"],
      "env": {
        "SANDBOXAPIS_API_KEY": "sk_live_…",
        "SANDBOXAPIS_BASE_URL_GITHUB": "https://gh-2026-03-g12.snap.sandboxapis.dev",
        "SANDBOXAPIS_BASE_URL_JIRA": "https://jira-v3-g12.snap.sandboxapis.dev",
        "SANDBOXAPIS_BASE_URL_SLACK": "https://slack-2026-08-g12.snap.sandboxapis.dev"
      }
    }
  }
}

Restart the server from Cursor's MCP settings after editing. orient then reports those hosts as the base URLs, and its access block says whether the key was read. Versioning and pinning explains the registry; get_snapshot returns the same hostnames from inside a session.

03 / The repository

Open the examples repo.

sandboxapis-examples is the public repository behind the eval pack and the three agent tutorials. Opening it in Cursor applies the same rule from .cursor/rules/sandboxapis.mdc at its root, so if you skipped the local plugin above the agent is still briefed. It also puts evals/ in reach for section 05.

terminal

git clone https://github.com/driftwork-llc/sandboxapis-examples
cursor sandboxapis-examples

04 / The task

Install the plugin, then ask Cursor's agent to find the incident across Slack, Jira and GitHub and score the run.

Open the agent panel and paste this. It names the incident by its title rather than its key so the agent has to find it, and it asks for the host behind each answer so you can see the crossing happen:

prompt

Call orient first, then check_budget. Then find the incident the agent tutorials read, on the pinned hosts:
1. the Jira issue titled "Postmortem follow-up: events dropped during a rebalance": its key, status and who filed it;
2. the pull request that fixed it on the GitHub host: its number, head branch, head SHA, and whether anyone other than its author approved it;
3. the #incident-bridge thread about it on the Slack host: whether it is resolved and who called the all clear.
Report the three as one timeline and say which host answered each.

What a correct run comes back with, in whatever words the model chooses:

expected

Jira    FATE-51  "Postmortem follow-up: events dropped during a rebalance"  Done
GitHub  PR #53  hotfix/backfill-job-ooming  94dd1fdf3b96  merged, approved by someone other than the author
Slack   #incident-bridge  resolved

Those are the values the three agent tutorials assert on the same hosts, so they are held by tests rather than typed here: Pinned GitHub for the pull request, Pinned Jira for the issue, Pinned Slack for the thread. If the agent reports something else, the first question is which host it asked: an unpinned server answers from the live hosts, where the incident has a different key and number.

What the server can and cannot do here, said plainly.

The ten tools cover repositories, pull requests, issues (Jira included), users and commits, which answers the first two lines. There is no Slack tool. orient returns the Slack host's base URL and a ready-to-run request, and Cursor's agent can run a curl in the terminal, so a capable run fetches the thread over HTTP with the same key. A run that reports the Slack line as unknown has read the tools correctly and stopped early; that is a finding about the agent, not the data.

Every host is read-only. If the agent decides to comment on the issue or close it, the host answers with the provider's own error shape and a plain message naming what was attempted, and the rule tells the agent not to retry. The one exception, scratch writes for GitHub issues and comments, is off until you turn it on for a key, and keys and rate limits describes exactly what it permits and for how long.

05 / Score it

The eval pack, from the skill or the terminal.

The plugin's skill, sandboxapis-eval, runs the answer-key eval pack from the repository you just opened and reads back the score by difficulty. Ask for it by name:

prompt

Use the sandboxapis-eval skill to score the data set, then score the agent.

Or run the same thing yourself, with Node 22 and nothing installed:

terminal

cd sandboxapis-examples/evals
node run.mjs

A full run is twelve requests. Reading the answers out of the responses scores the data set, and every item should pass; replacing answer() with a model call and running with --agent scores the agent, and a failure then tells you whether it read the right rows wrongly. With the flight recorder on for your key, SANDBOXAPIS_RUN=<name> lands the whole run in your dashboard as one timeline.

06 / What Cursor does and does not do

Read before you file a bug.

The install link adds the server only. Rules cannot be imported by a link; Cursor's docs list a plugin, a Team Rule, or a file checked into the repository as the ways a rule arrives. That is why the rule is in the plugin and at the examples repo's root both, and why those two files are asserted byte-identical on every build.
The plugin is not on Cursor's marketplace yet. Cursor reviews every plugin by hand and requires it to be open source, which it is. Until it is listed, the local-plugin directory above is the install, and this page will say so when that changes.
The rule is advisory. It is text the model reads, not a hook that blocks a call. An agent can still ignore check_budget and hit the hourly ceiling; when it does, the refusal carries an upgrade field rather than a surprise, and the budget resets within the hour.
Nothing on this page was captured from a Cursor session. The link format, the plugin layout and the local-plugin path are from Cursor's own documentation, read 2026-10-02. The expected answers are from the tests behind the three agent tutorials. If Cursor's behaviour differs from what is written here, say so and this page will change.

Where to go from here.

The three agent tutorials, Pinned GitHub, Pinned Jira and Pinned Slack, are the same incident with a script in place of Cursor, which is where to go when you want the assertion in CI rather than in a chat. MCP setup covers the server for every other client.

All tutorials · The eval pack · Keys and rate limits · Versioning and pinning · Coverage manifest