Skip to main content
[ MCP server ]

Let an agent cut clips for you over MCP

The backend ships an MCP endpoint at POST /mcp on your own host. An agent gets 8 tools to start jobs, read status, list clips, restyle captions and recut.

What you need to connect

  • An osk_ API key (created on the API access page) or a session token. Without one /mcp returns 401. Each tool runs with the account's permissions, so admin-only tools fail for a member.
  • A token in the Authorization: Bearer header. The login cookie does not work, because tools only forward the Authorization, X-API-Key, X-Gemini-Key and X-Upload-Post-Key headers.
  • An osk_ key does not expire until it is revoked. A session token lives only 30 days; when it expires, sign in again and update the client config.
  • Enough credits: process_video calls POST /api/process, so it reserves credits like any other job.
  • A user who holds the rights to the content. process_video refuses unless confirm_rights is true.

Connect a client

The server speaks plain HTTP: POST JSON-RPC, get JSON back, with no SSE and no sessions. Any MCP client that supports HTTP and can send headers works. The example below is Claude Code.

Connect · bash
# BASE is the VimeoClip address you use. TOKEN is an admin session token.
BASE=http://localhost:8000
TOKEN=$(curl -s -X POST "$BASE/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"YOUR_PASSWORD"}' | jq -r .access_token)

claude mcp add --transport http openshorts "$BASE/mcp" \
  --header "Authorization: Bearer $TOKEN"
List tools · bash
curl -s -X POST "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | jq -r '.result.tools[].name'
Call a tool · bash
curl -s -X POST "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "process_video",
      "arguments": {
        "source_url": "https://www.youtube.com/watch?v=VIDEO_ID",
        "confirm_rights": true,
        "target_clips": 5
      }
    }
  }' | jq .result.structuredContent

The 8 tools

Each tool calls one REST route of the same app, with the caller's headers.

ToolRequired argumentsOther argumentsWhat it does
process_videoconfirm_rights, plus source_url or upload_idtarget_clips, clip_min_seconds, clip_max_seconds, output_format, layouts, captions, caption_preset, auto_hook, hook_style, moment_hint, clip_workflow, clip_lenses, source_language, caption_language, test_mode, webhook_url, webhook_secret, force_low_quality and other processing fieldsStarts a job from a link or an uploaded file and returns job_id at once.
create_uploadNonefilenameReserves an upload slot and returns upload_id and upload_url.
get_job_statusjob_idNoneStatus, last 10 log lines, the error if any, clips once they exist.
list_clipsjob_idNoneClips of a finished job: titles, per-platform descriptions, score, video_url.
get_quotaNoneNoneSee the note below: it does not return a balance yet.
add_subtitlesjob_id, clip_indexstyle, position, font_size, font_name, font_color, highlight_color, uppercaseRestyles the captions of one clip.
recut_clipjob_id, clip_index, segmentssnap_to_words, reapply_captions, framingRe-renders a clip from a list of segments in source-video seconds.
publish_clipjob_id, clip_index, platformstitle, description, scheduled_date, timezonePosts to tiktok, instagram, youtube. See the note below.

clip_index starts at 0 and comes from list_clips.

A typical call flow

process_video returns job_id right away, so an agent does not wait inside one call.

  1. Call process_video

    Pass the link exactly as the user gave it. The server downloads the video, so the agent does not need to open the link.

  2. Follow the job

    Call get_job_status every 30 to 60 seconds, or pass webhook_url to be called back.

  3. Read the clips

    When status is completed, call list_clips.

  4. Adjust if needed

    Use add_subtitles to change captions and recut_clip to cut again.

What to know first

The tools behave as the current code does, so a few things are worth knowing before you hand them to an agent.

  • get_quota always returns a note saying there is no minute quota, even though jobs still reserve credits. For the real balance, call GET /api/me.
  • publish_clip cannot send an Upload-Post profile name yet, so the route can return 400 "Missing Upload-Post user profile". Call POST /api/social/post directly with the user_id field.
  • create_upload builds upload_url from PUBLIC_API_URL. When the server has not set it, upload_url points at the tool's internal address.
  • The file PUT and video_url links both need the token, because /api/uploads and /videos are closed to anonymous callers.
  • list_clips returns an absolute video_url when PUBLIC_API_URL is set. Without it you get a relative path.

Uploading a file for create_upload

Unlike the hint in the tool description, the PUT must carry the token.

PUT · bash
# create_upload returns upload_id and upload_url.
curl -T video.mp4 "UPLOAD_URL" -H "Authorization: Bearer $TOKEN"

Frequently asked questions

POST /mcp on the same host as the dashboard you use, for example https://<host>/mcp.

Need the routes behind the tools?

The API page lists the POST /api/process fields, how to read clips and the error codes.

Illustration (stock video), not VimeoClip output · Storyblocks