cutpro-mcp

cutpro-mcp

MCP server that exposes the public CutPro v1 API as tools, so AI clients can drive the full clipping flow: analyze → submit → poll → list clips → render → download, plus balance and templates.

Built to work everywhere and to be token-efficient.

Tools

All 34 v1 endpoints are exposed, grouped by resource:

• Workspace & balance: get_workspace, get_balance, get_balance_history
• Videos & uploads: list_videos, delete_video, start_upload, complete_upload
• Clipping: analyze_video, submit_clipping, list_submissions, get_submission, delete_submission
• Clips: list_clips, apply_template, delete_clip
• Templates: list_templates
• Renders: render_clip, list_renders, get_render, get_render_download, cancel_render, get_render_limits, start_bulk_download, get_bulk_download
• Posts (publishing): create_post, list_posts, get_post, update_post, publish_post, retry_post_item, delete_post_item, delete_post
• Connections: list_connections, get_connection

Each tool carries read-only / write / destructive annotations so clients can plan calls.

Token efficiency

• Results are compact JSON (no pretty-print) and projected to the fields that matter, dropping null/empty values.
• list_clips is rating-sorted, capped (limit, default 10), and omits the long signed URLs unless include_urls: true.
• Tools carry read-only / open-world annotations so clients can plan calls.

Setup

bun install
cp .env.example .env   # set CUTPRO_API_KEY

API access requires the Pro plan. Generate a key at cut.pro/studio/me/api-keys.

Transports

stdio (default — all local clients)

Works with Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Zed, and any other local MCP client. The client launches the process; it speaks MCP over stdio. Set CUTPRO_API_KEY in the client's env.

Claude Code

claude mcp add cutpro --env CUTPRO_API_KEY=SUA_CHAVE -- npx -y cutpro-mcp

Claude Desktop / Cursor / Windsurf / VS Code (mcpServers config):

{
  "mcpServers": {
    "cutpro": {
      "command": "npx",
      "args": ["-y", "cutpro-mcp"],
      "env": { "CUTPRO_API_KEY": "SUA_CHAVE" }
    }
  }
}

Until published to npm, replace npx -y cutpro-mcp with bun run /abs/path/to/services/mcp/src/index.ts.

Streamable HTTP (remote / self-host)

MCP_TRANSPORT=http PORT=8787 bun run src/index.ts   # serves /mcp

The endpoint is stateless. The key is read per request from Authorization: Bearer <key> or X-Api-Key (env key is the fallback), and X-Workspace-Id is honored, so one deployment can serve many users.

OAuth 2.1 (browser clients: ChatGPT, Claude.ai)

MCP_TRANSPORT=http PORT=8787 MCP_OAUTH=1 MCP_PUBLIC_URL=https://mcp.cut.pro bun run src/index.ts

With MCP_OAUTH=1 the server becomes a full OAuth 2.1 authorization server (metadata discovery, Dynamic Client Registration, PKCE, token + refresh, revocation) using the MCP SDK helpers. The flow:

• The client (ChatGPT/Claude.ai) discovers the server via the WWW-Authenticate header on the 401 from /mcp and registers itself.
• The user is sent to a consent page where they paste their CutPro API key.
• The key is validated against the API; on success a code → access token is issued. The token maps server-side to that key.
• /mcp is protected by bearer auth; each call uses the token's key.

MCP_PUBLIC_URL is the public endpoint (e.g. https://mcp.cut.pro); its origin becomes the OAuth issuer. Token/code/client stores are in-memory — fine for a single instance; back them with Redis/DB for HA.

Hosting: runs on a dedicated subdomain at the root, so the reverse proxy just forwards the whole host to the server:

mcp.cut.pro { reverse_proxy localhost:8787 }

(In this deploy, Caddy is configured by the main API's bootstrap.ts domain map, which routes mcp.cut.pro → localhost:8787.)

To connect: add https://mcp.cut.pro as a custom connector in ChatGPT or Claude.ai and complete the consent step.

Build

bun run build   # outputs dist/index.js