@deepy/mcp-server

Thin MCP server that lets external AI agents (Cursor, Claude Desktop, Claude Code, Windsurf, …) drive Deepy generation of video / image / audio over the public Deepy API using a personal API key.

It carries no business logic — billing, moderation, idempotency, rate limits, provider access and ownership checks all stay in the Deepy backend, which is the source of truth. This server is only a safe adapter that exposes Deepy as MCP tools, prompts and resources.

1. Requirements

• Node.js 22+ (the connector runs on your machine).

• A Deepy API key — create one in the Deepy web app under API access. It is shown only once and looks like sk_live_… (or sk_test_…).

2. Install & configure

Point your MCP client at the connector and give it two environment values:

Option A — run straight from GitHub (works today, no npm needed)

npx clones this repo, installs its dependencies and runs the committed build — no npm publish required.

Cursor — put this in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "deepy": {
      "command": "npx",
      "args": ["-y", "github:deepy-to/deepy-mcp-server"],
      "env": {
        "DEEPY_API_BASE_URL": "https://app.prod.einfra.tech",
        "DEEPY_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Claude Desktop — same block in claude_desktop_config.json, then restart Claude Desktop. Ready-made copies live in mcp-configs/.

Option B — npm (once published)

When @deepy/mcp-server is published to npm, the args simplify to ["-y", "@deepy/mcp-server"].

Option C — local copy (offline / development)

Clone this repo (git clone https://github.com/deepy-to/deepy-mcp-server), run npm install, then point the config at the built entrypoint:

{
  "mcpServers": {
    "deepy": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/deepy-mcp-server/dist/index.js"],
      "env": {
        "DEEPY_API_BASE_URL": "https://app.prod.einfra.tech",
        "DEEPY_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

3. Tools

The server also ships MCP prompts and resources (skills) that teach an agent the safe generation flow.

4. Safe generation flow

1. Understand the task (ask 1–2 clarifying questions if unclear).

2. Pick a model (deepy_list_models / deepy_get_model).

3. Improve the prompt (deepy_improve_prompt).

4. Estimate the cost (deepy_estimate_generation).

5. Show the price and get explicit user approval.

6. Only then deepy_create_generation with confirmed=true.

7. Poll deepy_get_generation, then fetch deepy_get_result.

deepy_create_generation refuses to run without confirmed=true, generates an idempotency key when none is given, and never retries a paid create.

5. Security

• The API key is read only from DEEPY_API_KEY (config/env), never from tool arguments or chat text, and is redacted from every log line.

• The server never talks to WaveSpeed/RunPod, the database or S3 directly, and never returns private provider/S3 URLs.

• The backend remains authoritative for moderation, billing, rate limits and ownership. On INSUFFICIENT_CREDITS top up; on CONTENT_REJECTED the content broke the rules; on MODEL_NOT_FOUND re-list the catalog; on IDEMPOTENCY_CONFLICT do not auto-retry.

6. Troubleshooting

7. Development

npm install
npm run build       # tsc -> dist/
npm test            # vitest (safety-critical behaviour)
npm run dev         # tsx src/index.ts