https://mcp.summerengine.com/mcp), on the summer-engine npm MCP and in the summer CLI (--json). Your agent reads status first. Connect your agent: MCP setup.
The answer
needs_approval answer comes when a switch in Studio > Settings > Agent permissions is off, when the change always asks, or when Summer Games still asks (for now: an agent’s publish or release asks the game’s owner; price, A/B test and member changes ask the person). Nothing changes until the person approves. See Agent permissions and approvals.
Errors
An error answersok: false with error.code, a plain message, one next step and retry. Do the next step first. next is one of:
{ "op": "...", "input": {...} }: the operation to call;{ "url": "...", "label": "..." }: a link to give the person;{ "say": "..." }: what to tell the person.
retry says if the same call may run again:
The list of codes is closed: a new code is a new version of the catalog.
When credits run out, the answer is
no_credits with one link: https://www.summerengine.com/studio/credits (Add credits). In ChatGPT, the agent tells you in words.
dryRun
Every operation that changes something takesdryRun: true. Summer checks and describes the call: nothing changes, nothing is spent and nothing is sent. The answer is dry_run with a preview: a summary, the changes, the approval it needs, and for spend operations your estimated credits.
idempotencyKey
Every operation that changes something takes anidempotencyKey. The same key with the same input gives the first answer again and never does the work twice. Use a new key for each new request, and the same key only to retry it. The same key with a different input answers idempotency_conflict. Operations that go live or move money require a key, such as store.publish, store.release and the pricing changes.
Jobs
Long work answersrunning with a job, and a request for approval answers needs_approval with one. Generating 3D, video and motion always answers with a job. A job id starts with its kind, such as gen:, apr:, upload: or op:.
A job ends
done (with its result), failed, cancelled, declined, expired or stale. While it waits for approval, its state is awaiting_approval.
3.x tool names
Every 3.x tool name keeps working for all of 4.x:summer_call accepts it as the op and runs the operation that replaced it. If a 3.x call’s arguments now belong to another operation, the answer is moved, and its next has the exact new call. The old-to-new table: 3.x tool names.
The versions of Summer in the ChatGPT and Claude app directories keep their 3.x tools. See Summer in ChatGPT and Claude.
More
Operations reference
Every operation, its input, its answer and an example call
Agent permissions
What your agent may do without asking, and approvals
MCP setup
The hosted URL, and the npm MCP for engine work
CLI reference
Every command, and operations from the shell
MCP overview · MCP setup

