@sleeperhit/mcp-server

A Model Context Protocol server that exposes the Sleeper Hit Studio B2B Story API (/api/v1) as MCP tools. Point any MCP-capable agent — Claude Desktop, Claude Code, Cursor, etc. — at it and the agent can build a podcast end-to-end: ingest sources, develop a Series Bible, map a season with the user, generate coverage-gated episodes, and publish them to a shareable RSS feed.

It is a thin, faithful wrapper over the REST API. Tool names and endpoint paths track docs/agents/api-reference.md. For the authoritative, live feature list, read the capabilities resource (it fetches GET /api/v1/capabilities).

What an agent can do with this

The Story API is a pipeline. The tools mirror each stage:

1. Sources — add_source (type text | markdown | url | pdf). Inline text is READY immediately; url/pdf are fetched asynchronously, so poll get_source until status: READY. Each source then runs a structured digest (digestStatus).
2. Series Bible — use get_series_bible, save_series_bible, and generate_series_bible to establish durable format, canon, cast, audio direction, then generate_series_bible_coverage / get_series_bible_coverage to pass the versioned foundational craft gate direction, and the complete episode map shared by the web, REST, CLI, and MCP surfaces.
3. Season map — create_season_run imports the Bible episode map without generating anything. Discuss and confirm each brief with map_season_episode, then show the complete map and call approve_season_map only after the user explicitly approves that exact map.
4. Season runner — reload with get_season_run, take one durable step with advance_season_run, and follow the returned nextAction. Every episode plan, revision/retry, production repair, and RSS publish hold remains explicit. Coverage and required music/SFX/voice effects fail closed before publishing. Episodes publish sequentially to the run's audio RSS series.
5. Plan — for one-off work, call create_plan against a project with a target (audience / objective / outcome) and one or more artifactRequests. Returns a credit quote and runs the planner asynchronously; poll get_plan.
6. Approve — show the exact plan to the user, then call approve_plan with userConfirmed: true once it reaches REQUIRES_APPROVAL (non-table-read plans may skip this by passing autoApprove: true to create_plan). reject_plan is the terminal alternative.
7. Job — create_job from an APPROVED plan. This reserves Studio Credits and queues generation. Poll get_job (or list_artifacts). For a known table-read cast, call list_voices first and set a complete voiceMap on the single table_read artifact request; each entry requires voiceId and may include voiceName, gender, and provider.
8. Artifact — get_artifact returns the manifest: share URLs for a table read, video status, etc. render_artifact_video triggers the opt-in MP4 (separate charge).
9. Refine / finalize — refine_artifact (natural-language instruction) and finalize_artifact. These are live post-creation controls for table read artifacts: refine creates a new revision under the same artifact id and share URLs, while finalize renders a durable MP3 or MP4.

Discovery: read the capabilities resource (sleeperhit://capabilities) first — it tells the agent which source types, artifact types, statuses, and quote pricing are live right now.

Tool catalog

Every tool returns JSON as text content: { "ok": true, ... } on success, or { "ok": false, "error": { code, message, status, requestId, details? } } with isError: true on failure — the same { error: { code, ... } } envelope the API returns, so agents can branch on error.code.

Install & build

From the monorepo root (pnpm workspace):

Copypnpm --filter @sleeperhit/mcp-server install
pnpm --filter @sleeperhit/mcp-server build

This compiles src/ to dist/ and exposes the sleeperhit-mcp binary (dist/index.js). To run it directly for a smoke test:

CopySLEEPERHIT_API_KEY=sh_... node packages/mcp-server/dist/index.js

Environment variables

Credit-reserving and generation POSTs (sources, plans, jobs, season advances, render-video) automatically attach a generated Idempotency-Key for safe retries.

MCP client config

Claude Desktop / Claude Code

Add to your MCP servers config (Claude Desktop: claude_desktop_config.json; Claude Code: .mcp.json or claude mcp add-generated config):

Copy{
  "mcpServers": {
    "sleeperhit": {
      "command": "sleeperhit-mcp",
      "env": {
        "SLEEPERHIT_API_KEY": "sh_...",
        "SLEEPERHIT_BASE_URL": "https://sleeperhit.studio"
      }
    }
  }
}

If sleeperhit-mcp is not on your PATH (e.g. you built locally without a global link), point command at the built file instead:

Copy{
  "mcpServers": {
    "sleeperhit": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "SLEEPERHIT_API_KEY": "sh_...",
        "SLEEPERHIT_BASE_URL": "https://sleeperhit.studio"
      }
    }
  }
}

Notes

• stdout is reserved for the MCP wire protocol; the server logs to stderr.
• The server validates SLEEPERHIT_API_KEY at startup and exits non-zero if it is missing, so misconfiguration fails loudly.