Connect your agent over MCP

The MCP server

Everything an agent can do on Benchy goes through one endpoint: https://mcp.benchy.studio/api/mcp, speaking Streamable HTTP (SSE is deliberately disabled). It registers tools across four prefixes; the exact set depends on account access, token scope, and deployment safety gates:

For Claude Code, Cursor, or any client that takes a JSON MCP config, this is the whole setup:

{
  "mcpServers": {
    "benchy": {
      "url": "https://mcp.benchy.studio/api/mcp",
      "headers": { "Authorization": "Bearer bnchy_..." }
    }
  }
}

Our hosted agent at benchy.studio consumes exactly this surface with your own credentials — no back doors, no privileged internal API. If our agent can do it, yours can. Studio also ships an optional AI SDK dual-runtime (same MCP tools, Gateway xai/grok-4.5) behind NEXT_PUBLIC_STUDIO_AGENT_RUNTIME=aisdk — still your JWT, still this endpoint. Skills and memories knowledge tools are always on for that agent; writes ask for Approve/Deny in the chat UI before they persist.

Personal access tokens

Mint tokens at benchy.studio → Profile → API keys. The essentials:

• Format is bnchy_ plus 32 characters. The plaintext is shown once; only its SHA-256 hash is stored.
• Two scopes: Full access or Read-only. Read-only tokens can call every read tool; every write is refused.
• Expiry options are 30, 90, or 365 days, or never (the default is 90).
• Up to 20 active tokens per account — one per agent is good hygiene.

Hosted connectors (OAuth)

Hosted agents that can't hold a pasted secret (ChatGPT connectors, hosted Claude) use OAuth instead: discovery via https://mcp.benchy.studio/.well-known/oauth-protected-resource, authorization at https://id.benchy.studio with dynamic client registration and PKCE, and mcp:read / mcp:write scopes with refresh-token rotation. Connect Benchy from the connector's directory and approve the scopes — no token handling required.

How auth works under the hood

A token is never used directly against a spoke. On every call, the hub exchanges it for a 120-second JWT carrying your sites, plan, shopBuyer, and mcpScope claims; spokes verify the signature against the hub's JWKS. Scope is enforced twice: a read-only credential is refused writes at the hub, and every spoke independently hard-rejects mutations carrying a read-only claim. Compromising one check buys nothing at the other.

Failed tools return a structured errorCode. Two are worth retrying in-loop: concurrency_conflict (re-read state, then retry) and elicitation_unsupported (re-call with the explicit argument). The rest — not_found, validation, cap_reached, rate_limited, unauthorized — need a state change or a human.

The audit log

Every tool call — success, error, or denied — lands in the hub's audit log with the user, token, tool name, duration, and error code. Never the arguments and never the return values: you can audit who did what without building a surveillance archive of what they said. Destructive tools additionally accept dryRun: true so agents can preview before they act.

Heavy lifting: benchy-cli

For bulk work and big files there's benchy-cli, a single-file Bun binary that speaks the same MCP protocol from your terminal — same tools, same scopes, same audit log:

export BENCHY_PAT='bnchy_...'
benchy whoami
benchy upload ./robot.glb --title "Articulated robot" --tags=robot
benchy list

Ready to hand the whole playbook to your agent? The agent skills are self-contained documents that teach an agent everything on this page and more.