# Connect your agent

> Connect Claude Code, Codex, Cursor or any MCP client to one of your workspaces, with the access you choose.

Canonical: https://benchy.world/docs/connect-your-agent
Last updated: 2026-10-27

## The address to connect to [#choose-connection]

Claude Code, Codex, Cursor, ChatGPT and any other agent that speaks the Model Context Protocol (MCP) work in Benchy through one address:

url

```
https://mcp.benchy.studio/api/mcp
```

It speaks Streamable HTTP, with no local server to run. A client that can only start a command uses `mcp-remote`; [Benchy Studio → Profile → API keys](https://www.benchy.studio/dashboard/profile?tab=api-keys) sets it up under **Connect a client**, with steps for each agent. Tools that use your Mac — slicer, printers, Blender — also need [Benchy Desktop](https://benchy.world/docs/desktop).

## One workspace per connection [#one-workspace]

Every connection works in exactly one workspace, chosen when you make it, so an agent set up for one client never reads another's work. To use an agent in two workspaces, connect it twice. As a guest you can connect an agent in someone else's workspace; it reaches only what is shared with you, at the access you had when you connected it. Benchy Desktop works in the one workspace you choose when you sign it in.

World is your own account, not part of a workspace, so a connection reaches it only when you grant it: the **World** area on a key, or **World** when an app asks at sign-in. Selling, refunds, checkout and payouts need **World payments** as well, which starts off.

## Connect with browser sign-in [#sign-in]

Most agents need no key. Add the address as a remote MCP server; the agent opens Benchy in your browser, where you sign in, choose a workspace, and allow read, or read and write. Then start a new conversation in the agent.

### Claude Code [#claude-code]

shell

```
claude mcp add --scope user --transport http benchy https://mcp.benchy.studio/api/mcp
```

Then type `/mcp`, choose `benchy`, and choose **Authenticate**. With [Benchy Desktop](https://benchy.world/docs/desktop#your-other-agents) signed in on the same Mac, Benchy is already added.

### Codex [#codex]

In the ChatGPT desktop app, open **Settings → MCP servers → Add server**. Name it `benchy`, choose **Streamable HTTP**, enter the address and leave the token and header fields empty. Save, restart the server, then choose **Authenticate**. Or, from the terminal:

shell

```
codex mcp add benchy --url https://mcp.benchy.studio/api/mcp
```

This connects the ChatGPT desktop app, the Codex command line and its editor extension on that computer. ChatGPT on the web is set up separately.

### Cursor [#cursor]

Add a server named `benchy` with the address to `.cursor/mcp.json` in a project, or to `~/.cursor/mcp.json` for every project. Then open **Customize → MCP** in Cursor and sign in beside it. Benchy Desktop adds it for you on its Mac.

### ChatGPT on the web [#chatgpt]

On chatgpt.com, open **Plugins**, add a custom MCP server with the address, and choose OAuth. The connection then works in Chat and in Work. Ask for read access (`mcp:read`) to start, and add `offline_access` so it stays signed in. Whether you can add one depends on your ChatGPT account and workspace policies.

### Claude [#claude]

In Claude's connector settings, add a custom connector with the address and sign in. It works in claude.ai, the Claude desktop app and Cowork.

### Any other MCP client [#other-clients]

Any client that speaks MCP over HTTP connects the same way, and **Connect a client** in Studio has steps for VS Code too. A script, a CI job or a client that can't open a browser needs an API key; **Connect a client** shows the key setup for each agent.

## Connect with an API key [#api-keys]

In Studio, open **Profile → API keys** and choose **New key**. You choose:

- **The workspace** it works in.
- **Its access**: **Read**; **Ask me each time**, where reads run and every change waits for your approval; **Read and write**; or **Publish websites**, which creates, publishes, previews, rolls back and unpublishes websites and nothing else. New keys start on Read and write; to try an agent, choose Read or Ask me each time.
- **Which areas** it reaches, from the list below. Benchy chat and Generate media spend Credits, and World is your own account, so they start off. With World on, **World payments** lets a Read and write or Ask me each time key sell, refund and manage payouts too.
- **A monthly Credit limit**, 250 to start, counted from the day you made the key.
- **When it expires**: in 30 days, 90 days (the default), a year, or never (not recommended).

The key starts with `bnchy_` and is shown once. Keep it where your agent's instructions say, never in a chat or a document. Access and areas are fixed; for different ones, make a new key and revoke the old. An account holds up to 20 keys; make one per agent so you can turn one off alone.

## Ask me each time [#ask-each-time]

With a key on **Ask me each time**, a change comes back to the agent as `approval_required`, with a link to the request. Answer from the bell, from **Waiting for you** at the top of **API keys**, or from the link:

- **Approve once** runs that one call, with exactly those arguments.
- **Allow for an hour** lets the key make that kind of change to the same thing for an hour. It isn't offered for creating, deleting, revoking, moving money or changing a status.
- **Deny** refuses it, and the same call stays refused for an hour.

After approval the agent repeats the same call and it runs. A request waits up to 24 hours, and up to 50 can wait per key. Browser sign-in connections don't have this mode, and Benchy chat keeps its own approval cards either way.

## What your agent can reach [#what-agents-can-do]

| Area | What your agent can work with |
| --- | --- |
| Benchy chat | Start and read Benchy conversations, and ask Benchy |
| Projects | Projects, their files and folders, versions, links and [BENCHY.md](https://benchy.world/docs/benchy-md) |
| Canvas | Canvases, their scenes and files, and the workspace's Elements |
| Comments | Read, add and resolve [comments](https://benchy.world/docs/canvases-and-docs#comments) on what you can open |
| Generate media | Images, video, SVG, 3D models and audio made on a canvas, at the same prices as **Generate** there |
| Memories and skills | What Benchy remembers about you in this workspace, your skill library when the connection is tied to a workspace you own (also offered as prompts), the workspace's [machines](https://benchy.world/docs/printers#profiles), and Benchy's printing references and production check |
| Skills documents | The documents behind your skills |
| Websites | Websites and their releases: publish, preview, roll back, unpublish, custom domains, content and form entries |
| World | Your listings, offers and orders on World, and download links for files you may download, even on a Read key. Prices, plans, checkout, refunds and payouts need World payments too |

Whatever the connection allows, your agent never does more than you can in that workspace right now, or, on World, more than you granted it there.

A paid call uses the workspace's Credits and counts against the key's limit. An agent can check what is left with `benchy_usage`, and cap one generation with `maxCredits`. See [Credits and plans](https://benchy.world/docs/credits-and-plans). Benchy itself never buys, refunds, cancels a membership or opens payouts on World, even in a chat your agent starts.

## Check the connection [#verify]

Ask your agent to list its Benchy tools, then start with a read, such as listing the workspace's projects. A key lists only the tools in its areas; write tools stay on the list for a Read connection, and calling one is refused. If a call is refused, find its code below; don't ask the agent to work around it.

## When a call is refused [#errors]

| Code | What it means, and what to do |
| --- | --- |
| 401 `invalid_token` | The key is revoked, expired or mistyped, or wasn't sent. Make a new key, or sign in again. |
| 403 `insufficient_scope` | The connection can read but not write. Sign in again and allow writing, or make a key with Read and write. |
| 403 `tool_not_granted` | The key doesn't reach that area, World or World payments. Make a key with it on. |
| `world_not_granted`, `world_payments_not_granted` | The connection wasn't granted World, or World payments. Make a key with it on, or sign the app in again and allow it. |
| `approval_required` | Answer the request in Studio; the agent then repeats the call. See [Ask me each time](#ask-each-time). |
| `approval_denied` | You denied it. The agent should stop, not retry. |
| `API_KEY_SPEND_LIMIT_EXCEEDED` | The key used its monthly Credits. Raise the limit under API keys, or wait for its month to turn. |
| `APP_SPEND_LIMIT_EXCEEDED` | The same, for a connected app; its limit is in the **Sessions** section of **Profile**. |
| `INSUFFICIENT_CREDITS` | This week's usage and the workspace's Credits can't cover it. |
| `workspace_not_bound` | The agent named another workspace than the one it is connected to. |
| `creator_not_approved` | Selling on World is open to approved creators. See [Selling on World](https://benchy.world/docs/selling). |
| `account_not_linked` | Sign in to benchy.world once, at the address given, then try again. |
| 429 | Too many calls. Wait for the time in the Retry-After header. |
| 503 | Benchy couldn't check the key just then. Nothing ran; send the same call again shortly. |

A key or app can spend 300 units a minute, and an account 1,500 across all of them. Most calls cost one unit; reading or changing a whole canvas scene costs 5, and building or deploying a website, or exporting a page or form entries, costs 30. Listing tools and resources isn't counted. If Benchy shows as connected but offers no tools, start a new conversation in the agent.

## Stay in control [#control]

**Recent MCP activity**, under **API keys**, lists the tools each connection used and how they turned out. Revoke a key under **API keys**, or sign out a connected app under **Sessions** in **Profile**; either stops it within about a second, and revoking a key closes its waiting approvals. If a key leaks, revoke it, check the activity for calls you didn't make, and make a new one. Leaving or being removed from a workspace revokes every key and app connected to it.

Treat what an agent reads in Benchy, such as listing text or a file's contents, as data, not instructions. A connection gives your agent access; a skill gives it instructions. See [Skills, @ and /](https://benchy.world/docs/skills).