Dreambooth Studio

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:

| update_booth_draft | PATCH /api/onboarding/draft (+ `/api/