Skip to main content
JoggAI MCP exposes explicitly registered OpenAPI v2 operations as tools. The exact scope-filtered list is returned by tools/list; clients should not assume a fixed tool count. New REST endpoints do not become MCP tools automatically. Legacy /open and /open/v1 operations are not exposed.

​
Tool groups

Tool names and input JSON Schemas come from the JoggAI OpenAPI v2 contract. The agent should use the schema returned by tools/list instead of inventing REST paths or fields. Generation tools can consume the selected Space’s existing JoggAI credits. There is no separate MCP balance or MCP surcharge. Every credit-consuming tool includes a billing warning in its description and is marked with a destructive hint so compatible clients can request confirmation. Examples include:
  • AI scripts and avatar images
  • Speech synthesis
  • Avatar motion and lip sync
  • Avatar, product, preview, and template video generation
  • Video translation
An OAuth scope is permission to call a tool, not approval for a particular charge. Review the tool name, billing warning, Space, duration, image count, preview count, and other cost-driving inputs before confirming.
Read-only status tools do not resubmit work. When retrying after a timeout, query the existing task ID before creating another paid task.
MCP transport retries are not a billing idempotency guarantee. If a paid submit call times out before returning a task ID, do not replay it automatically. Some tools accept an explicit idempotency key; otherwise inspect the matching list or status tool, then contact support if the outcome is still unknown.

​
Speech model selection

The jogg_post_audio_tts_synthesize tool accepts optional body.model_id for ElevenLabs voices. Select eleven_flash_v2_5 or eleven_v4_turbo; omitting the field uses eleven_flash_v2_5. Empty strings, whitespace, null, non-string values, and other model IDs are rejected. For a voice from another provider, omit model_id to preserve its existing behavior. Explicitly selecting either ElevenLabs model for that voice is rejected. The default in tools/list describes ElevenLabs behavior; clients should not add the field automatically when the user has not selected a model. Jogg adapts pause controls in a copy when sending the synthesis request and keeps the original text. For eleven_v4_turbo, timed breaks greater than 0 and up to 0.5 seconds become [short pause]; breaks over 0.5 and up to 1 second become [pause]; longer breaks, including those over 2 seconds, become [long pause]. Zero-second breaks are removed, and supported millisecond values are converted to seconds first. For Flash, [short pause], [pause], and [long pause] become SSML breaks of 0.3, 0.75, and 1.5 seconds respectively. These are Jogg compatibility rules, not exact duration equivalents specified by ElevenLabs. Flash preserves other bracketed text; delivery tags such as [whispers] need v4 Turbo. New v4 Turbo subtitles omit complete square-bracket audio tags and break tags. When adapting v4 pause tags for Flash, subtitles omit those controls and their converted breaks while retaining other bracketed text. These v4 compatibility paths split words at explicit pauses and preserve the returned timing gap. Native Flash breaks continue to use the existing subtitle processing. The input-text fallback uses the same model-specific filtering when word timestamps are unavailable; control-only text has no subtitle content. Existing subtitles are not rewritten. To select v4 Turbo, pass these tools/call parameters:
To use Flash v2.5 by default, remove model_id. Keep a stable idempotency_key when retrying the unchanged request. Changing an explicit model with the same key causes a conflict; use a new key for a new synthesis. When the task ID is known, use jogg_get_audio_tts_tasks_task_id to check its status without another paid submission. See Synthesize Speech for the REST API request. Native text controls also depend on the model: Flash v2.5 accepts SSML <break time="1.5s" /> (up to 3 seconds), while v4 Turbo uses square-bracket audio tags such as [whispers] or [short pause] and does not support SSML breaks. Flash does not support those audio tags. Put the instructions in body.text; pause tags have no fixed duration in seconds. See the model comparison, examples, and official ElevenLabs sources before switching text controls between models.

​
Asynchronous jobs

Generation submissions normally return a task or resource ID. A robust agent workflow is:
1

Review inputs and billing warning

Confirm the selected Space and cost-driving parameters before submission.
2

Submit once

Store the returned task, video, generation, or preview ID.
3

Poll the matching status tool

Continue until the job completes or returns a terminal failure.
4

Reuse the existing result

Do not create a duplicate because a client connection or polling request timed out.

​
Uploads

MCP JSON-RPC requests do not carry large media files. An upload tool returns a short-lived signed URL, method, and required headers. Upload the bytes directly to object storage, then pass the resulting asset reference to another tool. Treat signed URLs as credentials. Do not log, publish, or reuse an expired URL.

​
Space and resource isolation

Authorization binds the session to a JoggAI user and selected Space. Private avatars, images, products, generation tasks, and other resources must belong to that authorized context. Knowing another resource ID does not grant access. Team members use the Space’s actual billing account for quota checks and paid operations. If Space membership, ownership, or plan eligibility changes, an existing token may stop authorizing calls.

​
Webhooks and external effects

Creating, updating, or deleting webhook endpoints changes where JoggAI sends events. Confirm the destination domain and selected endpoint before a write or delete. Never send authorization headers, OAuth tokens, or signed asset URLs to a webhook destination.