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.
# 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"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'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.structuredContentThe 8 tools
Each tool calls one REST route of the same app, with the caller's headers.
| Tool | Required arguments | Other arguments | What it does |
|---|---|---|---|
| process_video | confirm_rights, plus source_url or upload_id | target_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 fields | Starts a job from a link or an uploaded file and returns job_id at once. |
| create_upload | None | filename | Reserves an upload slot and returns upload_id and upload_url. |
| get_job_status | job_id | None | Status, last 10 log lines, the error if any, clips once they exist. |
| list_clips | job_id | None | Clips of a finished job: titles, per-platform descriptions, score, video_url. |
| get_quota | None | None | See the note below: it does not return a balance yet. |
| add_subtitles | job_id, clip_index | style, position, font_size, font_name, font_color, highlight_color, uppercase | Restyles the captions of one clip. |
| recut_clip | job_id, clip_index, segments | snap_to_words, reapply_captions, framing | Re-renders a clip from a list of segments in source-video seconds. |
| publish_clip | job_id, clip_index, platforms | title, description, scheduled_date, timezone | Posts 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.
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.
Follow the job
Call get_job_status every 30 to 60 seconds, or pass webhook_url to be called back.
Read the clips
When status is completed, call list_clips.
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.
# 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.
Yes, once the admin turns on API access for that account; until then /mcp returns 403. A member connects with their own key. Tools that call admin-only routes (captions, recut, publish) still get 403 "This feature currently requires an administrator".
Yes. process_video calls POST /api/process, so credits are reserved the same way as for a job started in the dashboard.
The server accepts protocolVersion 2025-06-18, 2025-03-26 and 2024-11-05. It does not support batching several messages in one request.
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




