{
  "markdown": "# dreambooth-mcp\n\nMCP server for Dreambooth Studio. Lets ChatGPT, Claude and Gemini answer an\noperator's questions about their own booths — \"how did my Bandung booth do this\nweek?\" — by wrapping the Studio API the dashboard already uses.\n\n**Status: live at `https://mcp.dreamboothstudio.com/mcp`** (server `0.3.0`).\nStreamable HTTP + stdio, **23 tools** — 13 read-only, 9 that create or edit\nsomething, and `connect_account`. Listed in the official MCP Registry as\n[`com.dreamboothstudio/dreambooth`](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.dreamboothstudio/dreambooth)\nv0.1.0 (registry versions are immutable, so that entry stays at 0.1.0).\n\n**Ten tools are always registered**, on stdio and on every HTTP session:\n\n| | |\n|---|---|\n| `connect_account` | starts the device flow |\n| read | `connection_status` · `get_sessions` · `get_gallery_stats` · `search_docs` |\n| read | `list_projects` · `get_project` · `get_revenue_summary` · `get_credits` · `get_wallet_transactions` |\n\n`session_info` is an eleventh, registered only when `MCP_DIAGNOSTICS=1`.\n\n**Twelve more appear only on an OAuth session** (see the gate below):\n\n| | |\n|---|---|\n| creates | `create_booth` · `start_booth` · `refine_booth` · `create_filter` · `duplicate_project` |\n| creates | `start_frame` · `refine_frame` · `save_frame` |\n| edits | `update_booth_draft` |\n| read | `get_booth_draft` · `check_generation` · `preview_filter` |\n\nPhase 3 hardening has since **landed**, on the OAuth path: the Studio runs a\nfull OAuth 2.1 authorization server — PKCE S256 only, one-hour access tokens,\n30-day refresh, dynamic client registration, RFC 8707 resource audience,\nRFC 7009 revocation, and a CSRF-bound consent screen that names the scopes\nbeing granted. This server is a protected resource in front of it (RFC 9728).\nBoth discovery documents are live.\n\nThe **device flow is the older path and keeps the older properties** — its\ntoken is a year long, unscoped and unrevocable. That asymmetry is the whole\ngate: the twelve tools above are registered only when the session carries a\nbearer token (`session.bearerAuth`), so on stdio and on a device-flow session a\nmodel cannot promise something the Studio would refuse. There is **no feature\nflag** in this — an earlier version of this README described one, and it was\nremoved; deploy order is what guards a new tool. The gate checks for a token,\nnot for its scope: a read-scoped OAuth connection still *sees* the write tools\nand gets a 403 on calling one, with a sentence naming the fix. See\n[Connecting an account](#connecting-an-account).\n\nDesign: [`docs/dreambooth-mcp-design.md`](../dreambooth-prod/docs/dreambooth-mcp-design.md)\nin the Studio repo. Inline cards in ChatGPT:\n[`docs/apps-sdk-widgets-plan.md`](docs/apps-sdk-widgets-plan.md).\n\n---\n\n## What it does not do\n\nThis service holds **no database, no business logic, and no aggregations**. Every\ntool wraps a route the Studio already exposes, so there is exactly one\nimplementation of \"what is this operator's revenue\" and it lives in the Studio.\nThe moment an aggregation is copied in here, it becomes a second source of truth\nthat drifts silently — which is how you end up with three different revenue\nnumbers and no way to tell which is right.\n\nAlso permanently out of scope: withdrawals, payout accounts, MFA/step-up,\nsubscription token regeneration, and anything under `/api/admin`.\n\n## Run it\n\n```bash\nnpm install\ncp .env.example .env\n\nnpm run dev               # Streamable HTTP on PORT (default 8080)\nnpm run dev:stdio         # stdio, for Claude Desktop\n\nnpm run build\nnpm run inspect           # stdio smoke: handshake, tools/list, widgets, every tool\nnpm run inspect:http      # HTTP smoke: sessions, isolation, unknown-session 404\nnpm run preview           # writes each widget state to .preview/ to open in a browser\n```\n\n`inspect:http` runs `dist/`, so `npm run build` first or you are testing the last\nbuild rather than your change.\n\nBoth smokes run without a token. `search_docs` needs no auth, and the authed\ntools must come back with a readable message naming `connect_account` rather\nthan crashing — that failure path is part of what the checks verify.\n\n## Connecting an account\n\n**There is no token to configure, in either transport.** The operator asks their\nassistant to connect; `connect_account` starts the device flow the Studio\nalready runs for the Electron booth and returns a Google link for them to open.\nThe tool returns immediately and polls in the background — a tool call that\nblocks for minutes reads as a hung server to every MCP client, and by the time\nthey ask their next question the token is in place.\n\nThat includes local development. A pasted token would be a session-equivalent\ncredential (one year, no scopes, no revocation) sitting in a file on disk, and\nin HTTP mode it would authenticate every incoming session as that one account.\nApproving in a browser after a restart takes about fifteen seconds; that is the\nwhole cost of not having it.\n\nDevice-flow tokens are held **in memory, per MCP session**. A restart means\neveryone reconnects, which is the right trade for that path: there is no\ncredential store to protect. The token itself is session-equivalent — one year,\nno scopes, no revocation — and that has not changed.\n\nWhat changed is that it is no longer the only way in. A client that arrives\nwith its own `Authorization: Bearer` is on the **OAuth path**, where the token\nexpires in an hour, carries a scope the operator approved by name, and can be\nrevoked at `/api/oauth/revoke`. Nothing is stored here on that path at all: the\ncredential belongs to the request that carried it and is never written into a\nsession, where a later request quoting the same session id could read it.\n\nThe two credentials are deliberately **not** equivalent in what they may do. The\nwrite tools exist only on the OAuth path, and the Studio refuses a non-GET from\na device-flow token on any route that opted into connector writes — the weaker\ncredential must not inherit access granted to the stronger one. Everything the\nbooth fleet POSTs with that token is untouched.\n\nReading is unchanged on both: a session that never connects an account can read\nnothing but `search_docs`.\n\n## Deploy\n\nRailway, following the `dreambooth-whatsapp` recipe: `railway.json` with\n`npm run build` / `npm start`, healthcheck on `/health`, restart ON_FAILURE. No\nDockerfile, no CI, and no volume — this service is stateless.\n\nSet `DREAMBOOTH_API_URL` and `ALLOWED_HOSTS`. There is no token to configure.\nLeave `MCP_DIAGNOSTICS` unset in production — see the tools section.\n`OPENAI_APPS_CHALLENGE` is set only while a directory submission is in flight —\nsee [`docs/chatgpt-listing.md`](docs/chatgpt-listing.md).\n\n`ALLOWED_HOSTS` must list **both** public hostnames:\n\n```\nALLOWED_HOSTS=mcp.dreamboothstudio.com,dreambooth-mcp-production.up.railway.app\n```\n\nRailway keeps serving its generated hostname after a custom domain is attached,\nand DNS-rebinding protection is an allow-list, not a filter — naming only one\nhost makes the other return 400 on `/mcp`. `/health` keeps answering `ok` either\nway, because it is registered ahead of the transport, so the healthcheck cannot\ntell you this broke. Leaving the variable empty disables the protection entirely\nrather than allowing everything through some safer path.\n\n### Publishing to the registry\n\n`server.json` is the registry manifest. **Entries cannot be unpublished and each\nversion is immutable** — a changed URL or a fixed typo means publishing a new\n`version`, never editing the old one.\n\n```bash\n./mcp-publisher validate server.json    # checks against the live registry, publishes nothing\n./mcp-publisher login dns --domain dreamboothstudio.com --private-key \"$(openssl pkey -in key.pem -noout -text | grep -A3 priv: | tail -n +2 | tr -d ' :\\n')\"\n./mcp-publisher publish\n```\n\nAlways `validate` first; it is the only step in that sequence you can take back.\n\nThe `com.dreamboothstudio` namespace is proved by a TXT record on the **apex**\n(`dreamboothstudio.com`, not the `mcp` subdomain), signed by `key.pem`. That file\nis gitignored and lives on one machine. Losing it is recoverable — generate a new\nEd25519 pair and replace the TXT record. Leaking it is not: this repo is public,\nand whoever holds it can publish under `com.dreamboothstudio/*` permanently.\n\n### Connecting a client\n\nThe hosted server needs no install. In any client that accepts a remote MCP\nserver, point it at:\n\n```\nhttps://mcp.dreamboothstudio.com/mcp\n```\n\n### Claude Desktop\n\nFor running a local checkout — against a preview Studio, or a branch. To use the\ndeployed server, add the URL above instead; there is nothing to clone.\n\nAdd to `claude_desktop_config.json`. `--stdio` is required — the entry point\ndefaults to HTTP, and without it Claude Desktop starts a web server and waits\nforever for a reply on stdin.\n\n```json\n{\n  \"mcpServers\": {\n    \"dreambooth\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"src/index.ts\", \"--stdio\"],\n      \"cwd\": \"/absolute/path/to/dreambooth-mcp\",\n      \"env\": { \"DREAMBOOTH_API_URL\": \"https://dreamboothstudio.com\" }\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Wraps | Auth |\n|---|---|---|\n| `get_sessions` | `GET /api/sessions` | Bearer |\n| `get_gallery_stats` | `GET /api/gallery` | Bearer |\n| `search_docs` | `/docs-search-index-{locale}.json` | none |\n| `list_projects` | `GET /api/projects` | Bearer |\n| `get_project` | `GET /api/projects?id=` + `GET /api/device-monitoring` | Bearer |\n| `get_revenue_summary` | `GET /api/me/revenue-summary` | Bearer |\n| `get_credits` | `GET /api/credits` | Bearer |\n| `get_wallet_transactions` | `GET /api/wallet-transactions` | Bearer |\n\nThat is the complete read set. Two more wrap a route that creates something:\n\n| Tool | Wraps | Auth |\n|---|---|---|\n| `create_filter` | `POST /api/filters` | Bearer + `booths:write` |\n| `duplicate_project` | `POST /api/projects?duplicate` | Bearer + `booths:write` |\n| `start_frame` | `POST /api/ai/frames/start`, then `POST /api/ai/threads/{id}/messages` | Bearer + `booths:write` |\n| `refine_frame` | `POST /api/ai/threads/{id}/messages` | Bearer + `booths:write` |\n| `check_generation` | nothing — reads this process | Bearer |\n| `save_frame` | `POST /api/ai/frames/from-generation` | Bearer + `booths:write` |\n| `preview_filter` | `GET /api/filters/preview` | Bearer (read is enough) |\n| `start_booth` | `POST /api/onboarding/generate` | Bearer + `booths:write` |\n| `refine_booth` | `POST /api/onboarding/generate` (regen, or a rebuild) | Bearer + `booths:write` |\n| `create_booth` | `GET /api/onboarding/draft` → `GET by-slug?checkOnly` → `POST /api/onboarding/draft-frames` → `GET /api/onboarding/frames` + `/catalog` (+ `/api/ai-effects/catalog`) → `POST /api/projects/onboarding` → `GET by-slug` | Bearer + `booths:write` |\n| `get_booth_draft` | `GET /api/onboarding/draft` | Bearer (read is enough) |\n| `update_booth_draft` | `PATCH /api/onboarding/draft` (+ `/api/ai-effects/catalog` when an effect is named) | Bearer + `booths:write` |\n\n> **Deploy order matters for the frame and booth tools.** They are listed\n> unconditionally — there is no flag — and they call Studio routes that are\n> new or newly opened to OAuth: `/api/ai/frames/start`,\n> `/api/ai/frames/from-generation`, `/api/ai/threads/{id}/messages`,\n> `/api/onboarding/generate`, `/api/onboarding/draft-frames`,\n> `/api/projects/onboarding`, `/api/filters/preview`. Deploy that Studio change\n> before a build of this server that carries the tools, or the tools answer\n> with a sentence saying the Studio is not updated yet. Booth generation also\n> needs the Studio's `digital_mode` feature to be live (it is the /new pipeline;\n> when dormant, the booth tools say so). `oauth-write-check.mjs` in the\n> mcp-verify skill runs a real round — add `--booth` for the booth one — run it\n> once after both are live.\n\nFrame generation is the one flow here that is neither a single call nor a\nsingle answer. An image-model round trip runs 30–90 seconds against a\n15-second request timeout in this service, and raising the timeout would not\nhelp: a tool call that blocks that long reads as a hung server to every MCP\nclient. So `start_frame` and `refine_frame` start the work and return a job\nid, and `check_generation` reports — the shape `connect_account` already uses\nfor the device flow. And one prompt rarely lands, so the flow is the\ndashboard's Frame Studio thread: `start_frame` opens a thread on a blank\ntemplate and makes the first version, `refine_frame` makes the next one in\nthe same thread (\"darker\", \"less ornament\"), and only `save_frame` turns the\ngeneration the operator chose into a frame in their list. Until then\n**nothing is saved**, and the tool descriptions, the results and the preview\ncard all say so rather than leaving a model to guess. Every generation spends\npart of the account's free daily allowance, which is why the descriptions tell\nthe model never to iterate on its own initiative.\n\n**Booths follow the same shape**, through the `/new` onboarding pipeline — the\nStudio designs a whole booth from a sentence (spec, welcome screens for phone\nand laptop, in-booth background) and creates it. `start_booth` makes a DRAFT\n(a `draftId`, 60–120 s, a background job); `refine_booth` redraws the welcome\nscreen or the in-booth background from an instruction, or rebuilds the whole\ndraft from a new description; `update_booth_draft` changes what a redraw\ncannot — title, link name, button text, colours, capture mode, language, which\nframes and filters it carries, its AI effect, and the page settings the\ndashboard editor offers (photo count, countdown, timeouts, GIF/recording,\nretake, checkout, payment, result) — stored on the draft and applied by the\nStudio at create; `get_booth_draft` reads the draft back once the job store has\nforgotten it (drafts live 7 days); `create_booth` is the only step that makes a\nbooth — it checks the link name first, draws the booth's own three frames,\npicks three starter frames and the Studio's default filter the way /new does,\nand creates the booth with the draft's design, theme and capture mode. The\ndraft id is a plain value the model keeps, so a conversation outlives this\nprocess; drafts last seven days in the Studio. Quotas are the Studio's: 3 full\ngenerations and 5 redraws per draft, 10 drafts an hour per account. There is\nno spec-patch path — title, headline, colours change only through a redraw or\na rebuild; title and link name are chosen at create time.\n\n**Filters** are previewed before they exist: `preview_filter` asks the Studio\nto bake its sample photo (or the operator's own preview photo) through the\nbooth's real filter pipeline and returns a URL; `create_filter` saves the same\nadjustments. The preview shows 13 of the 31 adjustments and says which it\ncannot — the booth applies all of them.\n\nJobs live in this process, keyed by a hash of the bearer that started them —\nnever the bearer itself, which would mean holding operator credentials for as\nlong as the jobs. A restart loses running jobs and the poll says so, pointing\nat the dashboard rather than reporting a failure that may not have happened.\n**Running a second instance would break polling**; the fix at that point is a\nshared store.\n\nIt generates onto the Studio's blank templates (`layout` + `shape`, resolved\nserver-side), never at a width, a height or a photo window the model chose.\n`drawParams` is the contract the booth prints against, and invented geometry\nproduces a frame that is created successfully and prints wrong — a failure\nthat reports nothing. The saved frame's photo windows are keyed transparent by\nthe same server code the /new onboarding flow uses.\n\n**They are registered only when the request carries its own bearer token** —\nthat is, on the OAuth path. On stdio, and on a device-flow HTTP session, they\ndo not appear in `tools/list` at all. Writing requires a credential that\nexpires in an hour, carries a scope and can be revoked; the device flow's token\nis one year, unscoped and unrevocable, and must not inherit access granted to\nthe other one. The Studio enforces the same rule independently — see\n`utils/resolveAuthSession.ts` there, and [`docs/write-tools-plan.md`](docs/write-tools-plan.md)\nfor why the gate here cannot check the scope itself.\n\nNothing deletes and nothing touches money. There is no `put` or `delete` on\n`StudioClient`; the Studio opened exactly eight POST handlers to it —\n`/api/filters`, `/api/projects`, `/api/projects/onboarding`,\n`/api/onboarding/generate`, `/api/onboarding/draft-frames`,\n`/api/ai/frames/start`, `/api/ai/frames/from-generation`, and\n`/api/ai/threads/{id}/messages`.\n\nOne thing **does** edit: `update_booth_draft` PATCHes `/api/onboarding/draft`,\nthe single `patch` on `StudioClient`. It changes a draft that has not become a\nbooth yet — drafts live 7 days and `create_booth` is still the only step that\nmakes a real booth — but \"nothing edits\" stopped being true when it shipped.\n\nTwo tools wrap nothing:\n`connection_status` (is this session authenticated — polled by the connect card)\nand `session_info` (diagnostics, **temporary**, and registered only when\n`MCP_DIAGNOSTICS=1`; delete it once the session-continuity question in the\nwidgets plan is answered).\n\nEvery tool carries a `title`, an `outputSchema`, and explicit `readOnlyHint` /\n`destructiveHint` / `openWorldHint` annotations. That is not decoration: both\nthe Anthropic Connectors Directory and the ChatGPT plugin directory flag a tool\nthat is missing any of them, and `session_info` is gated off by default because\na listing is judged on its tool list and that one answers nothing an operator\nasked.\n\nOutput schemas are deliberately **permissive** — every field the Studio owns is\noptional. The SDK validates `structuredContent` against the schema and throws\n`McpError` on a mismatch, which is a protocol error, and rule 5 below exists to\nprevent exactly that. A Studio rename must degrade to a missing key, never to a\nbroken tool.\n\n## Inline cards (ChatGPT)\n\n`connect_account` renders a real card — a Google button that notices when the\noperator has finished approving — instead of a URL they have to copy. It is an\nMCP resource (`ui://widget/connect-account.html`) pointed at by `_meta` on the\ntool, per the Apps SDK.\n\n`duplicate_project` renders a second card, `ui://widget/write-result.html`. It\nrenders the result and nothing else: the copy's name, what it was copied from,\nand a link to it in the dashboard. There is no confirmation card and no form —\na widget only renders after the tool has already written, so confirming would\nneed a second tool that writes nothing, and the host's own approval dialog is\nthe real gate. There is no \"undo\" button either: undo means PUT or DELETE,\nwhich would widen the scope from \"create\" to \"change and delete\" for one\nbutton. Its CSP names no origin at all, which is what makes it impossible for\nit to talk to the network.\n\n**Everything generated renders in a third card**, `ui://widget/generation.html`\n— the one card whose CSP names an origin, because it shows images from the\nStudio's storage. From the moment a thing is asked for to the moment it\nexists:\n\n- `start_frame` / `refine_frame` / `start_booth` / `refine_booth` /\n  `create_booth` return while the work runs, and their card is **live**: a\n  skeleton of the thing being made (a strip with its photo windows, a phone\n  with a welcome screen) that polls `check_generation` from inside the iframe\n  every few seconds and redraws as the preview when the work is done — the\n  operator watches it appear. `check_generation` is widget-accessible for\n  exactly that; a host without `callTool` just leaves the card at \"working\".\n- `check_generation` shows the preview (frame image; booth draft with its\n  welcome screen and palette; created booth with its thumbnail and links).\n  `get_booth_draft` and `update_booth_draft` render the same draft card, with\n  what was set and what could not be applied named on it.\n- `save_frame` shows the saved frame's thumbnail; `create_filter` shows the\n  created filter on the Studio's sample photo (the same render `preview_filter`\n  shows, fetched after the save — best-effort); `preview_filter` shows the\n  preview and names the adjustments it cannot show.\n\nLeaving a card goes through the host. Every `https` link in a card is routed\nthrough `window.openai.openExternal` (where the host has no such API the anchor\nkeeps its own `target=\"_blank\"`), and once the thing exists the whole card is the\nlink: a created booth opens its public link, a saved frame, a created filter or\na duplicated booth opens the dashboard. Drafts, previews and live cards are\ndeliberately not links — nothing exists yet to open.\n\nNothing about this changes other clients. Every tool result carries the payload\ntwice: `structuredContent` for widgets, and the same object pretty-printed as\ntext `content` for Claude and Gemini, which render no widget. The text block is\nwhat it always was.\n\nWidgets are self-contained HTML with an **empty CSP on both domain lists**. That\nis load-bearing: a card that cannot reach the network cannot leak the operator's\nsession token, and it never needs to, because all of its data arrives through\n`callTool` on the server side. Keep it that way — inline any asset you need.\n\nDesign tokens are copied by hand into `src/ui/tokens.ts` from the Studio's\n`tailwind.config.js`, because a sandboxed iframe has no Tailwind. That makes it a\nsecond copy of the design system; when a brand colour moves, it moves there too.\n\n`get_project` reports `livenessTier`, not the device's `isOnline` field.\n`isOnline` is retained only for back-compat and collapses \"quiet because it was\ndeliberately shut down\" into \"offline\" — which is how a healthy fleet gets\nreported as broken.\n\nThe first three needed no Studio change at all. The rest depend on Studio\nwork that has now landed: `GET` on `/api/projects`, `/api/credits` and\n`/api/wallet-transactions` accepts `Authorization: Bearer` via\n`resolveAuthSession` (PUT and DELETE deliberately still do not, and POST only\non the two routes named above, only for a token carrying `booths:write`), and\n`GET /api/me/revenue-summary` is a new owner-scoped endpoint — `/api/analytics/revenue`\nis superadmin-gated and returns 403 to an operator.\n\n`get_wallet_transactions` and `get_revenue_summary` answer different questions\nand their descriptions say so. The wallet ledger excludes cash and voucher\nincome entirely, so for an operator who takes cash it understates real revenue —\na model that reports it as \"your earnings\" is confidently wrong.\n\n**Identity is never an argument.** No tool accepts a `userId` or `email` — the\noperator is resolved server-side from the token, exactly as `lib/ai-chat` does in\nthe Studio. A tool that needs such an argument is designed wrong.\n\n## Rules for adding a tool\n\n1. It wraps an existing Studio route. If no route fits, add a thin one in the\n   Studio — do not reimplement the query here.\n2. The description says **when to call it**, not just what it returns. The model\n   picks tools by description alone.\n3. Return the smallest useful shape. `get_gallery_stats` returns counts, not 12\n   media URLs, because the model does not need them and they cost context.\n4. Read-only tools carry `annotations: { readOnlyHint: true }` so clients can\n   auto-approve them. A write tool must not, and must also state\n   `idempotentHint` — `create_filter` says `false`, because calling it twice\n   makes two filters and a client that retries a timeout needs to know that.\n5. **`ownerEmail` is not an argument.** The Studio's POST handlers accept it for\n   the dashboard's collaborator path. A tool that forwards it hands the caller a\n   way to write into somebody else's account, so tool bodies are built field by\n   field rather than spread from `args`. The Studio refuses it from a bearer as\n   well; both halves are deliberate.\n6. Failures go back as `isError` content with a sentence the model can relay —\n   never a protocol error, which just makes clients retry. For a write, relay\n   the Studio's own message: \"this connection is read-only, reconnect and\n   approve permission to create things\" names the button to press.\n\n## Notes\n\n- **stdout is the transport.** A single `console.log` corrupts the stream and the\n  client drops the connection with a parse error. Diagnostics go to stderr.\n- Do not copy `dreambooth-whatsapp`'s habit of committing `.env`. Nothing secret\n  belongs in it here, and the surest way to keep that true is to never start.\n",
  "bytes": 24457,
  "sha": "f4276c231a23a4c01c724018bcc5a7acfd5b2bf2ca2913b6dbf92723ac8e985a",
  "repo_slug": "dreambooth-studio/dreambooth-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_dreamboothstudio_dreambooth_cae6b9db/readme"
}