Documentation 40

MCP · the agent front door

One config line. No credentials.

An agent calls orient and receives everything it needs to make a correct API call — with no docs reading, no human setup, and nothing to clean up afterwards.

Add it to your client

One action per client.

Each of these connects your client to the hosted server at https://api.sandboxapis.dev/mcp, with nothing to install; Claude and ChatGPT sign you in and draw on your own key.

Claude, web and desktophttps://api.sandboxapis.dev/mcp/authCustomize → Connectors → Add custom connector, paste, Sign in now.
ChatGPThttps://api.sandboxapis.dev/mcpDeveloper mode → create connector, paste, choose OAuth.
Claude Codeclaude mcp add --transport http sandboxapis https://api.sandboxapis.dev/mcpRun it in a terminal. It works with no key, on the anonymous budget.
CursorAdd to Cursorhttps://api.sandboxapis.dev/mcpOpens Cursor, which shows the server before it installs. No key in the link.
VS CodeAdd to VS Code Insidershttps://api.sandboxapis.dev/mcpOpens VS Code, which asks before it adds the server. No key in the link.
AntigravityShow the confighttps://api.sandboxapis.dev/mcpAdd it as serverUrl in mcp_config.json, then reload the server.

Prefer to run it locally? The npm package and its one-click Cursor link are under Install, below.

What the agent gets

One call to orient, recorded.

This is what orient returned to a fresh, anonymous session on 28 October 2026 (sandboxapis 0.3.20). The server was started with SANDBOXAPIS_BASE_URL_GITHUB=https://gh-2026-03-g12.snap.sandboxapis.dev, the frozen gh-2026-03-g12 pin, so every request below answers exactly as recorded, for good.

Its budget, before it spends any. The access block, as recorded; a live call reports your own window.

json

{
  "keyed": false,
  "limit": 60,
  "remaining": 60,
  "reset": 1793202637,
  "upgradeUrl": "https://sandboxapis.dev/upgrade?from=anonymous",
  "note": "Anonymous: 60 requests/hour shared across every provider host; set SANDBOXAPIS_API_KEY to a free key for 600/hour and opt-in scratch writes."
}

25 providers, each with its base URL and a line on how to point a client at it, plus 148 pinned snapshot hosts, the org's 4 teams and 1 repositories, and where the coverage manifest lives.

7 entry points, each a request it can run next:

Flagship repository. The org's most recently active repo (default branch main).
terminal
```
curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/repos/olympus-labs/parthenon
```
A merged pull request. PR #83 "Clean up the core library": a completed arc from review to merge; its merge commit exists in history.
terminal
```
curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/repos/olympus-labs/parthenon/pulls/83
```
A draft pull request (edge case). PR #47 "WIP: Refactor event batching": draft state, useful for testing draft/ready handling.
terminal
```
curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/repos/olympus-labs/parthenon/pulls/47
```
Richest pull request. PR #71 "Clean up the CLI": 8 inline review comments across its discussion.
terminal
```
curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/repos/olympus-labs/parthenon/pulls/71
```
An open issue. Issue #82 "Question: how should the session cache behave when two tabs are open?": cross-references authors, labels, and (often) a milestone.
terminal
```
curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/repos/olympus-labs/parthenon/issues/82
```

A recent commit. 6da56bead498: the latest commit; the SHA is identical on every provider rendering.

terminal

curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/repos/olympus-labs/parthenon/commits/6da56bead49874592a691b7a22eee0b59d3b72c3

Largest team. Argonauts (@olympus-labs/argonauts): 5 members.

terminal

curl -s https://gh-2026-03-g12.snap.sandboxapis.dev/orgs/olympus-labs/teams/argonauts

01 / Install

Add the server.

The row at the top of this page does each of the hosted forms below in one step.

Option one: the hosted URL. Nothing to install. The server runs at https://api.sandboxapis.dev/mcp over Streamable HTTP, with no sign-in, and answers with the same tools as the npm package below. In Claude Code:

terminal

claude mcp add --transport http sandboxapis https://api.sandboxapis.dev/mcp

In Cursor, add it to mcp.json by URL:

json

{
  "mcpServers": {
    "sandboxapis": {
      "url": "https://api.sandboxapis.dev/mcp"
    }
  }
}

In Claude (desktop or web), open Customize, then Connectors, and choose Add custom connector. To connect Claude to your account, paste https://api.sandboxapis.dev/mcp/auth, choose Sign in now, then Use Claude's published identity or Register automatically, and add no headers. Claude starts a sign-in only when a server refuses a call that has none, so this second address serves the same tools and refuses calls without a sign-in, while https://api.sandboxapis.dev/mcp never does. The plain https://api.sandboxapis.dev/mcp address stays for anonymous use, or for a key under Request headers. Any other client that takes a remote MCP server URL takes either one.

In ChatGPT, turn on developer mode, create a connector with the URL, and choose OAuth. The connector asks you to sign in to sandboxapis.dev. On the approval page you pick one of your keys, or create a new one, and the connection then draws on that key's budget. It appears under the key on the dashboard, and you can revoke it there. If you would rather not sign in, choose No authentication instead: the connector still works, on the anonymous budget of 60 req/hour. How the sign-in works.

In Antigravity, add it to ~/.gemini/config/mcp_config.json for every workspace, or .agents/mcp_config.json for one project. Antigravity names a remote server by serverUrl; it does not read url:

mcp_config.json

{
  "mcpServers": {
    "sandboxapis": {
      "serverUrl": "https://api.sandboxapis.dev/mcp"
    }
  }
}

That runs on the anonymous budget with no further setup. To sign in instead, use https://api.sandboxapis.dev/mcp/auth, which refuses a call with no credential so that Antigravity starts the sign-in, and choose Authenticate next to the server in Antigravity's settings. Our authorization server takes dynamic client registration, so the entry needs no oauth block:

mcp_config.json

{
  "mcpServers": {
    "sandboxapis": {
      "serverUrl": "https://api.sandboxapis.dev/mcp/auth"
    }
  }
}

Prefer a local process to https://api.sandboxapis.dev/mcp? The npm package goes in the same file, with your key as SANDBOXAPIS_API_KEY in its env (leave the env out to run anonymously):

mcp_config.json

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

After editing the file, reload the server from Antigravity's MCP manager (/mcp in the CLI, the refresh button under Settings, Customizations, Installed MCP Servers in the app), or restart Antigravity.

The SandboxAPIs plugin for Antigravity bundles the hosted server with a skill that teaches the agent to test against it; the Antigravity tutorial walks through installing it.

Option two: the npm package. Register it as a stdio MCP server in your agent (e.g. Claude Code):

terminal

claude mcp add sandboxapis -- npx -y @sandboxapis/mcp

In Cursor, one click does the same. The link carries the server command and nothing else:

Add to Cursor

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

Or point any MCP client at the equivalent stdio command. Cursor users can also install the whole SandboxAPIs plugin, which adds a rule that teaches the agent to call orient first and check_budget before a loop; the Cursor tutorial walks through it.

02 / OAuth

Connect with OAuth.

ChatGPT connectors and Claude's connector directory cannot carry a pasted key. They run an OAuth sign-in instead, and the hosted URL supports one: the app sends you to a SandboxAPIs page, you sign in and approve, and the connection draws on one of your keys without the key ever leaving your account.

Clients find everything from the metadata, at https://sandboxapis.dev/.well-known/oauth-authorization-server (and the same document at https://sandboxapis.dev/.well-known/openid-configuration). It names the authorization, token, registration and revocation endpoints. Authorization codes require PKCE with S256, there is one scope, universe:read, and clients register either by a client metadata document URL or by dynamic registration.

On the approval page you choose the key. It lists your live keys by name and last four characters, with an option to create a new key named after the app. The page also names the host the app returns you to; approve only a connection you started yourself.

Tokens live one hour. The app refreshes them on its own, and every refresh replaces the refresh token, so a copied one stops working the first time either copy is used.

Every connection is listed on the dashboard, under the key it draws on, with when it was connected and when it last got a token. Revoke one there and its token stops working on the next request. Revoking the key revokes every connection that uses it.

How the hosted URL answers. A call with no credential is still served, on the anonymous budget, and its response carries a WWW-Authenticate header that points at the protected-resource metadata, at https://api.sandboxapis.dev/.well-known/oauth-protected-resource. That document names https://sandboxapis.dev as the authorization server, which is how a client finds the sign-in. A token that has expired or been revoked gets a 401 with error="invalid_token" in the same header, so the app knows to refresh or to ask you to connect again. At https://api.sandboxapis.dev/mcp/auth, a call with no credential is not served: it gets a 401 whose WWW-Authenticate header points at that address's own metadata, at https://api.sandboxapis.dev/.well-known/oauth-protected-resource/mcp/auth, so the client starts the sign-in. A key or a token works there exactly as on https://api.sandboxapis.dev/mcp. A token issued for either address works on both and only there, never on a provider host.

03 / Your key

Use your API key.

That line works with no key, and it runs on the anonymous budget: 60 req/hour, shared by every caller on your address across every provider host. One orient plus a handful of tool calls is already a visible slice of 60, so an agent in a loop finds the ceiling quickly. A free key raises it to 600 req/hour and moves the budget onto your account, where it belongs to you rather than to your network. Get a free key, then give it to the server as SANDBOXAPIS_API_KEY.

In Claude Code, on the same line that registers the server:

terminal

claude mcp add sandboxapis --env SANDBOXAPIS_API_KEY=sk_live_… -- npx -y @sandboxapis/mcp

In Claude Desktop or Cursor, which read a JSON config, the key is an env entry beside the command:

json

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

In any other client, export it in the shell the server starts in:

terminal

export SANDBOXAPIS_API_KEY=sk_live_…

On the hosted URL, the key is a header, Authorization: Bearer sk_live_…, sent with every request to https://api.sandboxapis.dev/mcp. In Claude Code:

terminal

claude mcp add --transport http sandboxapis https://api.sandboxapis.dev/mcp \
  --header "Authorization: Bearer sk_live_…"

In Cursor, a headers entry beside the URL:

json

{
  "mcpServers": {
    "sandboxapis": {
      "url": "https://api.sandboxapis.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_…"
      }
    }
  }
}

In Antigravity, the same headers entry beside serverUrl:

mcp_config.json

{
  "mcpServers": {
    "sandboxapis": {
      "serverUrl": "https://api.sandboxapis.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_…"
      }
    }
  }
}

In a Claude custom connector, add the same header under Request headers. ChatGPT's developer mode has no field for a key: connect it with OAuth to use your key's budget, or choose No authentication and it runs on the anonymous budget.

04 / Tools

What the agent gets.

orient — start here. Universe, providers + base URLs, live-vs-snapshot and how to pin, the org and teams, 7 notable entry points, where the coverage manifest lives, and an access block: keyed or not, the requests left this hour, and where to raise the limit.
check_budget — free to call, and the thing to call before a loop. The real hourly window (limit, remaining, when it resets), read through an endpoint that is exempt from the budget it reports.
list_repositories, get_repository, list_pull_requests, get_pull_request (with reviews), list_issues, get_user — REST-identical results with provider-form ids.
search_commits_by_author — cross-referenceable SHAs.
get_snapshot — a pinned, reproducible hostname for CI.

05 / Prefer HTTP?

Skip MCP entirely.

Point your client library at the base URLs directly — see the GitHub and GitLab quickstarts, or the agent guide.