> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations reference

> Every Summer operation an agent can run, generated from the operation catalog: what it does, whether it asks you first, its inputs, its answer and an example call.

Summer is the game engine built for AI. Everything your agent can do with Summer is an operation: one name such as `assets.generate_3d` or `store.publish`, one input, one answer. The hosted MCP, the npm MCP and the `summer` CLI all run the same 320 operations: 229 on Summer's servers and 91 on your computer.

<Note>
  Generated from the `summer-engine` npm package `4.2.0`: its public operation catalog (`registry/operations/public-catalog.json`) and its engine and local operations. If something here is wrong, the operation's definition is wrong.
</Note>

## Call an operation

| From | How |
| - | - |
| Hosted MCP, `https://mcp.summerengine.com/mcp` | The common jobs are their own tools (below). For anything else, `summer_search` finds the operation from the job in plain words and returns its exact input. Then `summer_call` runs it: `{"op": "pricing.set_base", "input": {...}}`. |
| npm MCP, `summer mcp` | Engine operations under their tool names, such as `summer_add_node` and `summer_play`, plus `summer_search` and `summer_call`. After `summer login` it runs every cloud operation too. |
| CLI | `summer <area> <action> --field value`, for example `summer assets search --query knight`. Add `--dry-run`, `--wait` or `--json`. `summer ops search <words>` finds an operation; `summer ops describe <name>` prints its input. |

Tools on the hosted MCP:

| Tool | Operation | What it does |
| - | - | - |
| `summer_whoami` | [`whoami`](/mcp/operations/account#whoami) | Show the signed-in Summer account: user id, the agent app, plan, credits and whether generation is unlocked. |
| `summer_docs_search` | [`docs.search`](/mcp/operations/docs#search) | Search Summer's own skills, Studio guides and docs pages by describing the task in plain words. |
| `summer_docs_read` | [`docs.read`](/mcp/operations/docs#read) | Read one Summer skill, Studio guide or docs page by its id from docs.search, as Markdown. |
| `summer_jobs_get` | [`jobs.get`](/mcp/operations/jobs#get) | Read one job once: its state (queued, running, awaiting\_approval, done, failed...), progress and, when done, its result. |
| `summer_jobs_wait` | [`jobs.wait`](/mcp/operations/jobs#wait) | Wait up to timeoutSeconds (at most 50) for a job to finish, then return it. |
| `summer_games_list` | [`games.list`](/mcp/operations/games#list) | List the person's games on Summer Games: game id, name, status, targets and store link, newest change first. |
| `summer_assets_search` | [`assets.search`](/mcp/operations/assets#search) | Search game assets: the Summer library (130k+), the person's own assets (scope mine; an empty query lists recent), or both. |
| `summer_assets_get` | [`assets.get`](/mcp/operations/assets#get) | Read one asset by id: title, type, status, file, download and viewer URLs, license, tags and its parent. |
| `summer_assets_generate_image` | [`assets.generate_image`](/mcp/operations/assets#generate_image) | Draw or edit an image with an AI model into the person's Summer assets. |
| `summer_assets_generate_3d` | [`assets.generate_3d`](/mcp/operations/assets#generate_3d) | Model a 3D asset from words, a picture or several views, optionally rigged and animated. |
| `summer_assets_generate_audio` | [`assets.generate_audio`](/mcp/operations/assets#generate_audio) | Make speech, a sound effect, music or a dialogue into the person's Summer assets. |
| `summer_analytics_summary` | [`analytics.summary`](/mcp/operations/analytics#summary) | One game's numbers for 7, 28 or 90 days: views, launches, sessions, play time, every day, top custom events, players and return, interest, sales, price and this month's event usage, with one reading. |
| `summer_pricing_get` | [`pricing.get`](/mcp/operations/pricing#get) | A game's price on Summer Games: the base price, any sale (now or scheduled), what players pay now and the prices set per country. |
| `summer_projects_list` | [`projects.list`](/mcp/operations/projects#list) | List the person's Summer projects, newest edit first: project id, name, kind (browser, cloud or desktop), share state and where it opens. |
| `summer_store_get_listing` | [`store.get_listing`](/mcp/operations/store#get_listing) | Read a game's store page as the store will show it: page state, targets, text per store, art per slot, price, the publish checklist (what is missing), publish requests and the tags a page can pick. |
| `summer_store_update_listing` | [`store.update_listing`](/mcp/operations/store#update_listing) | Edit the store page draft: title, targets, desktop and mobile text, tags, long description, support contact, release stage, content rating and other languages. |
| `summer_store_status` | [`store.status`](/mcp/operations/store#status) | Read where a game stands on Summer Games in one call: the review and its feedback, a publish request waiting for the owner, every upload and its checks, and what players get now on each platform. |
| `summer_store_publish` | [`store.publish`](/mcp/operations/store#publish) | Ask the owner to publish the store page draft with a build and price. |
| `summer_search` | [`ops.search`](/mcp/operations/ops#search) | Finds any operation by the job in plain words. |
| `summer_call` | | Runs any operation by name, with the same checks as its own tool. |

Tool names come from the operation: `games.list` is `summer_games_list`. Engine operations keep their 3.x names, and makers keep `summer_tool_<name>`. Every 3.x tool name still works: see [3.x tool names](/mcp/operations/legacy-names).

## The answer

Every operation answers one JSON shape. MCP sends it as text and as structured content; the CLI prints it with `--json`.

| `status` | Means | What the agent does next |
| - | - | - |
| `done` | Finished. `result` holds the answer. | Use `result`. |
| `running` | Long work started. `job.id` names it. | Call `jobs.wait` with the job id until it is done. |
| `needs_approval` | The change waits for your yes. Nothing has changed. | Give you `approval.url`, then call `jobs.wait` with the job id. |
| `dry_run` | A check only (`dryRun: true`). Nothing changed and nothing was spent. | Read `preview`: the changes, and for spend operations your estimated credits. |

An error answers `ok: false` with `error.code`, a plain `message`, exactly one `next` step and `retry` (`no`, `safe`, `same_key` or `after`).

Every operation that changes something also takes:

* `dryRun: true` to check the call and see what it would do. Nothing changes, nothing is spent and nothing is sent.
* `idempotencyKey` to retry safely: the same key with the same input gives the first answer again and never does the work twice. Operations that go live or move money require it.

## What your agent may do without asking

Studio shows six switches in **Settings > Agent permissions**. They apply to every app you connect. These defaults apply now. You can change them soon. Until then, Summer Games still asks the game's owner before an agent publishes, and price, A/B test and member changes ask you first. When a change asks, the operation answers `needs_approval` with a link, and your open Studio tab shows the request. Nothing changes until you approve. **Settings > Agent activity** lists what your agents did, with Undo for prices, sales, member roles, team names and the event limit.

| Permission | By default | Operations |
| - | - | - |
| Make and build | On: runs at once | 120 |
| Spend credits | On: runs at once | 51 |
| Publish | On: runs at once, except what Summer Games still asks for | 8 |
| Prices and live changes | On: runs at once, except what Summer Games still asks for | 9 |
| Delete for good | Off: asks you first | 18 |
| Contact people | Off: asks you first | 5 |
| Always asks | You approve each time | 5 |
| Reads | Never ask | 104 |

Spending never asks per call: agents spend within your credits and the monthly limit of your auto top-up. When credits run out, the answer is `no_credits` with a link to add credits.

## Errors

The list is closed: a new code is a new version of the catalog.

| `code` | When | `retry` |
| - | - | - |
| `invalid_input` | The input does not match the operation. details.path names the field. | `no` |
| `not_signed_in` | The operation needs a Summer sign-in and there is none. | `no` |
| `forbidden` | Signed in, but not allowed: not your game, or not a member. | `no` |
| `not_found` | The target does not exist or has expired. | `no` |
| `conflict` | The thing changed since it was read. Read it again, then retry. | `no` |
| `idempotency_conflict` | The same idempotencyKey was used with a different input. | `no` |
| `in_progress` | The first call with this idempotencyKey is still running. | `after` |
| `rate_limited` | Too many calls. details.retryAfterSeconds says when to try again. | `after` |
| `no_credits` | Not enough credits for this call. | `no` |
| `over_limit` | A plan or allowance limit was reached. | `no` |
| `engine_not_running` | An engine operation was called and no Summer Engine is open. | `safe` |
| `engine_lacks_op` | The open Summer Engine is too old for this operation. | `no` |
| `unsupported` | This server cannot run the operation (an engine operation on the hosted server). | `no` |
| `not_in_profile` | The operation exists, but this server version does not serve it. | `no` |
| `moved` | A 3.x tool was called with arguments that now belong to another operation. next has the exact new call. | `no` |
| `outcome_unknown` | The call may or may not have happened. Check with the read in next before retrying with the same key. | `same_key` |
| `unavailable` | A Summer service is down for a moment. | `after` |
| `internal` | A bug on Summer's side. The answer has a requestId for support. | `no` |

## Operations by area

| Area | Operations | What for |
| - | - | - |
| [Account](/mcp/operations/account) | 5 | Who is signed in, credits, agent permissions and auto top-up. |
| [Find operations](/mcp/operations/ops) | 2 | Find any operation by describing the job, and read its exact input. |
| [Jobs](/mcp/operations/jobs) | 4 | Long work and waiting for your approval: read, wait for, list and cancel jobs. |
| [Docs and skills](/mcp/operations/docs) | 5 | Summer's skills, templates, references and the engine class reference. |
| [Assets](/mcp/operations/assets) | 47 | Make, find, edit and upload images, 3D models, sound, music, voices, video and animation. |
| [Makers](/mcp/operations/makers) | 22 | One-shot creative recipes: trailers, ads, NPC voices, sprite sheets and more. |
| [Projects](/mcp/operations/projects) | 8 | Where a game is made: list, create, build and open projects. |
| [Plans](/mcp/operations/plans) | 27 | The game plan: look, characters, direction and the plan agent. |
| [Games](/mcp/operations/games) | 9 | Your games on Summer Games, and who works on them. |
| [Store and publishing](/mcp/operations/store) | 18 | A game's store page, uploads, publishing and releases. |
| [Jams](/mcp/operations/jams) | 3 | Summer Games Jams: list, enter and withdraw. |
| [Pricing](/mcp/operations/pricing) | 6 | What players pay: base price, country prices and sales. |
| [Analytics](/mcp/operations/analytics) | 7 | How your game is doing: views, launches, sessions, play time, events and funnels. |
| [A/B tests](/mcp/operations/experiments) | 6 | Create, start, stop and read A/B tests. |
| [Marketing](/mcp/operations/marketing) | 9 | Services Summer runs for a game, and the Content videos and brand pack. |
| [Teams](/mcp/operations/team) | 5 | Your teams: list, create, rename and invite. |
| [Profile](/mcp/operations/profile) | 6 | Your public profile and Studio settings. |
| [Summer Apps](/mcp/operations/apps) | 23 | Team tools that agents build inside Summer Studio. |
| [Studio](/mcp/operations/studio) | 6 | Move around Summer Studio: open pages, read the map and the page. |
| [Chats](/mcp/operations/chats) | 3 | Your Studio chats. |
| [Stories](/mcp/operations/stories) | 12 | The story builder: nodes, links, references and sharing. |
| [Plugins](/mcp/operations/plugins) | 2 | Plugins for desktop projects. |
| [Engine](/mcp/operations/engine) | 85 | The open project in Summer Engine and the running game: scenes, nodes, scripts, play, input and screenshots. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.