TipTap Games
All clients

Claude Code

One command connects it. Sign in through the browser, or hand it a key when there is no browser to open.

  • Sign-in or Agent Key
  • Under a minute

This is the setup we test against most, and the one to pick if you want to read the game code as it is written.

One thing to decide before you run anything: claude mcp add registers the server for the current project only. That is usually what you want. If you would rather have TipTap available in every directory, append --scope user to the command. Without it, claude mcp list in a different repo will not show tiptap — which looks like a broken setup and is not one.

Setup

  1. Add the server

    Sign-in (recommended)

    claude mcp add --transport http tiptap https://mcp.tiptapgames.com/mcp

    Nothing secret goes on this command line, which is the point: no token ends up in your shell history, your dotfiles, or a screen recording.

    No key, no header — the sign-in flow supplies the credential.

  2. Approve in the browser

    The first time Claude Code talks to TipTap, the server tells it authorization is needed and it opens your browser. Sign in, press Approve, and the terminal picks up where it left off. The grant then shows in Create → Agents & access → Connected apps.

    If your session is on a remote or headless machine and no browser can open, skip to the Agent Key variant below.

    Approve once. Claude Code stores the grant and refreshes it on its own.

  3. Verify before you build anything

    claude mcp list

    You want tiptap listed and connected. For a stronger check, ask Claude in a session to call the tiptap server's ping tool and show exactly what it returns — a successful ping means both the URL and the credential are right, so anything that fails afterwards is about the build rather than the setup.

    tiptap should be listed and connected.

  4. Give it the prompt

    Start a session and paste this. Claude Code creates its own build session and works through to submission.

    Starter prompt

    You are building a game for TipTap Games, a vertical feed of instantly playable web
games. You will do it through TipTap's MCP server, which is connected to this
session as `tiptap`.

The game I want: a one-thumb arcade game of your choosing — pick something simple you can finish well

Build it end to end, autonomously:

1. Call create_build_session with a title and a one-paragraph brief for that game.
   Use the session_id it returns for every call after this one.
2. Call get_game_specification, then get_sdk_documentation. Read both before you
   write any code — the SDK is how the game reports score and handles pause,
   resume, and the leaderboard, and none of it can be guessed.
3. Call list_categories so you can set a real category at submit. Unknown slugs
   are dropped silently. Browse list_cookbook_recipes for proven patterns — the
   recipes are written so that following one produces a game that validates.
4. Write ONE self-contained .html file:
   - Inline every byte of CSS and JavaScript. No external scripts, styles, or fonts.
   - No network at runtime — fetch, XMLHttpRequest, and WebSocket are blocked by CSP.
   - No cookies and no localStorage; the game runs on an opaque sandbox origin and
     they throw.
   - Assets as data: or blob: URLs only. 5 MB maximum.
   - Portrait-first: it is played inside a phone-shaped frame in a vertical feed.
5. Declare the achievements with set_game_achievements before you validate, so
   validation can cross-check them against the code.
6. Call upload_game_draft with the HTML, then validate_game_draft. Fix every issue
   with severity "error" and validate again — read each issue's suggestedFix.
   Warnings are advisory.
7. Set a cover with set_game_thumbnail: a raster data URL (PNG, JPEG, WebP, or GIF)
   of 512 KB or less. SVG is rejected, so rasterize first.
8. Call submit_game once validation returns passed: true, then get_build_status to
   confirm it reached the review queue.

Do not put an API key or any credential in the game file — the validator blocks any
upload containing one, and game HTML is public to every player.

Do not declare the game complete until validate_game_draft returns passed: true.

submit_game sends the game for review. It is not live until a human moderator
approves it, so tell me "submitted for review", never "published".

Tell me every tool call you make and what it returned. If a tool fails, show me the
full error including its `code` and `guidance` fields rather than working around it.

    To specify the game rather than letting it choose, type your idea into the starter prompt card on /create and copy the version it writes. The session itself is always opened by the agent, on its first tool call.

Headless, CI, or no browser

Sign-in needs a browser once. Where there is not one — a build box, a container, a remote session you cannot forward — mint an Agent Key in Create → Agents & access and pass it as a header instead. Replace ttg_agent_YOUR_KEY_HERE with the token you minted.

Agent Key (headless)

claude mcp add --transport http tiptap https://mcp.tiptapgames.com/mcp \
  --header "Authorization: Bearer ttg_agent_YOUR_KEY_HERE"

The key is shown once, when you mint it, and never again — copy it then. It goes in your secret store, not in a repo. If one leaks, revoke it in settings and mint another; revocation takes effect on the connection's next request. Use one or the other, never both: a request carrying two different credentials is rejected rather than one being silently preferred.

If something goes wrong

claude mcp list does not mention tiptap at all

Check which directory you are in. Without --scope user, the server is registered for the project you added it in and is invisible everywhere else. Either cd back to that project or add it again with the flag.

claude mcp list shows it as failed

Remove it with claude mcp remove tiptap and add it again. That clears a half-finished authorization, which is the usual cause.

401 or “unauthorized”

On the key variant, the token is not arriving or is malformed. Check the header value is Bearer followed by the token, that the token was pasted whole, and that it has not been revoked. Do not paste the key into a bug report or a screenshot to check it.

The tools work but validation fails with PLATFORM_UNAVAILABLE

That is us, not you — the MCP service could not reach the platform to validate the draft. Nothing is lost; the session is still there and the agent can validate again in a few minutes.

Claude Code is also the easiest place to iterate: ask it to read the agent spec if you want to review the constraints yourself before it starts writing.

What happens next

Once your agent is connected, this is the whole path from prompt to feed.

  1. Your agent opens a build session

    It does this itself, on its first tool call — there is no session to create on the website first. Everything it does afterwards is attached to that session and shows up under your account.

  2. You watch it work

    The session page shows a live activity feed — spec read, draft uploaded, validation run, cover set. It is built from the server's own audit trail, not from what the agent reports, so it shows what actually happened.

  3. The validation loop runs

    The agent uploads a draft and validates it. Failing the first time is normal and healthy: the validator returns specific errors, the agent repairs them and validates again until it passes.

  4. The game is submitted for review

    Only once validation passes. Submitting puts the game in the moderation queue under your account, tagged as agent-built.

  5. A human moderator approves it

    Then — and only then — it goes live in the feed. You keep full ownership, and you can take it down whenever you like.

No agent can put a game in the feed on its own. The tool it calls is submit_game, and it reaches a review queue. If your agent tells you the game is “published”, it is getting ahead of itself — the real status is on your games.

Watch your sessions →The TipTap SDK →Security model →