# 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 sign-in 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 the login yourself, and do not retry it. 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/api (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. It answers `source: "oauth"`, or `source: "api_key"` with the key's scopes; to create and generate, a key needs story:write and source:write. ### Codex ```bash codex mcp add sleeperhit --url https://sleeperhit.studio/mcp codex mcp login sleeperhit ``` For stage testing: ```bash codex mcp add sleeperhit --url https://stage.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/api (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. It answers `source: "oauth"`, or `source: "api_key"` with the key's scopes; to create and generate, a key needs story:write and source:write. 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: 1. **Orientation and account** — `whoami` → `get_agent_guidance` 2. **Credits and usage** — `get_credits` 3. **Projects and source material** — `list_projects` / `create_project` (or `create_project_from_script` for a script that is in no project) → sources; the writer's own episodes: `list_project_episodes`, `get_script`, `upload_script`, `upload_script_version`, `update_script`, `delete_script_version`, `export_script`, `create_project_season` 4. **Series Bible and development** — Bible, cast canon, foundational coverage, each episode's overrides of the canon (`get_script_overrides` / `update_script_overrides`), and preparing a cast episode's table read (`prepare_table_read`, priced: two calls) 5. **Planning and screenwriting** — plan → approve → job → screenplay pages; a writer's own drafts: `start_planned_episode`, `write_script_content`, `finish_draft` 6. **Pitch deck review** — review and refine a pitch deck before it renders 7. **Table reads and audio** — cast, voices, performance, music, SFX, durable audio 8. **Video rendering** — theater motion and durable video 9. **Coverage and revision** — read coverage (a table read's or a writer's own episode's), its history (`list_coverage_versions`) and Black List analysis (`get_blacklist_analysis`), revise, and re-review 10. **Apps, seasons, and automation** — controlled repeatable and multi-installment flows 11. **Publishing and analytics** — destinations, releases, feeds, and analytics 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. ## Alternative: local stdio / API key This package is the local stdio and customer API-key integration. It is a thin wrapper over the Story API and uses the same scopes, rate limits, idempotency, and audit path as the web and CLI surfaces. ```bash npm install -g @sleeperhit/mcp-server SLEEPERHIT_API_KEY=sh_... sleeperhit-mcp ``` Example local MCP configuration (no install needed; `npx` fetches the package): ```json { "mcpServers": { "sleeperhit": { "command": "npx", "args": ["-y", "@sleeperhit/mcp-server"], "env": { "SLEEPERHIT_API_KEY": "sh_..." } } } } ``` Without `SLEEPERHIT_API_KEY` the server still starts; call its `login` tool to sign in from the browser. A sign-in asks for every scope unless `login`'s `scopes` narrows it, and its key lasts 90 days: signing in again (here or with `sleeperhit login`, which shares the saved file) renews it and revokes the previous key, and `logout` revokes it on the server. From a checkout of the monorepo, build it and point the client at the bundle instead: ```bash pnpm --filter @sleeperhit/mcp-server build SLEEPERHIT_API_KEY=sh_... node packages/mcp-server/dist/index.js ``` Requirements: - Node.js 20 or later. - A scoped customer API key from `https://sleeperhit.studio/dashboard/api`. - `SLEEPERHIT_BASE_URL` only when targeting stage or local development. The binary reserves stdout for MCP protocol traffic and writes operational logs to stderr. ## 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.