Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@synthesia-mcp Create a draft video of Anna saying 'Hello from Synthesia!'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that exposes the Synthesia avatar video API to MCP clients such as Claude Desktop. Local stdio transport, API-key auth via environment, draft-by-default rendering so iteration never burns enterprise video quota.
This is a Phase 1 MVP focused on a clean capability layer; opinionated educational-video workflows live in a separate Claude skill that builds on top of these tools.
Related MCP server: HeyGen MCP Server
Once connected, you can ask Claude things like:
"List my Synthesia templates and show me the variables of the one called 'Lesson intro'."
"Create a draft 2-scene video introducing photosynthesis with the Anna avatar."
"Render that as a final video now."
"How's video abc-123… doing? When it's done, make it public."
"Upload ./diagram.png to Synthesia and use it as the background of scene 2."
The server holds the API key; Claude never sees it.
Node.js ≥ 20 (the server is shipped as an ESM bundle and uses the built-in fetch).
A Synthesia API key. Enterprise plan recommended — the API is enterprise-tier on most plans. Find or create a key in Synthesia account settings: https://app.synthesia.io/#/account.
An MCP-capable client. Claude Desktop is the primary target; the server works with any client that supports stdio MCP servers (e.g. Cursor, MCP Inspector).
Clone or unzip this repository, then:
cd synthesia-mcp
npm install
npm run buildThat produces dist/index.js — the executable the MCP client will run.
Open your Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Add (or merge) an entry under mcpServers:
{
"mcpServers": {
"synthesia": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/synthesia-mcp/dist/index.js"],
"env": {
"SYNTHESIA_API_KEY": "your-synthesia-api-key-here"
}
}
}
}Use the absolute path to dist/index.js (Claude Desktop does not resolve ~ or relative paths).
Quit fully and reopen. The Synthesia tools should appear in the tool picker. If they don't, check ~/Library/Logs/Claude/mcp*.log (macOS) or the equivalent on your OS — the server logs to stderr and Claude Desktop captures it.
Once connected, ask Claude:
List my Synthesia templates.
If you see your templates: you're set. If you see an auth_error: the API key is wrong or missing — double-check it in claude_desktop_config.json (no quotes inside the value, no trailing spaces) and restart Claude Desktop.
Render your first video — for free:
Create a draft 1-scene video titled "Hello" with the Anna avatar on a white_studio background. The avatar should say "Hello from Synthesia! This is my first API video."
Claude will call create_video with render_mode: "draft" by default. The result includes a videoId and a note that this is a watermarked test render. Renders take a few minutes; ask Claude to check on it:
Is that video ready yet?
Claude will call get_video and either tell you to wait, or hand you the download URL.
Only when you're happy with the draft, ask explicitly:
Render that as a final video.
A final render counts against your account's video quota.
SYNTHESIA_API_KEYPassed as an environment variable in claude_desktop_config.json's env block. Per the MCP authorization specification, stdio servers retrieve credentials from the environment rather than implementing OAuth; that's exactly what this server does.
~/.synthesia-mcp/config.jsonHolds non-secret settings, primarily your custom avatar and voice IDs (Synthesia has no API endpoint for avatar/voice discovery, so any custom or personal avatar must be registered here to be discoverable via list_avatars).
Shape (see config.example.json):
{
"customAvatars": [
{ "id": "uuid-from-studio", "name": "My Personal Avatar", "notes": "..." }
],
"customVoices": [
{ "id": "uuid-from-studio", "name": "My Custom Voice", "language": "English (UK)" }
],
"defaults": {
"aspectRatio": "16:9"
}
}To get a custom avatar ID: open https://app.synthesia.io/#/actors, hover the avatar, open the three-dot menu, and pick Copy ID.
Override the config path with SYNTHESIA_MCP_CONFIG=/path/to/config.json if you want it somewhere else.
The repo ships with a small seed catalog for offline use. To get the full lists from the live Synthesia documentation:
npm run refresh-catalogThat rewrites catalog/avatars.json and catalog/voices.json. Commit them. Re-run whenever Synthesia publishes new avatars or voices.
All tools return a JSON object inside an MCP text content block. Errors carry isError: true with a structured { code, message, remediation, details? } envelope.
Tool | What it does |
| Lists stock avatars (bundled catalog snapshot) + custom avatars from config. Filter by |
| Lists stock voices (snapshot) + custom voices from config. Filter by |
| Lists STUDIO templates with their variable names. Paginated ( |
| Returns a single template's full variable list — call this before |
Tool | What it does |
| Creates a multi-scene video from raw scene objects ( |
| Renders a STUDIO template by passing |
Both creation tools return a videoId immediately — Synthesia renders asynchronously, often in minutes. Check progress with get_video.
Tool | What it does |
| Returns status ( |
| Lists videos in the account. Paginated, filterable by |
| Updates |
| PERMANENT. Double-gated: refuses unless |
Tool | What it does |
| Uploads an image/video and returns an |
| Uploads narration audio (mp3 / |
Tip: scene background fields and template media variables accept URLs directly. upload_asset is only needed when the media isn't publicly reachable or a stable asset ID is preferred.
A few decisions worth knowing about as a user:
Draft-by-default. Every render path defaults to render_mode: "draft" (Synthesia test: true) — free, watermarked, no quota. final must be requested explicitly.
Server-side validation. Mismatched template variable names, malformed script tags, and disallowed asset content types are caught locally before a request reaches Synthesia, so failures arrive instantly with the exact fix instead of after a wasted render.
Traceability. Every created video gets a callbackId (auto-stamped mcp/yyyy-mm-dd/title-slug if you don't supply one). Useful for spotting MCP-originated videos in a shared workspace and for the planned Phase 4 webhook integration.
Token-frugal responses. Tools return curated fields, not raw API payloads, to keep your context window healthy across long workflows.
Logging stays out of the way. All logs go to stderr (stdout is reserved for the MCP protocol). The API key is registered with a redactor so it can never accidentally appear in a log line.
Rate-limit aware. On HTTP 429, the server reads RateLimit-Reset and retries once after the indicated wait (capped). Synthesia Enterprise's tier limits are generous enough that you'll rarely see this.
No waiting/polling tool by design. Renders can take minutes; blocking a chat turn that long is worse than a quick check-in. Use get_video when you're curious.
Hosted-readiness without speculation. The credential layer is isolated behind a CredentialProvider interface; the tool registration is transport-agnostic. Switching to a hosted Streamable HTTP deployment with OAuth 2.1 later is a contained swap, not a rewrite.
src/
index.ts # entry: wires credentials → client → tools → stdio transport
credentials.ts # CredentialProvider interface + EnvCredentialProvider
config.ts # local config loading (custom avatars/voices, defaults)
catalog-loader.ts # reads catalog/*.json
logger.ts # stderr-only logger with secret redaction
errors.ts # SynthesiaMcpError + error code enum
synthesia/
client.ts # HTTP client: auth, two hosts, 429 retry, error mapping
types.ts # minimal API response types
util/
escape.ts # templateData text entity escaping
script-tags.ts # break/sub tag validator
tooling.ts # ok/fail envelopes, guard wrapper, callbackId stamping
tools/
discovery.ts # list_avatars, list_voices
templates.ts # list_templates, get_template
videos.ts # create_video, create_video_from_template, get_video, list_videos, update_video, delete_video
assets.ts # upload_asset, upload_script_audio
catalog/
avatars.json # seed snapshot; regenerate with npm run refresh-catalog
voices.json # seed snapshot
scripts/
refresh-catalog.mjs # regenerates the catalog files from docs.synthesia.io
test/
smoke.mjs # offline smoke test (no API key required)npm install
npm run build # tsc → dist/
npm run smoke # offline: spawns the built server, calls list_avatarsThe smoke test verifies all 12 tools are registered and that list_avatars returns catalog data — without making network calls, so no API key is required.
Create or edit a module in src/tools/.
Define a zod schema for the inputs (it's both the validator and the source of the JSON Schema advertised to clients).
Wrap the handler with guard(name, handler) from util/tooling.ts to get consistent error envelopes.
Return data via ok({...}) — keep the payload curated, not the raw API response.
Register the module from src/index.ts.
Add the tool name to EXPECTED_TOOLS in test/smoke.mjs.
The MCP authorization specification draws a clean line between transports:
stdio (local): retrieve credentials from the environment, no OAuth flow.
Streamable HTTP (remote): OAuth 2.1 with PKCE, dynamic client registration, etc.
This server ships only the stdio path. The CredentialProvider interface in credentials.ts is the seam: a future hosted variant adds an HTTP transport in index.ts and a session-scoped provider implementing the same interface — no tool code changes. The Synthesia client always reads the key through the interface, never directly from process.env.
All failures surface as SynthesiaMcpError instances. The guard() wrapper turns them into MCP tool results with isError: true and the structured { error: { code, message, remediation, details? } } envelope. Error codes are deliberately few and category-level:
auth_error — 401/403 from Synthesia
config_error — missing env var or malformed config file
validation_error — local pre-flight failed; nothing was sent to Synthesia
not_found — 404 from Synthesia
rate_limited — 429 after retry
moderation_rejected — Synthesia content moderation
file_error — local file unreadable, download failed, wrong type
upstream_error — everything else from the Synthesia side
remediation is written for the LLM to self-correct in the next turn — concrete, specific, with the exact field name or available values where possible.
npm run refresh-catalog fetches https://docs.synthesia.io/reference/avatars.md and …/voices.md, parses the markdown tables, and overwrites the JSON catalogs. The refresh script is intentionally simple: no schema migrations, no diffs — just replace and commit.
This server is the MCP layer of a two-layer plan. Things deliberately not in v1:
Phase 4: webhook tools (Synthesia fires video.completed / video.failed with captions, thumbnails, and your callbackId in the payload). Requires a public HTTP receiver; polling via get_video suffices for interactive authoring.
Phase 5: translations, XLIFF export/import, dubbing — the localization surface is substantial and earns its own milestone.
Phase 6: hosted Streamable HTTP deployment with OAuth 2.1, multi-account profiles, evals.
On top of this server, a separate Claude skill handles the educational workflow: eliciting audience, learning objectives, target duration (translated into a word-count budget), tone, and pedagogical structure; co-writing the script scene by scene; then delegating execution to these tools. The skill is opinionated and customizable per user; this server stays plug-and-play.
MIT.
Create a Synthesia avatar video from one or more scenes (avatar + background + script each). Rendering is asynchronous: this returns a videoId immediately; check progress later with get_video. DEFAULTS TO A FREE DRAFT (watermarked test render); pass render_mode='final' only when the user explicitly wants to spend quota on a final render. For visually rich layouts (on-screen text, images), prefer create_video_from_template with a STUDIO-designed template.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Video title (shown in the workspace and on the share page). | |
| description | No | ||
| scenes | Yes | Scenes in order. Each needs avatar, background, and scriptText (or scriptAudioId + scriptLanguage). | |
| aspectRatio | No | Default 16:9 (or the server config default). | |
| soundtrack | No | Optional stock soundtrack. | |
| ctaSettings | No | Call-to-action button on the share page. | |
| visibility | No | Default private. | |
| folderId | No | Optional STUDIO folder UUID to file the video under. | |
| callbackId | No | Traceability tag echoed in webhooks; auto-stamped if omitted. | |
| render_mode | No | draft (DEFAULT): free test render with a watermark, does not consume the Synthesia quota — use for all iteration. final: full-quality render that COUNTS AGAINST the account's video quota — only use when the user explicitly approves a final render. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses asynchronous rendering (returns videoId immediately), default draft render (watermarked, free), and that final render consumes quota. Could mention error handling or rate limits, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences with no wasted words. Front-loaded with the main purpose and key behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters and nested objects, the description provides a high-level overview covering async, quota, and sibling alternative. It could include expected output or common errors, but is reasonably complete given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 90% (high), so baseline is 3. The description adds valuable context beyond the schema: async behavior, draft/final distinction, and alternative tool advice. It doesn't repeat param details but provides complementary guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Synthesia avatar video from one or more scenes' with specific verb and resource. It distinguishes from the sibling tool create_video_from_template by noting when to prefer that alternative for visually rich layouts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use this tool vs create_video_from_template, and clear instructions on render_mode: default to draft for iteration, use final only on explicit user approval. Also mentions asynchronous workflow and to check progress with get_video.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Synthesia video from a STUDIO template by substituting its variables (templateData). The server fetches the template first and validates every templateData key against its declared variables — variable names are case-sensitive. Text values are HTML-entity-escaped automatically (Synthesia requirement); media variables accept an uploaded asset ID or a URL. DEFAULTS TO A FREE DRAFT (watermarked); pass render_mode='final' only on explicit approval. Returns a videoId immediately; check progress with get_video.
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | Template ID (see list_templates). | |
| templateData | Yes | Variable name → value. Keys are CASE-SENSITIVE and must match the template's variables exactly. | |
| title | No | Defaults to the template title. | |
| description | No | ||
| visibility | No | ||
| ctaSettings | No | ||
| brandKitId | No | 'workspace_default' behavior if unset; 'no_brand_kit' to disable branding; or a custom brand kit UUID. | |
| folderId | No | ||
| callbackId | No | Auto-stamped if omitted. | |
| escapeText | No | Default true: HTML-escape string values (recommended). Set false ONLY if you are passing pre-escaped entities. | |
| render_mode | No | draft (DEFAULT): free test render with a watermark, does not consume the Synthesia quota — use for all iteration. final: full-quality render that COUNTS AGAINST the account's video quota — only use when the user explicitly approves a final render. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details critical behaviors: server-side validation, case sensitivity, HTML escaping, media handling, draft default, and async return. Missing rate limits or error handling, but sufficient for operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: front-loaded purpose, then key details in separate sentences. Slightly long but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-param tool with nested objects and no output schema, the description covers the core flow: template validation, variable substitution, draft default, return of videoId, and follow-up with get_video. Lacks error scenarios but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains templateData substitution, case sensitivity, media asset types, render_mode semantics, and brandKitId options. Some params like folderId lack extra context, but key parameters are well-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'Synthesia video from a STUDIO template', distinguishing it from sibling tools like 'create_video' which likely creates from scratch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on default draft mode and when to use 'final' with approval. Implicitly differentiates from other tools by focusing on templates, but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PERMANENTLY delete a video from the Synthesia account. Destructive and double-gated: the call is refused unless confirm=true is passed. Only set confirm=true after the user has explicitly confirmed deletion of this specific video.
| Name | Required | Description | Default |
|---|---|---|---|
| videoId | Yes | ||
| confirm | No | Must be true to actually delete. Leave unset to get the video's details for confirmation first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the destructiveHint annotation by explaining the double-gated mechanism, permanence, and the need for explicit user confirmation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with critical information. No fluff. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple two-parameter destructive tool. It explains the action, the guard, and correct usage. No gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to the confirm parameter (must be true for deletion, can be left unset for review). For videoId, no addition beyond schema, but schema coverage is 50% and the description compensates well for the confirm parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: permanently delete a video. It distinguishes from siblings like create_video, update_video, get_video by specifying the destructive and final nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: the tool is refused unless confirm=true, and confirm should only be set after user confirmation. It also implies that leaving confirm unset can be used to get details first. This tells when and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Synthesia template by ID, including its full variable list. Call this before create_video_from_template to see exactly which templateData keys are expected (variable names are case-sensitive).
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | Template ID (from list_templates or the STUDIO templates page). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool returns the full variable list and that variable names are case-sensitive, which aids behavior prediction. The readOnlyHint annotation is consistent, so no contradiction. No mention of rate limits or auth, but acceptable for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The critical information is front-loaded: what the tool does and why it's useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description fully covers purpose, usage, and return value implications. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (templateId described). The description adds context beyond the schema: clarifies where to get the ID ('from list_templates or the STUDIO templates page') and emphasizes case-sensitivity of variable names, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a single Synthesia template by ID, including its full variable list.' This is a specific verb-resource combination and distinguishes from sibling tools like list_templates (listing) and create_video_from_template (using the template).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Call this before create_video_from_template to see exactly which templateData keys are expected,' guiding the agent on proper usage sequence. Does not explicitly mention when not to use it, but the context is sufficient for differentiation from list_templates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a Synthesia video by ID: render status (in_progress / complete / error / rejected), and once complete, a time-limited download URL, duration, and thumbnail. Use this to check on videos created with create_video or create_video_from_template. Renders take minutes — do not call this in a tight loop.
| Name | Required | Description | Default |
|---|---|---|---|
| videoId | Yes | Video ID returned by a create tool or list_videos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important behavioral traits: the download URL is time-limited, the status can be one of four specific values, and renders take minutes. This adds significant context for an agent's decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences plus a tersely worded warning. Every sentence serves a distinct purpose (what, when, and warning). No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description adequately covers all necessary aspects: the ID source, response fields, status states, and a usage caveat. It is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single parameter 'videoId' with a description ('Video ID returned by a create tool or list_videos'). The description does not add any additional meaning or constraints beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a Synthesia video by ID, enumerates the returned fields (status, download URL, duration, thumbnail), and directly associates its use with videos created by create_video or create_video_from_template. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (after creating a video) and warns against polling in a tight loop ('Renders take minutes — do not call this in a tight loop'). This provides actionable guidance beyond a simple purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Synthesia avatars available for video creation: stock avatars from a bundled catalog snapshot, plus any custom/personal avatars registered in the local server config. Returns avatar IDs to use as the avatar field in create_video. Note: Synthesia has no API endpoint for avatar discovery, so the stock list is a snapshot and may be incomplete; custom avatar IDs must be registered in the config file (copied from STUDIO via the avatar's three-dot menu → Copy ID).
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Case-insensitive substring match on the avatar name. | |
| gender | No | Filter by gender as listed in the catalog (e.g. 'Male', 'Female'). | |
| version | No | Filter by avatar model version, e.g. 'EXPRESS-1' or '3'. | |
| source | No | Limit to stock catalog or config-registered custom avatars. Default: all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that stock list is a snapshot and may be incomplete, and custom IDs must be registered in config, adding value beyond readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose and usage, but includes necessary context; slightly lengthy but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a list tool: explains return values (avatar IDs), usage in create_video, and limitations of stock and custom sources, compensating for lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full parameter descriptions (100% coverage), but description adds context for obtaining custom avatar IDs, which enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists Synthesia avatars (stock and custom) for video creation, distinguishing from sibling tools like list_voices or list_templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (before creating video), notes limitations (stock snapshot incomplete, custom IDs from STUDIO), and directs to use IDs in create_video.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Synthesia video templates (created in STUDIO) with their IDs and variable names. Templates are the way to produce rich, designed videos via the API — use create_video_from_template with a templateId from this list. Paginated: pass the returned nextOffset as offset to fetch more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Templates per page (default 20, max 100). | |
| offset | No | Pagination offset; use nextOffset from the previous call. | |
| source | No | Filter by origin: 'workspace' (your own templates) and/or 'synthesia' (stock). Default: both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds context about templates being created in STUDIO and their role in producing rich videos. No contradiction between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the purpose and providing critical usage context. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains that the response contains IDs and variable names. Pagination is covered, and all three parameters are well-documented in the schema. The description is complete for a list operation with read-only annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds value by explaining pagination (nextOffset) and default filtering behavior (source defaults to both), going beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists templates with IDs and variable names, and distinguishes from sibling tools like create_video_from_template by explaining that templates from this list are used with that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to get template IDs for video creation) and describes pagination behavior via nextOffset. It does not explicitly state when not to use, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List videos in the Synthesia account (created via API or STUDIO), newest context first. Paginated: pass the returned nextOffset as offset to fetch more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Videos per page (default 20, max 100). | |
| offset | No | Pagination offset; use nextOffset from the previous call. | |
| source | No | Filter by origin. Default: all sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds ordering and pagination details beyond the readOnlyHint annotation. It does not cover potential errors or rate limits, but for a read operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The purpose is front-loaded, and the pagination instruction is directly useful. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core behavior and pagination but does not describe the output format or fields. However, for a simple list tool with no output schema, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds value by clarifying offset usage ('pass the returned nextOffset') and limit default (20). This provides practical meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List videos in the Synthesia account' with a specific verb and resource. It distinguishes from sibling tools like list_avatars, list_templates, etc., by focusing on videos and mentioning ordering by newest context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to list videos) and provides pagination guidance, but does not explicitly mention when not to use it or compare to alternatives like search or filter. However, the context is clear for a basic list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Synthesia text-to-speech voices: stock voices from a bundled catalog snapshot plus custom voices registered in the local server config. Returns voice IDs for the avatarSettings.voice field in create_video. IMPORTANT: voices are optional — if omitted, Synthesia automatically uses its recommended voice for the chosen avatar, which is a good default. The stock list is a snapshot and may be incomplete.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Case-insensitive substring match on the voice name (e.g. 'Hope'). | |
| language | No | Substring match on language name or ICU code (e.g. 'English', 'en-GB'). | |
| gender | No | Filter: 'm' or 'f' as listed in the catalog. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation and adds context: it lists both stock and custom voices, and explains the output is voice IDs for create_video. It also discloses the snapshot nature, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loading the main purpose. Every sentence adds value: purpose, output usage, and an important note. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (3 optional parameters, no required), the description fully covers what the tool does, what it returns, and caveats. The lack of output schema is compensated by describing the return value's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters have descriptions. The tool description does not add new information about individual parameters beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states explicitly 'List Synthesia text-to-speech voices', specifying the verb and resource. It distinguishes from sibling tools like list_avatars by focusing on voices, and clarifies the two types of voices (stock and custom).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: voices are optional and if omitted, the system uses a recommended voice. It also warns that the stock list is a snapshot and may be incomplete, setting proper expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a video's title, description, visibility, or call-to-action button. The main use is flipping visibility to 'public' to activate the Synthesia share page for a finished video.
| Name | Required | Description | Default |
|---|---|---|---|
| videoId | Yes | ||
| title | No | ||
| description | No | ||
| visibility | No | 'public' activates the share page for anyone with the link. | |
| ctaSettings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses that changing visibility to 'public' activates the share page, but does not mention any other behavioral traits (e.g., whether updates are immediate, require authentication, or have irreversible effects). The description is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences. It front-loads the key purpose and includes a specific use case. No extraneous information is present, though the second sentence could be seen as a bonus rather than essential. Overall, it is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should provide more complete behavioral context. It does not explain what happens after an update (e.g., return value, side effects on other metadata), prerequisites (e.g., video must exist), or handling of complex parameters like ctaSettings. The description leaves significant gaps for an agent to operate effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only visibility has a description), yet the tool description merely rephrases the available fields without adding meaningful guidance on parameter usage. For instance, it does not explain that ctaSettings requires both label and url or that videoId is a required identifier. The description adds minimal value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool updates video metadata (title, description, visibility, call-to-action button). It distinguishes itself from sibling tools like create_video and delete_video by focusing on updates. The specific use case of flipping visibility to 'public' to activate the Synthesia share page provides clear, actionable purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for existing videos and gives a primary use case (making a video public). However, it does not explicitly state when to avoid using this tool or provide comparisons to similar siblings like create_video. The agent is left to infer usage context from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image or video to Synthesia and get back an asset ID, usable as a scene background in create_video or as a media variable value in create_video_from_template. Accepted types: image/jpeg, image/png, image/svg+xml, video/mp4, video/webm (GIF and WebP are rejected by Synthesia). Provide a local filePath or a url. TIP: backgrounds and media variables also accept URLs directly — uploading is only needed for non-public files or when a stable asset ID is preferred. For media variables, match the aspect ratio of the element being replaced to avoid stretching.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | No | Absolute path to a local file on the machine running this MCP server. | |
| url | No | Alternatively, an https URL the server downloads and uploads. | |
| contentType | No | Inferred from the file extension when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return value (asset ID), accepted types, and typical usage. Could improve by specifying behavior when both filePath and url are provided, or error handling (e.g., file not found, size limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with logical flow: purpose, accepted types, inputs, usage tips. No redundant sentences; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple upload tool with no output schema, description adequately explains return and usage. Could mention size limits or authentication requirements for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with decent descriptions. Description adds value by listing accepted MIME types (including rejected GIF/WebP) and reiterating that contentType can be inferred. Provides extra context about use in media variables, but could clarify behavior when both filePath and url are present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Upload' and resource 'image/video asset'. Distinguishes from siblings by explaining that uploaded assets are used in create_video and create_video_from_template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool versus direct URLs in backgrounds/media variables. Lists accepted and rejected content types, and provides a tip about aspect ratio matching for media variables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload pre-recorded narration audio (mp3 / audio/mpeg only) to use INSTEAD of text-to-speech: pass the returned ID as scriptAudioId (with scriptLanguage) in a create_video scene. NOTE: Synthesia processes uploaded script audio asynchronously — if video creation fails right after uploading with an error about the asset, wait a moment and retry; processing must complete before the audio is usable.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | No | Absolute path to a local .mp3 file. | |
| url | No | Alternatively, an https URL to an mp3 the server downloads and uploads. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions asynchronous processing of uploads and advises retrying if video creation fails, which is valuable context. However, it lacks details on authentication requirements, rate limits, or file size constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loads the core purpose. It avoids unnecessary details while including critical usage guidance. Could be slightly more structured but is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description provides most needed context: what to do with the returned ID and the async nature. However, it does not explicitly describe the return format or error handling, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the two parameters (filePath and url). The description adds minimal extra meaning beyond explaining they are alternative ways to provide the file. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: upload pre-recorded narration audio (mp3 only) to be used instead of text-to-speech. It explains the usage flow (pass the returned ID as scriptAudioId in create_video), distinguishing it from generic asset uploads like upload_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool (when pre-recorded audio is available instead of TTS) and provides a key usage note about asynchronous processing and retrying on failure. It does not explicitly state alternatives or when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0create_videocreate_video_from_templatedelete_videoget_templateget_videolist_avatarslist_templateslist_videoslist_voicesupdate_videoupload_assetupload_script_audioEach tool targets a distinct resource or action: two creation methods for different use cases, dedicated listing tools for each entity type, and specific operations for deletion, updating, and uploading. No two tools have overlapping purposes; descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern using lowercase with underscores (e.g., create_video, list_templates, upload_asset). Only create_video_from_template uses a slight variant ('from_template'), but it remains within the pattern and is clear.
With 12 tools, the set is well-scoped for a video creation service. It covers creation, retrieval, listing, updating, deletion, and asset uploads without being excessive or sparse.
The tool surface covers the core video lifecycle: create (two ways), read status, list, update metadata, delete, plus supporting operations for templates, avatars, voices, and asset/audio uploads. Missing features (e.g., custom avatar management) are intentionally handled via configuration, not gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create AI talking-avatar marketing videos from a script or product idea.
Create and manage cinematic AI video renders through the Future Video Studio Agent API.
Generate AI talking-head videos with custom characters and voices.
Create and edit AI videos from chat: plan shots, generate scenes, and export stories and ads.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/keithazz/synthesia-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
