dreambooth-mcp

MCP server for Dreambooth Studio. Lets ChatGPT, Claude and Gemini answer an operator's questions about their own booths — "how did my Bandung booth do this week?" — by wrapping the Studio API the dashboard already uses.

Status: live at https://mcp.dreamboothstudio.com/mcp (server 0.3.0). Streamable HTTP + stdio, 23 tools — 13 read-only, 9 that create or edit something, and connect_account. Listed in the official MCP Registry as com.dreamboothstudio/dreambooth v0.1.0 (registry versions are immutable, so that entry stays at 0.1.0).

Ten tools are always registered, on stdio and on every HTTP session:

session_info is an eleventh, registered only when MCP_DIAGNOSTICS=1.

Twelve more, listed on every connection (see below for what guards them):

Phase 3 hardening has since landed, on the OAuth path: the Studio runs a full OAuth 2.1 authorization server — PKCE S256 only, one-hour access tokens, 30-day refresh, dynamic client registration, RFC 8707 resource audience, RFC 7009 revocation, and a CSRF-bound consent screen that names the scopes being granted. This server is a protected resource in front of it (RFC 9728). Both discovery documents are live.

The device flow is the older path and keeps the older properties — its token is a year long, unscoped and unrevocable, so it must not be able to write. It cannot: the Studio refuses it with a 403 and a sentence naming the fix, exactly as it refuses a read-scoped OAuth token.

The tool list is the same on every connection. The twelve above used to be registered only when a request carried a bearer, which made tools/list answer 10 tools with no Authorization header and 22 with any string as one — the check was on the header's presence, not on anything in it. That is gone. An inventory that moves is unusable: the ChatGPT submission portal scans from the browser with no credential, so it could only ever see the read half while the submission declared all 22, and any client caching a pre-sign-in list keeps offering ten tools to an operator who has connected an account. What guards these tools now is what always decided the outcome anyway — AUTH_REQUIRED_TOOLS turns an uncredentialled call into the 401 that starts the OAuth flow, and the Studio's 403 answers a token without booths:write. There is no feature flag in this — an earlier version of this README described one, and it was removed; deploy order is what guards a new tool. See Connecting an account.

Design: docs/dreambooth-mcp-design.md in the Studio repo. Inline cards in ChatGPT: docs/apps-sdk-widgets-plan.md.

What it does not do

This service holds no database, no business logic, and no aggregations. Every tool wraps a route the Studio already exposes, so there is exactly one implementation of "what is this operator's revenue" and it lives in the Studio. The moment an aggregation is copied in here, it becomes a second source of truth that drifts silently — which is how you end up with three different revenue numbers and no way to tell which is right.

Also permanently out of scope: withdrawals, payout accounts, MFA/step-up, subscription token regeneration, and anything under /api/admin.

Run it

npm install
cp .env.example .env

npm run dev               # Streamable HTTP on PORT (default 8080)
npm run dev:stdio         # stdio, for Claude Desktop

npm run build
npm run inspect           # stdio smoke: handshake, tools/list, widgets, every tool
npm run inspect:http      # HTTP smoke: sessions, isolation, unknown-session 404
npm run preview           # writes each widget state to .preview/ to open in a browser

inspect:http runs dist/, so npm run build first or you are testing the last build rather than your change.

Both smokes run without a token. search_docs needs no auth, and the authed tools must come back with a readable message naming connect_account rather than crashing — that failure path is part of what the checks verify.

Connecting an account

There is no token to configure, in either transport. The operator asks their assistant to connect; connect_account starts the device flow the Studio already runs for the Electron booth and returns a Google link for them to open (Google only: the Studio builds an accounts.google.com URL). A client that signs in through its own connector settings (a request with no session and no credential) gets use_client_sign_in and no link instead; that sign-in is the Studio's login page, which takes an email and password as well as Google. The tool returns immediately and polls in the background — a tool call that blocks for minutes reads as a hung server to every MCP client, and by the time they ask their next question the token is in place.

That includes local development. A pasted token would be a session-equivalent credential (one year, no scopes, no revocation) sitting in a file on disk, and in HTTP mode it would authenticate every incoming session as that one account. Approving in a browser after a restart takes about fifteen seconds; that is the whole cost of not having it.

Device-flow tokens are held in memory, per MCP session. A restart means everyone reconnects, which is the right trade for that path: there is no credential store to protect. The token itself is session-equivalent — one year, no scopes, no revocation — and that has not changed.

What changed is that it is no longer the only way in. A client that arrives with its own Authorization: Bearer is on the OAuth path, where the token expires in an hour, carries a scope the operator approved by name, and can be revoked at /api/oauth/revoke. Nothing is stored here on that path at all: the credential belongs to the request that carried it and is never written into a session, where a later request quoting the same session id could read it.

The two credentials are deliberately not equivalent in what they may do. The Studio refuses a non-GET from a device-flow token on any route that opted into connector writes — the weaker credential must not inherit access granted to the stronger one. Everything the booth fleet POSTs with that token is untouched. The write tools are still listed on a device-flow session, because the tool list must not depend on the credential; calling one there returns the Studio's 403 and its sentence, which tells the operator what to do instead.

Reading is unchanged on both: a session that never connects an account can read nothing but search_docs.

Deploy

Railway, following the dreambooth-whatsapp recipe: railway.json with npm run build / npm start, healthcheck on /health, restart ON_FAILURE. No Dockerfile, no CI, and no volume — this service is stateless.

Set DREAMBOOTH_API_URL and ALLOWED_HOSTS. There is no token to configure. Leave MCP_DIAGNOSTICS unset in production — see the tools section. OPENAI_APPS_CHALLENGE is set only while a directory submission is in flight — see docs/chatgpt-listing.md.

ALLOWED_HOSTS must list both public hostnames:

ALLOWED_HOSTS=mcp.dreamboothstudio.com,dreambooth-mcp-production.up.railway.app

Railway keeps serving its generated hostname after a custom domain is attached, and DNS-rebinding protection is an allow-list, not a filter — naming only one host makes the other return 400 on /mcp. /health keeps answering ok either way, because it is registered ahead of the transport, so the healthcheck cannot tell you this broke. Leaving the variable empty disables the protection entirely rather than allowing everything through some safer path.

Publishing to the registry

server.json is the registry manifest. Entries cannot be unpublished and each version is immutable — a changed URL or a fixed typo means publishing a new version, never editing the old one.

./mcp-publisher validate server.json    # checks against the live registry, publishes nothing
./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')"
./mcp-publisher publish

Always validate first; it is the only step in that sequence you can take back.

The com.dreamboothstudio namespace is proved by a TXT record on the apex (dreamboothstudio.com, not the mcp subdomain), signed by key.pem. That file is gitignored and lives on one machine. Losing it is recoverable — generate a new Ed25519 pair and replace the TXT record. Leaking it is not: this repo is public, and whoever holds it can publish under com.dreamboothstudio/* permanently.

Connecting a client

The hosted server needs no install. In any client that accepts a remote MCP server, point it at:

https://mcp.dreamboothstudio.com/mcp

Claude Desktop

For running a local checkout — against a preview Studio, or a branch. To use the deployed server, add the URL above instead; there is nothing to clone.

Add to claude_desktop_config.json. --stdio is required — the entry point defaults to HTTP, and without it Claude Desktop starts a web server and waits forever for a reply on stdin.

{
  "mcpServers": {
    "dreambooth": {
      "command": "npx",
      "args": ["tsx", "src/index.ts", "--stdio"],
      "cwd": "/absolute/path/to/dreambooth-mcp",
      "env": { "DREAMBOOTH_API_URL": "https://dreamboothstudio.com" }
    }
  }
}

Tools

That is the complete read set. Two more wrap a route that creates something:

Deploy order matters for the frame and booth tools. They are listed unconditionally — there is no flag — and they call Studio routes that are new or newly opened to OAuth: /api/ai/frames/start, /api/ai/frames/from-generation, /api/ai/threads/{id}/messages, /api/onboarding/generate, /api/onboarding/draft-frames, /api/projects/onboarding, /api/filters/preview. Deploy that Studio change before a build of this server that carries the tools, or the tools answer with a sentence saying the Studio is not updated yet. Booth generation also needs the Studio's digital_mode feature to be live (it is the /new pipeline; when dormant, the booth tools say so). oauth-write-check.mjs in the mcp-verify skill runs a real round — add --booth for the booth one — run it once after both are live.

Frame generation is the one flow here that is neither a single call nor a single answer. An image-model round trip runs 30–90 seconds against a 15-second request timeout in this service, and raising the timeout would not help: a tool call that blocks that long reads as a hung server to every MCP client. So start_frame and refine_frame start the work and return a job id, and check_generation reports — the shape connect_account already uses for the device flow. And one prompt rarely lands, so the flow is the dashboard's Frame Studio thread: start_frame opens a thread on a blank template and makes the first version, refine_frame makes the next one in the same thread ("darker", "less ornament"), and only save_frame turns the generation the operator chose into a frame in their list. Until then nothing is saved, and the tool descriptions, the results and the preview card all say so rather than leaving a model to guess. Every generation spends part of the account's free daily allowance, which is why the descriptions tell the model never to iterate on its own initiative.

Booths follow the same shape, through the /new onboarding pipeline — the Studio designs a whole booth from a sentence (spec, welcome screens for phone and laptop, in-booth background) and creates it. start_booth makes a DRAFT (a draftId, 60–120 s, a background job); refine_booth redraws the welcome screen or the in-booth background from an instruction, or rebuilds the whole draft from a new description; update_booth_draft changes what a redraw cannot — title, link name, button text, colours, capture mode, language, which frames and filters it carries, its AI effect, and the page settings the dashboard editor offers (photo count, countdown, timeouts, GIF/recording, retake, checkout, payment, result) — stored on the draft and applied by the Studio at create; get_booth_draft reads the draft back once the job store has forgotten it (drafts live 7 days); create_booth is the only step that makes a booth — it checks the link name first, draws the booth's own three frames, picks three starter frames and the Studio's default filter the way /new does, and creates the booth with the draft's design, theme and capture mode. The draft id is a plain value the model keeps, so a conversation outlives this process; drafts last seven days in the Studio. Quotas are the Studio's: 3 full generations and 5 redraws per draft, 10 drafts an hour per account. There is no spec-patch path — title, headline, colours change only through a redraw or a rebuild; title and link name are chosen at create time.

Filters are previewed before they exist: preview_filter asks the Studio to bake its sample photo (or the operator's own preview photo) through the booth's real filter pipeline and returns a URL; create_filter saves the same adjustments. The preview shows 13 of the 31 adjustments and says which it cannot — the booth applies all of them.

Jobs live in this process, keyed by a hash of the bearer that started them — never the bearer itself, which would mean holding operator credentials for as long as the jobs. A restart loses running jobs and the poll says so, pointing at the dashboard rather than reporting a failure that may not have happened. Running a second instance would break polling; the fix at that point is a shared store.

It generates onto the Studio's blank templates (layout + shape, resolved server-side), never at a width, a height or a photo window the model chose. drawParams is the contract the booth prints against, and invented geometry produces a frame that is created successfully and prints wrong — a failure that reports nothing. The saved frame's photo windows are keyed transparent by the same server code the /new onboarding flow uses.

They are listed everywhere and usable only on the OAuth path. Writing requires a credential that expires in an hour, carries a scope and can be revoked; the device flow's token is one year, unscoped and unrevocable, and must not inherit access granted to the other one. That rule is enforced where it can actually be evaluated — by the Studio, which holds the key to the next-auth JWE this server cannot read a scope out of. See utils/resolveAuthSession.ts there, and docs/write-tools-plan.md. Until 2026-09-23 it was also approximated here, by registering these tools only when a request carried a bearer; that made the tool list depend on an HTTP header and was removed.

Nothing deletes and nothing touches money. There is no put or delete on StudioClient; the Studio opened exactly eight POST handlers to it — /api/filters, /api/projects, /api/projects/onboarding, /api/onboarding/generate, /api/onboarding/draft-frames, /api/ai/frames/start, /api/ai/frames/from-generation, and /api/ai/threads/{id}/messages.

One thing does edit: update_booth_draft PATCHes /api/onboarding/draft, the single patch on StudioClient. It changes a draft that has not become a booth yet — drafts live 7 days and create_booth is still the only step that makes a real booth — but "nothing edits" stopped being true when it shipped.

Two tools wrap nothing: connection_status (is this session authenticated — polled by the connect card) and session_info (diagnostics, temporary, and registered only when MCP_DIAGNOSTICS=1; delete it once the session-continuity question in the widgets plan is answered).

Every tool carries a title, an outputSchema, and explicit readOnlyHint / destructiveHint / openWorldHint annotations. That is not decoration: both the Anthropic Connectors Directory and the ChatGPT plugin directory flag a tool that is missing any of them, and session_info is gated off by default because a listing is judged on its tool list and that one answers nothing an operator asked.

Output schemas are deliberately permissive — every field the Studio owns is optional. The SDK validates structuredContent against the schema and throws McpError on a mismatch, which is a protocol error, and rule 5 below exists to prevent exactly that. A Studio rename must degrade to a missing key, never to a broken tool.

Inline cards (ChatGPT)

connect_account renders a real card — a Google button that notices when the operator has finished approving — instead of a URL they have to copy. It is an MCP resource (ui://widget/connect-account.html) pointed at by _meta on the tool, per the Apps SDK.

duplicate_project renders a second card, ui://widget/write-result.html. It renders the result and nothing else: the copy's name, what it was copied from, and a link to it in the dashboard. There is no confirmation card and no form — a widget only renders after the tool has already written, so confirming would need a second tool that writes nothing, and the host's own approval dialog is the real gate. There is no "undo" button either: undo means PUT or DELETE, which would widen the scope from "create" to "change and delete" for one button. Its CSP names no origin at all, which is what makes it impossible for it to talk to the network.

Everything generated renders in a third card, ui://widget/generation.html — the one card whose CSP names an origin, because it shows images from the Studio's storage. From the moment a thing is asked for to the moment it exists:

• start_frame / refine_frame / start_booth / refine_booth / create_booth return while the work runs, and their card is live: a skeleton of the thing being made (a strip with its photo windows, a phone with a welcome screen) that polls check_generation from inside the iframe every few seconds and redraws as the preview when the work is done — the operator watches it appear. check_generation is widget-accessible for exactly that; a host without callTool just leaves the card at "working".
• check_generation shows the preview (frame image; booth draft with its welcome screen and palette; created booth with its thumbnail and links). get_booth_draft and update_booth_draft render the same draft card, with what was set and what could not be applied named on it.
• save_frame shows the saved frame's thumbnail; create_filter shows the created filter on the Studio's sample photo (the same render preview_filter shows, fetched after the save — best-effort); preview_filter shows the preview and names the adjustments it cannot show.

Leaving a card goes through the host. Every https link in a card is routed through window.openai.openExternal (where the host has no such API the anchor keeps its own target="_blank"), and once the thing exists the whole card is the link: a created booth opens its public link, a saved frame, a created filter or a duplicated booth opens the dashboard. Drafts, previews and live cards are deliberately not links — nothing exists yet to open.

Nothing about this changes other clients. Every tool result carries the payload twice: structuredContent for widgets, and the same object pretty-printed as text content for Claude and Gemini, which render no widget. The text block is what it always was.

Widgets are self-contained HTML with an empty CSP on both domain lists. That is load-bearing: a card that cannot reach the network cannot leak the operator's session token, and it never needs to, because all of its data arrives through callTool on the server side. Keep it that way — inline any asset you need.

Design tokens are copied by hand into src/ui/tokens.ts from the Studio's tailwind.config.js, because a sandboxed iframe has no Tailwind. That makes it a second copy of the design system; when a brand colour moves, it moves there too.

get_project reports livenessTier, not the device's isOnline field. isOnline is retained only for back-compat and collapses "quiet because it was deliberately shut down" into "offline" — which is how a healthy fleet gets reported as broken.

The first three needed no Studio change at all. The rest depend on Studio work that has now landed: GET on /api/projects, /api/credits and /api/wallet-transactions accepts Authorization: Bearer via resolveAuthSession (PUT and DELETE deliberately still do not, and POST only on the two routes named above, only for a token carrying booths:write), and GET /api/me/revenue-summary is a new owner-scoped endpoint — /api/analytics/revenue is superadmin-gated and returns 403 to an operator.

get_wallet_transactions and get_revenue_summary answer different questions and their descriptions say so. The wallet ledger excludes cash and voucher income entirely, so for an operator who takes cash it understates real revenue — a model that reports it as "your earnings" is confidently wrong.

Identity is never an argument. No tool accepts a userId or email — the operator is resolved server-side from the token, exactly as lib/ai-chat does in the Studio. A tool that needs such an argument is designed wrong.

Rules for adding a tool

1. It wraps an existing Studio route. If no route fits, add a thin one in the Studio — do not reimplement the query here.
2. The description says when to call it, not just what it returns. The model picks tools by description alone.
3. Return the smallest useful shape. get_gallery_stats returns counts, not 12 media URLs, because the model does not need them and they cost context.
4. Read-only tools carry annotations: { readOnlyHint: true } so clients can auto-approve them. A write tool must not, and must also state idempotentHint — create_filter says false, because calling it twice makes two filters and a client that retries a timeout needs to know that.
5. ownerEmail is not an argument. The Studio's POST handlers accept it for the dashboard's collaborator path. A tool that forwards it hands the caller a way to write into somebody else's account, so tool bodies are built field by field rather than spread from args. The Studio refuses it from a bearer as well; both halves are deliberate.
6. Failures go back as isError content with a sentence the model can relay — never a protocol error, which just makes clients retry. For a write, relay the Studio's own message: "this connection is read-only, reconnect and approve permission to create things" names the button to press.

Notes

• stdout is the transport. A single console.log corrupts the stream and the client drops the connection with a parse error. Diagnostics go to stderr.
• Do not copy dreambooth-whatsapp's habit of committing .env. Nothing secret belongs in it here, and the surest way to keep that true is to never start.