Skip to main content
This page is for the agent and for the person who drives it. It has the build loop, the three mistakes that break apps, and prompts that work.

Connect your agent

The apps.* operations are in the Summer Engine MCP. Your agent runs each with summer_call: {"op": "apps.create", "input": {...}}. summer_search "summer app" lists them with their inputs. Every input: Summer Apps operations. Connect your agent in one of the two ways below. Or describe the app to Summer in Studio chat: Build a new app in Studio > Apps and Edit with agent on an app page open it.
Add https://mcp.summerengine.com/mcp to your agent and sign in to your Summer account once. Nothing to install. Claude Code: claude mcp add --transport http summer https://mcp.summerengine.com/mcp, then /mcp and sign in. Claude and ChatGPT: add it as a custom connector. Step by step: Connect your agent.Use the custom connector, not the versions of Summer made for the ChatGPT and Claude app directories: those do not have Summer Apps.

The loop

1

Read the guide

apps.guide returns Markdown. Without a section it returns overview: when to build an app, layout or code, the loop and the rules. Read it first. Then read what the app needs: examples starts with a complete working app; sdk, manifest and kit have every call, field and component; design has the look; layout the layout format; types the SDK’s TypeScript types. all returns every section except types at once, about 100,000 characters: raise maxCharacters (default 24,000) or the answer is cut and says truncated. Load the summer-apps and summer-apps-design skills when you have them.
2

Create the app

apps.create { name, purpose, format }. format is code (default) or layout. The answer has the new appId. The person’s open Studio tab moves to the new app. If the answer has studio.reason: "no_tab", no Studio tab was open: give the person the link /studio/apps/<appId>.
3

Write and publish

Write index.html and app.js (and CSS if you need it), then apps.publish { appId, files, manifest, note }. With the npm package, apps.publish_folder publishes a local folder instead. Each publish is a new, immutable version. A publish error names the file or the rule: fix it and publish again. A publish that goes through can still answer checks: SDK calls whose permission the manifest lacks, and summer.agent.send events or summer.agent.tool tools the manifest does not declare. Those fail when the app runs. Fix them and publish again.
4

Seed data

If the app should start with content, write it with apps.write_data and "as": "seed". Seed rows belong to the team and show no author.
5

Look at it

apps.screenshot { appId }, then again with width: 390 (a phone) and theme: "dark". To see a dialog or a second state, add steps. Fix every error, console line and refused call it reports, publish, and look again. Repeat until it is clean.
6

Listen

apps.events { appId, after, timeoutSeconds } waits up to 50 seconds for what the app sends (summer.agent.send), errors (uncaught ones and console.error lines) and the team’s feedback. Pass the returned cursor as after next time.
7

Change it, keep it or archive it

To change the app, apps.get { appId } returns the current files and manifest. Edit them and publish again. To change only data, use apps.write_data; no publish needed. When the team keeps the app, apps.update { appId, status: "kept" }. Archive throwaway apps when you are done: apps.update { appId, status: "archived" }.
Before step 2, check whether Summer already does the job: the asset library’s collections and groups, Pick one and sound choices, Grow dashboards, Team. If it does, use that. If an app needs something the SDK lacks, report it with apps.report_gap.

Three things that break apps

  1. The SDK and kit load as ES modules from root paths. The app is served from its own host, apps.summerengine.app:
    Any other path, a CDN copy or a local copy does not connect. The screenshot then shows connected: false.
  2. await summer.ready before the first call. It resolves when Studio connects the app. Outside Summer Studio it never resolves, so opening index.html on its own shows nothing. There is no offline host; do not mock the SDK.
  3. Shared data goes through summer.data.collection(name). Use .list(), .get(id), .put(id, data), .patch(id, partial), .remove(id) and .subscribe(fn). There is no summer.data.list(name); it rejects with invalid.
Also: the app runs in a sandbox with no cookies, no localStorage and no network. Keep state in shared data. Add the data permission to the manifest, or every data call rejects with permission_missing.

Catch mistakes before you publish

Save the SDK types from /summer-sdk/v1.d.ts (or apps.guide section types) as summer-sdk.d.ts in the folder above your app folder, and start app.js with:
Your editor, or tsc --checkJs --noEmit, now reports a wrong method name, a missing argument or a wrong result field. Keep the .d.ts file out of the app folder: .ts is not an app file type, so a publish with it fails.

Look at it: apps.screenshot

Summer renders the published app headless, as the person and with their data, and returns the picture (image) plus a report. The report: To see the edit dialog of an app whose table rows open one, click the first row before the capture:
For a button the app declared with summer.page.declare, { "press": "<action id>" } works the same way. The screenshot is read-only. Reads run as the person (data, assets, team, projects, Grow, choices, engine status). Writes, paid calls and other engine calls are refused with invalid; events and notices are recorded, not delivered. They all work in Studio. To see data in a screenshot, seed it first with apps.write_data. A screenshot before the first publish fails with not_found. The SDK also reports an app’s console.error lines to apps.events as error events, so errors the app catches and logs reach you after the person uses it.

Prompts that work

Build a team tool. Your agent builds, publishes, seeds and checks a Summer App.

Change an app. Your agent edits the files and publishes a new version.

Edit the data. Your agent changes records; everyone with the app open sees it live.

Fix what the team reports. Your agent reads errors and feedback and fixes the app.

Worked examples: Apps for game teams.