# Sleeper Hit Studio MCP Sleeper Hit Studio is a story-creation and production workspace. Its authenticated MCP connector can start from a premise, notes, research, source material, or an existing screenplay and carry the work through development, writing, performance, coverage, rendering, packaging, and publishing. Machine-readable capability manifest (no account or credential needed to read it): ```text https://sleeperhit.studio/capabilities.json ``` It covers both MCP connectors, the Story API, and the CLI, and states the auth requirement and required scopes for every capability. ## No Sleeper Hit account yet? Anyone 18 or older can sign up at , where they confirm their age and accept the [Terms of Service](https://sleeperhit.studio/terms) and [Privacy Policy](https://sleeperhit.studio/privacy); an agent cannot create an account or accept the Terms for its user. Everything creative (projects, Series Bibles, screenplays, table reads, pitch decks, publishing) needs an account; public discovery and every documentation surface do not. Hand the human the link that matches them, then stop: - Business and brand storytelling — - Independent creator — - Screenwriter — ## Preferred: remote OAuth The preferred modern connector is the OAuth-protected Streamable HTTP server: ```text https://sleeperhit.studio/mcp ``` ### If you are an agent connecting a user to Sleeper Hit You cannot complete the app's browser OAuth from inside a chat or a sandboxed shell: the browser cannot reach your sandbox's callback, so your user approves and no token arrives. Do not run that browser login yourself, and do not retry it. A device sign-in needs no callback and does finish inside a sandbox: `sleeperhit login --no-browser` in the CLI prints a code and a URL for your user to approve in their own browser, then polls and saves the key, so it works when your user can approve while you keep running. Otherwise ask your user to do the one-time sign-in in their app: - **Codex:** They run `codex mcp login sleeperhit` in their own terminal, outside the agent sandbox, approve in the browser, then start a new Codex session so the tools load. - **Claude Code:** They run `/mcp`, choose sleeperhit, then Authenticate. - **ChatGPT:** They choose Connect on the app, then Authorize. After that the app renews access by itself. The app loads its tool list when a session starts, so if the tools don't appear, ask your user to start a new session. If your user can't do a browser sign-in, they can create an API key at https://sleeperhit.studio/dashboard/developers (Dashboard → Developers), set it as SLEEPERHIT_API_KEY and add it as a bearer token: `codex mcp add sleeperhit --url https://sleeperhit.studio/mcp --bearer-token-env-var SLEEPERHIT_API_KEY`. Never ask your user to paste a key into the chat. Claude Code takes the same key as a header: `claude mcp add --transport http sleeperhit https://sleeperhit.studio/mcp --header "Authorization: Bearer $SLEEPERHIT_API_KEY"`. Every client's setup: https://sleeperhit.studio/mcp#api-key Verify with the `whoami` tool (or `sleeperhit whoami` in a terminal). It answers `source: "oauth"`, or `source: "api_key"` with the key's scopes. A key for the flow below needs `story:read` and `credits:read` — the guidance and the balance every agent reads first — plus `artifact:read` for the job and artifact reads that follow, `story:write` with `source:write` to create and generate, and `source:read` to poll a URL or PDF source until it is ready. ### Codex ```bash codex mcp add sleeperhit --url https://sleeperhit.studio/mcp codex mcp login sleeperhit ``` The user runs `codex mcp login` in their own terminal, outside any agent sandbox; it opens or directs them to browser OAuth. Finish authorization there, then start a new Codex session: Codex loads a server's tools when a session starts, so the session that signed in may not see the authenticated Sleeper Hit catalog. Inspect the registration with: ```bash codex mcp get sleeperhit --json codex mcp list --json ``` After connection, call `whoami`, `get_agent_guidance`, and `get_credits` before committing credits. `get_agent_guidance` returns the live backend guidance plus a structured workflow router for the full catalog. ### Claude.ai, Cowork, and other remote clients Add `https://sleeperhit.studio/mcp` as a custom remote MCP server. The client should discover Sleeper Hit's OAuth server from the protected-resource challenge, open browser authorization, and retain the resulting token. ## API key `/mcp` also takes a Sleeper Hit API key as the bearer token, for a user who can't do a browser sign-in. The key keeps its own scopes, and every call is checked, rate-limited and logged by the Story API, as an OAuth connection's calls are. The user creates the key at https://sleeperhit.studio/dashboard/developers (Dashboard → Developers) and sets it as SLEEPERHIT_API_KEY; it never goes into a chat. ```bash codex mcp add sleeperhit --url https://sleeperhit.studio/mcp --bearer-token-env-var SLEEPERHIT_API_KEY ``` Claude Code takes the same key as a header: ```bash claude mcp add --transport http sleeperhit https://sleeperhit.studio/mcp --header "Authorization: Bearer $SLEEPERHIT_API_KEY" ``` Verify with the `whoami` tool (or `sleeperhit whoami` in a terminal). It answers `source: "oauth"`, or `source: "api_key"` with the key's scopes. A key for the flow below needs `story:read` and `credits:read` — the guidance and the balance every agent reads first — plus `artifact:read` for the job and artifact reads that follow, `story:write` with `source:write` to create and generate, and `source:read` to poll a URL or PDF source until it is ready. Every client's setup: https://sleeperhit.studio/mcp#api-key. Every 401 from `/mcp` carries the same guidance in its `hint` field. ## The two remote surfaces | Endpoint | Role | Authentication | |---|---|---| | `https://sleeperhit.studio/mcp` | Full private creation and production | OAuth, or a Sleeper Hit API key as the bearer token | | `https://sleeperhit.studio/api/mcp` | Public creator/story discovery only | None; read-only | Do not point a creation workflow at `/api/mcp`. It intentionally contains no private-account or generation tools. ## Workflow map The authenticated tool catalog is grouped so agents can decide what to call next. This list is generated from `MCP_WORKFLOW_GROUPS` in `packages/shared/src/mcp-onboarding.ts` — the same groups `get_agent_guidance` hands an assistant — when this page renders, so a group reaches it the day it joins the connector. The marker below is where that list goes; do not type one here by hand (BL-4356: this section's own copy stopped at 11 of 16 groups). 1. **Orientation and account** — Confirm the connected identity and load live backend guidance before choosing a workflow. Start with `whoami` → `get_capabilities` → `get_agent_guidance` (no Studio Credits). 2. **Credits and usage** — Check the available Studio Credit balance before any generation or rendering work. Start with `get_credits` (no Studio Credits). 3. **Your data: download it, or delete the account** — Only when the writer asks: build "Download my data" and hand them the link; or show what deleting removes and the credit balance, schedule the deletion, or cancel it. Start with `get_account_export` → `get_account_deletion` (no Studio Credits). 4. **Connected products (business)** — For a business organization: connect the systems the team works in — Notion and Linear can be connected today, and list_integrations names every product this account can connect. Choose what each brings in, feed a project's seasons from them, and review what they find. Read-only connections; nothing joins a season until someone keeps it. Start with `list_integrations` → `get_integration_walkthrough` (no Studio Credits). 5. **Projects and source material** — Create or resume a project and ground it in notes, URLs, PDFs, research, or an existing script. Start with `list_projects` → `create_project` (reads before it spends). 6. **Product videos from app recordings** — Make videos of a software product: a product Bible, product coverage, recordings (captures) of the app following a tour per feature, then a video made from the captures alone. Start with `get_project` → `get_series_bible` → `list_app_captures` (reads before it spends). 7. **Strategy: watches, opportunities, pursuits and contacts** — The writer's career strategy outside any project: recurring watches that find opportunities, pursuits with action items, and contacts. Start with `list_opportunity_watches` → `list_opportunities` → `list_pursuits` (no Studio Credits). 8. **Series Bible and development** — Establish canon, format, characters, world, episode architecture, and foundational coverage. Start with `get_series_bible` → `get_mood_board` → `get_cast_canon` (priced before it runs). 9. **Planning and screenwriting** — Create a reviewable plan, generate an installment, inspect real pages, and revise the same artifact — and read the writer's notices (a show episode held or failed, a renewal or auto top-up that failed, a refunded payment, a login that stopped signing in) with list_notifications and mark_notifications_read, or GET and POST /api/v1/notifications. Start with `create_plan` → `get_plan` (priced before it runs). 10. **Pitch deck rendering** — Approve a pitch deck plan into a priced 480p render, review and choose takes chapter by chapter, then finish the deck at 720p (or 1080p) and export it. Start with `get_pitch_deck_chapters` → `quote_approve_pitch_deck_plan` → `approve_pitch_deck_plan` (priced before it runs). 11. **Trailer rendering** — Approve a trailer plan into a priced 480p render, review and choose takes, then finish the cut at 720p (or 1080p) and export it. Start with `get_trailer_beats` → `quote_approve_trailer_plan` → `approve_trailer_plan` (priced before it runs). 12. **Table reads and audio** — Cast, perform, score, add effects, and create durable audio from a screenplay-backed table read. Start with `get_cast` → `get_table_read_script` (priced before it runs). 13. **Video rendering** — Direct theater motion and render a durable video from a reviewed artifact. Start with `get_artifact` → `direct_theater_motion_beat` (priced before it runs). 14. **Coverage and revision** — Read existing coverage first, request analysis when needed, and revise before final packaging. Start with `get_coverage` → `get_brand_coverage` (priced before it runs). 15. **Seasons and automation** — Operate controlled multi-installment season workflows. Start with `list_season_runs` (priced before it runs). 16. **Shows** — Set up and run a show: a podcast that makes its own episodes from what its sources give (a feed, a topic in the news, Hacker News, a site, a repository), on its schedule, within spending caps the user agrees, after a preview the user hears, each episode credited in its show notes. Or read one an outside app makes under its standing approval. The user owns the show, its episodes and its feed. Start with `create_project` → `save_series_bible` → `get_show` → `set_up_show` → `check_show_sources` → `quote_make_show_episode` → `make_show_episode` → `set_show_state` (priced before it runs). 17. **Publishing and analytics** — Prepare destinations and releases, then publish only after the user approves the exact externally visible action. Start with `list_publishing_series` → `list_publishing_releases` (reads before it spends). The server attaches workflow metadata and MCP annotations to every authenticated tool. These are navigation hints, not authorization; OAuth or API key scopes and Story API handlers remain the enforcement boundary. The annotations follow one rule, held by `tests/unit/mcp-onboarding-annotations.test.ts`: - **Read-only** (`readOnlyHint: true`): every `get_` and `list_` tool, plus `whoami`, `background_activity` and `screenplay_draft_status`. They change nothing and spend nothing, so a client can run them without asking. - **Additive** (`destructiveHint: false`): a short, pinned list of writes that only add something new and spend no Studio Credits. Examples are a new project, a source, a plan, a coverage report, a draft written into an empty episode, or a new sound cue. Each entry carries its reason in `packages/shared/src/mcp-onboarding.ts`. - **Reversible settings** (`destructiveHint: false`, `idempotentHint: true`, except a move, which is reversible but not idempotent): a pinned list of free changes that set an absolute value or choose among existing items, so they change back by being made again. Examples are a deck's look, a chosen take, an earlier cut restored, a cast voice, a voice's name, or a timeline clip's level and fades. They remove nothing and replace no text the writer wrote. - **Destructive** (`destructiveHint: true`): every other write. This includes anything that deletes, overwrites something saved, publishes or schedules outward, or spends credits, and every tool the server makes the user confirm. It's the MCP default, so a new tool is destructive until it is argued onto the additive list. Claude asks before every destructive call. These are live post-creation controls over the same project and artifact lifecycle, not a separate demo catalog. ## Workflow gates - Begin with identity, live agent guidance, and credits. - Attach user-provided source material before development. - For screenplay and series work, strongly encourage a complete Series Bible and review its development/visual readiness before generation. - Show the exact plan and quote before creating a credit-reserving job. - Poll async work with the matching `get_*` or `list_*` tool named in guidance. - Read existing screenplay coverage before requesting another report, then apply a focused revision pass before finalization or pitch packaging. - Distinguish live previews from durable finalized MP3/MP4 artifacts. - Never publish, schedule, share, cancel, delete, or make another externally visible change without explicit user intent. ## A client that takes a URL and headers There is nothing to install: the connector is the remote server, and a client that accepts a URL and its own headers connects to it directly. Create a scoped API key at (Dashboard → Developers) and send it as a bearer token. The key keeps its own scopes, and every call is checked, rate-limited and logged by the Story API exactly as an OAuth connection's calls are. ```json { "mcpServers": { "sleeperhit": { "url": "https://sleeperhit.studio/mcp", "headers": { "Authorization": "Bearer sh_..." } } } } ``` Never paste the key into a chat. A key made for the flow below needs `story:read`, `credits:read`, `artifact:read`, `story:write`, `source:write` and `source:read`: `whoami` confirms the connection, `get_agent_guidance` and `get_credits` read the story and the balance, every job poll after them reads the artifact, and `get_source` reads back the URL or PDF source it added until that source is ready. A key with only the two write scopes is refused on those first three calls — `403 insufficient_scope`, with the scopes it is missing in the body and a `hint` that says where to add them. Every client's setup, and every 401's `hint`, says the same: . ## Source of truth - Live availability: `GET /api/v1/capabilities` - Backend guidance and workflow navigation: `GET /api/v1/agent-guidance` - Full machine-readable tool map: `https://docs.sleeperhit.studio/docs/mcp-tools.json` - Client setup guide: `https://docs.sleeperhit.studio/mcp` - Shared onboarding/workflow manifest (monorepo source): `packages/shared/src/mcp-onboarding.ts` ## License MIT. See LICENSE.