Connect your agent
Connect Claude Code, Codex, Cursor or any MCP client to one of your workspaces, with the access you choose.
The address to connect to
Claude Code, Codex, Cursor, ChatGPT and any other agent that speaks the Model Context Protocol (MCP) work in Benchy through one address:
https://mcp.benchy.studio/api/mcpIt 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 sets it up under Connect a client, with steps for each agent. Tools that use your Mac — slicer, printers, Blender — also need Benchy Desktop.
Screenshot: Connect a client in Studio, with the steps for the client you picked.
One workspace per connection
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
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 mcp add --scope user --transport http benchy https://mcp.benchy.studio/api/mcpThen type /mcp, choose benchy, and choose Authenticate. With Benchy Desktop signed in on the same Mac, Benchy is already added.
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:
codex mcp add benchy --url https://mcp.benchy.studio/api/mcpThis 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
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
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
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
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
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
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
| 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 |
| Canvas | Canvases, their scenes and files, and the workspace's Elements |
| Comments | Read, add and resolve 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, 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. Benchy itself never buys, refunds, cancels a membership or opens payouts on World, even in a chat your agent starts.
Check the connection
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
| 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. |
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. |
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
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 /.