TipTap Games
All clients

Codex CLI

One command does the whole thing — Codex finds the authorization server itself, registers itself, and opens your browser to sign in.

  • Sign-in or Agent Key
  • Under a minute

Codex is the most self-sufficient client we support. You give codex mcp add a URL and nothing else; it fetches our metadata, works out that authorization is required, registers itself as a client, and starts the sign-in flow — all inside that one command. There is no separate login step to remember and no credential for you to handle.

The server goes into your Codex config at ~/.codex/config.toml, which means it is available in every directory. Unlike Claude Code there is no per-project scope to get wrong.

Setup

  1. Add the server

    Sign-in (recommended)

    codex mcp add tiptap --url 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 config file, or a screen recording. Codex proves it is the same client throughout with PKCE, so the code it receives at the end is useless to anything that intercepts it.

    One command. No key, no header, no separate login.

  2. Approve in the browser

    Your browser opens on a consent screen at tiptapgames.com. Sign in if you are not already, and press Approve.

    The screen will label the client an Unverified app and say it registered itself and chose its own name. That is expected — Codex registers dynamically rather than being an app we have on file, and the notice is telling you where the name came from rather than accusing Codex of anything. Check the address bar and that you started this yourself a moment ago, then approve.

    Check the address bar says tiptapgames.com before you approve.

  3. Expect to land on a local page, not on ours

    This is the step that surprises people. After you approve, the browser does not stay on tiptapgames.com — it is redirected to a small page served by Codex itself on your own machine, telling you authentication is complete. The address bar shows 127.0.0.1 and a port.

    That is the flow working, not a redirect that went wrong. Codex runs a one-off local listener to catch the authorization code, and that page is the listener saying it caught it. Close the tab and go back to your terminal.

    The connection now shows up in Create → Agents & access → Connected apps, with a revoke button that takes effect on the connection's very next request. Codex refreshes the grant on its own from here, so this is the only time you approve anything.

    127.0.0.1 in the address bar is correct here — that page is Codex's, not ours.

  4. Verify before you build anything

    codex mcp list
codex mcp get tiptap

    You want tiptap listed and enabled; codex mcp get tiptap shows the transport and URL it recorded. For a stronger check, start a session and ask Codex to call the tiptap server's ping tool and show exactly what it returns — a successful ping means the URL and the credential are both right, so anything that fails after that is about the build rather than the setup.

    tiptap should be listed and enabled.

  5. Give it the prompt

    Start a session and paste this. Codex 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. Either way the session is opened by the agent, on its first tool call — there is nothing to create on the website first.

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 point Codex at an environment variable holding it. Replace ttg_agent_YOUR_KEY_HERE with the token you minted.

Agent Key (headless)

export TIPTAP_AGENT_KEY="ttg_agent_YOUR_KEY_HERE"
# PowerShell: $env:TIPTAP_AGENT_KEY = "ttg_agent_YOUR_KEY_HERE"

codex mcp add tiptap --url https://mcp.tiptapgames.com/mcp \
  --bearer-token-env-var TIPTAP_AGENT_KEY

Note what that flag takes: the name of a variable, not the token. Codex records the name and reads the value at launch, so the key never lands in config.toml and never appears in the command you typed — better handling than most clients offer, and a reason to prefer this path in CI even though sign-in works too. The variable does have to be set in the environment Codex itself starts in; one exported in a different shell, or in a CI step that has already ended, gives you a 401 that looks exactly like a bad key.

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, and never into a game file. If one leaks, revoke it in Create → Agents & access and mint another; revocation takes effect on the connection's next request.

Use sign-in or a key, never both on one server entry. A request carrying two different credentials is rejected outright rather than one being silently preferred. If you already added the server the keyless way, run codex mcp remove tiptap before adding it again with the flag.

If something goes wrong

Authorization server response missing required issuer

A Codex regression, tracked upstream as openai/codex#31573 and open as of 30 July 2026. It affects any MCP server that advertises RFC 9207 support: Codex takes on the obligation to validate the iss parameter without reading it. Present in 0.143.0 and later; 0.141.0 predates it.

You should not meet it here. Our authorization server stopped advertising the guarantee while still sending iss on every authorization response, which is enough for Codex to complete the flow. If you do see it, you are pointed at a different server — or at a deploy of ours from before that change.

invalid_target: resource does not identify this server

This one was ours, and it is fixed. The MCP authorization spec says the resource indicator is the canonical URL the client connects to — /mcp included — and we used to accept only the bare origin. Both spellings are now accepted and both are advertised. If you are following an older error report, there is nothing to configure and you should not need --oauth-resource.

OAuth provider rejected discovered scopes. Retrying without scopes…

Harmless, and not a scope problem. Codex logs this when it meets an error it cannot attribute and guesses that scopes caused it — we have watched it do exactly that for a failure that had nothing to do with scopes. Scope on our side is a property of the server, not of a registration: what scopes_supported advertises is what any client may request, so a registration that asks for none is complete and loses nothing. Read the error after this line — that is the real one.

The browser opens, but the terminal never finishes

Codex is waiting on its local listener, so the browser has to be able to reach 127.0.0.1 on the machine running Codex. Over SSH without a forwarded port it never can. Either forward the port or use the Agent Key variant, which needs no browser at all.

401 or “unauthorized”

On the sign-in path, re-authorize with codex mcp login tiptap — or check the grant was not revoked in Create → Agents & access. On the key path the token is not arriving: confirm the variable is set in the environment Codex starts in, that you passed its name rather than its value, and that the key was pasted whole. Do not paste the key into a bug report or a screenshot to check it.

403 once the credential is working

Wrong hostname. Only the address in the command above is accepted for tool calls — check what codex mcp get tiptap recorded, and re-add the server if it is stale.

Something is stuck and you want a clean slate

codex mcp logout tiptap drops the stored authorization; codex mcp remove tiptap drops the whole server entry so you can add it again from scratch. That clears a half-finished authorization, which is the usual cause.

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.

Want to review the constraints before it starts writing? Ask Codex to read the agent spec first — it is the same document the get_game_specification tool returns.

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. It lands under Needs work

    Only once validation passes. The game is saved to your account as a draft, tagged as agent-built, under My games → Needs work. It is not in review and not in the feed — nobody but you can see it, and nobody has been asked to look at it.

  5. You play it and submit it

    This step is yours and cannot be done by an agent. Open My games in your Creator Studio, play the game, and submit it when you are happy. Submitting is where you accept the licence that lets us publish it, which is why it has to be you.

  6. A human moderator approves it

    Then — and only then — it goes live in the feed. The decision comes to you either way: a notification in the bell, and an email where enabled. You keep full ownership, and you can take it down whenever you like.

No agent can submit a game, let alone publish one. The tool it calls is submit_game — a name kept for compatibility — and it creates a draft. Sending that draft for review is a step only you can take, signed in, because it is where you accept the licence over your own work. If your agent says the game is “submitted” or “published”, it is getting ahead of itself; what is true is on My games.

Watch your sessions →The TipTap SDK →Security model →