@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 story end-to-end: ingest sources, plan, approve, generate, and refine artifacts.

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. Plan — 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.
3. Approve — approve_plan once the plan reaches REQUIRES_APPROVAL (skip this by passing autoApprove: true to create_plan). reject_plan is the terminal alternative.
4. Job — create_job from an APPROVED plan. This reserves Studio Credits and queues generation. Poll get_job (or list_artifacts).
5. 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).
6. Refine / finalize — refine_artifact (natural-language instruction) and finalize_artifact. These are forward-compatible: if the endpoint is not live in the current API phase, the tool returns the real server response (e.g. a 404 envelope) rather than faking success.

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, 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.