@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" }
		}
	}
}

For local development against unpublished changes, replace npx -y @cutpro/mcp with bun run /path/to/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. Set MCP_REDIS_URL (e.g. redis://127.0.0.1:6379) to back the OAuth state (clients, codes, tokens) with Redis so it survives restarts and works across multiple instances. Without it, an in-memory store is used (single instance, state lost on restart).

Hosting: run it on a dedicated host at the root and point a reverse proxy at it:

your-mcp-host { reverse_proxy localhost:8787 }

To connect to the hosted instance: 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