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: Phase 1, live at https://mcp.dreamboothstudio.com/mcp. Streamable HTTP + stdio, eight read-only tools, two that create something (a third is flag-gated, see below), and account connection through the Studio's existing OAuth device flow. Listed in the official MCP Registry as com.dreamboothstudio/dreambooth v0.1.0.

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. That asymmetry is the reason the two write tools are registered only on the OAuth path; 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. 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 write tools exist only on the OAuth path, and 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.

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:

Read the full README on GitHub →