# Deepy MCP server

Let your AI assistant make videos, images and audio on Deepy for you. You
describe what you want in a normal chat message, the assistant handles the model
choice, the parameters and the download.

Works with Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, Zed and
anything else that speaks [MCP](https://modelcontextprotocol.io).

```
You:  make me a 5-second clip of a cat knocking a glass off a table
Agent: That's bytedance/seedance-2.0, 133 credits. Go ahead?
You:  yes
Agent: Done — saved to ~/Downloads/deepy-8f3a…-0.mp4
```

Everything is billed to your normal Deepy balance. No separate card, no separate
invoice.

## Before you start

You need two things:

1. **Node.js 22 or newer.** Free, from [nodejs.org](https://nodejs.org). This is
   what runs the connector.
2. **A Deepy API key.** Create one in the Deepy web app under **API access**.
   It looks like `sk_live_…` and is shown only once, so copy it right away.

## Setup

Add this to your MCP client's config, replacing the key with your own.

**Cursor** — `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for
just one:

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

**Claude Desktop** — the same block in `claude_desktop_config.json`, then restart
the app. Copy-paste versions of both live in [`mcp-configs/`](./mcp-configs).

Other clients take the same three fields but not always under `mcpServers`: VS
Code and Windsurf use `servers`, Zed uses `context_servers`. Check your client's
own MCP docs for the wrapper key.

Then restart your client and ask it to list Deepy models. If it answers, you're
connected.

**The first start is slow.** `npx` downloads the connector before the client gets
a reply, which can take half a minute or so. If your client gives up early, raise
its MCP startup timeout to 60 seconds. Later starts are fast.

### Running from a local clone instead

Useful if you're working on the connector itself, or you want a pinned version:

```bash
git clone https://github.com/deepy-to/deepy-mcp-server
cd deepy-mcp-server
npm install
```

Then point the config at the built file — `"command": "node"`,
`"args": ["/absolute/path/to/deepy-mcp-server/dist/index.js"]`, same `env` block.

### Not on npm yet

`npx -y @deepy/mcp-server` gives you a 404 — the package hasn't been published.
Install from GitHub as shown above.

## What the assistant can do

| Tool              | What it's for                                               |
| ----------------- | ----------------------------------------------------------- |
| `generate`        | the whole job: price it, then create, wait and download     |
| `list_models`     | see which models are available                              |
| `get_model`       | read one model's parameters and limits (or several at once) |
| `improve_prompt`  | turn a rough idea into a stronger prompt                    |
| `upload_file`     | send a reference image, video or audio (up to 50 MiB)       |
| `open_topup_page` | open the top-up page when your balance runs out             |

`generate` is the one the assistant normally uses. Called without confirmation
it just quotes the price; called again with the same arguments and your approval
it creates the generation, waits for it and hands back the finished file. That's
two steps instead of the eight the granular tools need.

Those granular tools — `estimate_generation`, `create_generation`,
`get_generation`, `get_result` — are still there for step-by-step control, and
for the case where a long video outlives `generate`'s wait window.

The connector also ships prompt templates and short guides that teach the agent
the flow below, so you don't have to explain it every time.

## How spending works

This is the part worth reading.

**Nothing is charged without your explicit yes.** The agent has to price the
generation first (free), show you the number, and get an answer. Both paths
enforce this: `generate` stops after pricing and returns the cost, and
`create_generation` refuses to run unless it's told the user confirmed. When
either refuses, no paid request reaches the Deepy backend at all.

**The quoted price is the price.** The estimate and the create send byte-identical
requests, so the number you approved is the number you pay.

**You are never charged twice for one generation.** Each create derives its
idempotency key from the request itself, so a retry of identical arguments
replays the existing generation instead of buying a second one. If the agent
ever reports `IDEMPOTENCY_CONFLICT`, the generation already exists — it should
check its status, not start over.

If you deliberately want another copy of the same request (for a model that
varies by seed), the tools support a `copy` argument: set it to 2 for a second
copy, 3 for a third, and so on. Asking for copy 2 twice (a timeout-retry, an
agent loop) still replays — it's an ordinal, not a nonce.

**Out of credits isn't a dead end.** When your balance can't cover a generation,
the agent can open the Deepy top-up page in your browser. Add credits, tell it
you're done, and it picks up where it left off.

The Deepy backend, not this connector, decides prices, moderation and limits.

## Where your files land

Finished results are saved to `~/Downloads` (or your temp folder if that isn't
writable), and the agent tells you the path. Small images and audio also render
right in the chat.

Videos and large files stream straight to disk, so a long clip is limited only by
your free space — nothing is held in memory. If a download fails halfway, the
partial file is deleted rather than left looking complete.

## When something goes wrong

**No Deepy tools show up.** Check Node.js is installed (`node --version`), that
the config is in the right file, and that you fully restarted the client — not
just reopened the window.

**"Unauthorized".** The key is wrong, expired or disabled. Issue a new one under
API access and update the config.

**"Insufficient balance".** Top up and ask the agent to try again. It can open
the page for you.

**"Model not found".** The catalog changed. Ask the agent to list models and pick
from what's there.

## Your API key

The key is read only from the config's `env` block. The connector never accepts
it from chat text, never prints it in a log line, and never passes it back to the
agent — when the agent fetches your finished video, the connector does the
authenticated request itself.

It also never hands out raw storage URLs, never talks to the generation providers
directly, and refuses to follow HTTP redirects, so your key can't be replayed to
another host.

## Configuration reference

| Variable                | Required | What it does                                           |
| ----------------------- | -------- | ------------------------------------------------------ |
| `DEEPY_API_BASE_URL`    | yes      | Deepy API origin, no trailing slash                    |
| `DEEPY_API_KEY`         | yes      | your personal key (`sk_live_…`)                        |
| `DEEPY_LOG_LEVEL`       | no       | `debug`/`info`/`warn`/`error`/`silent`, default `info` |
| `DEEPY_HTTP_TIMEOUT_MS` | no       | request deadline in ms, default 30000                  |
| `DEEPY_MAX_RESULT_MB`   | no       | runaway-download guard in MiB, default 2048            |

Downloads get a longer deadline than `DEEPY_HTTP_TIMEOUT_MS` — at least two
minutes, and it resets on every chunk received, so a slow but healthy transfer
isn't cut off mid-file.

## Working on the connector

```bash
npm install
npm run build      # compile src/ to dist/
npm test           # vitest
npm run dev        # run from source
npm run lint
```

`dist/` is committed on purpose: that's what makes installing straight from
GitHub work without a build step on the user's machine. Rebuild before you commit
a source change.

## License

MIT.