Automation
OpenShorts MCP server, wired to your own pipeline
The repo ships a remote MCP server beside the dashboard: same API, same keys, eight tools that call it in-process. This page is the endpoint, the client command, and what each tool actually takes.
The MCP server is not a separate service. It lives inside the backend at /mcp, and every tool call is turned into an in-process HTTP call against the same routes the dashboard uses. That one design choice explains most of its behaviour: the agent inherits your auth, your quota and your keys, and nothing has to be kept in sync.
The endpoint is just /mcp on the backend
Self-hosted, that is http://localhost:8000/mcp — port 8000, the API port, not the dashboard on 5175. The cloud runs the identical endpoint at https://mcp.openshorts.app/mcp, with api.openshorts.app/mcp serving the same thing.
| Property | Value |
|---|---|
| Transport | Streamable HTTP, plain JSON responses |
| Sessions | None — stateless, no session ids, no SSE stream |
| Protocol versions accepted | 2025-06-18, 2025-03-26, 2024-11-05 |
| Methods used | initialize, tools/list, tools/call, notifications |
| Self-host auth | None required (BYOK): X-Gemini-Key header or the env value |
| Cloud auth | Authorization: Bearer osk_... — the key is the account |
Because the transport is stateless, you can restart the backend between calls without breaking a client, and you do not need a long-lived connection open for a job to finish.
Connect a client in one command
With Claude Code or any client that speaks HTTP MCP, the self-hosted server needs no header at all:
claude mcp add --transport http openshorts http://localhost:8000/mcp
On the cloud, add the bearer header:
claude mcp add --transport http openshorts https://mcp.openshorts.app/mcp \
--header "Authorization: Bearer osk_..."
Any client that takes a JSON config works the same way: point it at the URL and, for cloud, the bearer header. If you are running the stack in Docker on the same machine, localhost:8000 from the host reaches the backend; from another container, use the service name backend and the internal port 8000.
The eight tools
| Tool | What it does |
|---|---|
process_video |
Starts a clipping job from a URL or an uploaded file |
create_upload |
Returns a presigned URL for a local file |
get_job_status |
Progress, the last log lines, and the clips produced so far |
list_clips |
The clips a job produced |
get_quota |
Remaining plan minutes (cloud) or a no-quota note (self-host) |
add_subtitles |
Re-styles or re-times captions on an existing clip |
recut_clip |
Cuts a new clip out of an existing one by timestamp ranges |
publish_clip |
Posts a finished clip to a social platform |
process_video carries the whole configuration surface. The parameters that change the output:
| Parameter | Values | Default |
|---|---|---|
source_url or upload_id |
A video URL, or the id from create_upload |
required |
confirm_rights |
true — you assert you have the rights to the source |
required |
target_clips |
1–15 | 5 |
clip_min_seconds / clip_max_seconds |
5–175 / 10–180 | 15 / 60 |
layouts |
auto, split, screencast, speaker_cut, punch_in |
auto |
output_format |
auto, vertical, horizontal, square |
auto |
auto_hook / hook_style |
boolean; pill, classic, dark, yellow, red, outline, outline_yellow |
true / pill |
captions |
boolean | true |
webhook_url, webhook_secret |
Optional completion callback | — |
force_low_quality |
true skips the low-resolution confirmation gate |
false |
One job, end to end
A minimum call looks like this. confirm_rights is not optional — without it the call is refused, because the pipeline sends frames to third-party models.
{
"source_url": "https://www.youtube.com/watch?v=...",
"confirm_rights": true,
"target_clips": 3,
"output_format": "vertical"
}
Then poll get_job_status every 30–60 seconds. It returns a status of queued, processing, completed or failed, the last ten log lines, and each clip with its index, title, duration, video_url and the source segments it came from. A failed job comes back with the log line that explains it rather than a bare error.
Clips arrive with ready-made youtube_title, tiktok_description and instagram_description fields, so an agent can publish without writing copy again. publish_clip accepts tiktok (as a draft), instagram, youtube, facebook, linkedin, threads and bluesky, plus an optional ISO-8601 scheduled_date.
Uploads, webhooks and where the limits are
create_upload returns a URL you PUT the raw bytes to — curl -T file.mp4 "$URL" is enough — and the URL expires in six hours. If a machine dies mid-upload, ask for a new one; do not reuse the old URL.
Set webhook_url and webhook_secret on process_video and the server POSTs to you when the job finishes, signed with HMAC-SHA256 in the X-OpenShorts-Signature header. Verify that header before acting on the payload; anyone who knows your URL can otherwise post a fake "completed".
Four errors are worth wiring into your client:
quota_exceeded(cloud) — the response carries anupgrade_url.no_plan(cloud) — the key is valid but has no plan attached.needs_confirmation— the source is under the quality gate; retry withforce_low_qualityif you mean it.404 Job not found— cloud jobs are removed from local disk about an hour after they finish, and the API restores the project from storage. A job id from yesterday still works; a job from last month may not.
Self-hosted has no minute quota at all — get_quota says so — which is why the cost conversation here is about your own model bill, not a plan.
Self-host auth versus cloud auth
Self-hosted, the MCP server is BYOK and unauthenticated: whoever can reach port 8000 can start a job with your keys. That is fine on a laptop and not fine on a public VPS — put it behind a firewall or a reverse proxy with auth before you expose it. Cloud, the osk_ key scopes every call to one account, and gating happens exactly as it does for dashboard requests.
The REST routes behind the tools
If you would rather call the API directly than speak MCP, the same operations are plain REST routes on the same port:
| Route | Equivalent |
|---|---|
POST /api/process |
process_video |
POST /api/uploads |
create_upload |
GET /api/status/{job_id} |
get_job_status |
POST /api/subtitle |
add_subtitles |
POST /api/clip/rerender |
recut_clip |
POST /api/social/post |
publish_clip |
GET /api/me |
get_quota |
For where the keys themselves go, see the API keys page; for a job that dies halfway, the troubleshooting page opens with the log commands.