Generate images, video, character portraits, lip-sync video, music and speech from an MCP client. Connect with OAuth, reuse your private media, set a Gem spending limit and retrieve durable generation results.
Add this remote Streamable HTTP server to an MCP client that supports browser-based OAuth. There is no API key to copy: the client starts a standard OAuth sign-in and stores its own access and refresh tokens.
Server URL
https://mcp.letsgen.app/mcp
Start the sign-in from the client. An authorization URL forwarded from another machine will not complete, because the request is bound to that client's PKCE challenge and loopback callback.
Claude Code
claude mcp add --transport http letsgen https://mcp.letsgen.app/mcp
The client performs OAuth Authorization Code with S256 PKCE and manages access and refresh tokens. Account cookies and Lets Gen API keys are not substitutes for an OAuth access token.
Scope
Access
mcp:read
Required for the MCP connection: account, capability, owned-media and generation reads.
mcp:generate
Additional permission to import media or call any of the six Create tools. Request it together with mcp:read.
mcp:canvas:write
Additional permission to update owned Canvas projects. Read access is account-wide for owned projects; mcp:generate does not grant Canvas editing.
OAuth discovery is available at the protected-resource metadata URL. Its authorization server is Lets Gen. Access tokens are bound to the MCP resource URL; tokens for another environment are not interchangeable.
The server accepts POST /mcp. Let the SDK negotiate the protocol, initialize the connection and supply protocol headers. The adapter supports standard 2025-11-25 initialization and 2026-07-28 discovery. The JSON examples below are tools/call parameters after initialization, rather than complete HTTP requests.
Manage or revoke clients on MCP connections. Revocation blocks subsequent requests. Outputs and imported references stay private to the connected personal account unless you publish them separately in Lets Gen.
02 / Reference
17 public tools
Call list_generation_capabilities before choosing generation inputs. Its inputs, options and model-specific models[].capabilities describe current accepted values. Discovery does not promise that every model will be available to your account when you submit.
Read an owned Canvas project and its editing guide before changing its graph.
Parameters
projectId: nonempty string (≤160 characters).
Result
{ project, cursor, guide, canvasUrl }. guide includes workflow instructions and graphSchema. This does not create a session, approve storyboard images or start generation.
get_canvas_project
mcp:read
Read the current owned Canvas graph, revision and generation statuses.
Parameters
projectId: nonempty string (≤160 characters).
Result
{ project, cursor, canvasUrl }. Use the current revision for updates and cursor for waiting.
update_canvas_project
mcp:canvas:write
Save an owned Canvas graph using revision compare-and-swap, preserving unrelated work.
Parameters
projectId: nonempty string (≤160 characters); revision: integer ≥0; graph: object matching the schema returned by connect_canvas_project; title?: string (1–120 characters).
Result
{ project, cursor, canvasUrl }. On a stale revision, reread and reconcile instead of resubmitting a stale graph with a newer revision. Generation remains a creator-reviewed action in Canvas.
wait_canvas_project
mcp:read
Wait for graph-revision or generation-status changes without starting or recovering generation.
{ project, cursor, changed, canvasUrl }. changed:false means the wait timed out, not that generation completed. Status changes can occur without a graph revision change.
list_generation_capabilities
mcp:read
Discover the six generators, their current input definitions and model-specific options.
Parameters
{} — no arguments.
Result
{ capabilities: [...] }. Each entry includes capability, appId, outputKind, availability, inputs and options. Image/video entries also include models.
get_account
mcp:read
Read your Gem balance and subscription plan.
Parameters
{} — no arguments.
Result
{ gemBalance: number, plan: string, generationAvailable: boolean }. generationAvailable reflects a positive balance; Create still checks price, model access and account eligibility.
list_media_assets
mcp:read
Browse ready, visible media owned by the connected account.
{ assets: [...], nextCursor: string | null }. Each asset has id, kind, state and media metadata. Hidden one-shot imports are not listed; retain their returned id.
get_media_asset
mcp:read
Read one owned asset before using it as a reference.
Parameters
assetId: nonempty string (≤160 characters).
Result
{ asset: {...} }. The asset identifier is asset.id; check kind and state === ready. Available content and preview links depend on the asset.
import_media_from_url
mcp:generate
Import one public HTTPS file as private, temporary one-shot media.
prompt is required (≤20,000 characters). referenceImages holds up to ten owned image IDs, subject to the selected model's lower limit. outputCount is 1–4. Some editing models require sourceImage. Use current model-specific input, ratio and resolution options.
create_video_generation
mcp:generate
Generate video from text or an owned starting image.
For image-to-video, sourceImage is an owned ready image ID, not a URL. Choose a model whose capabilities.inputs includes first-frame. duration is a string such as "6"; ratio, resolution and audio are model-specific. A supplied sourceImage determines image-to-video mode.
create_character_image
mcp:generate
Generate an original character portrait; this does not create a chat Character.
appearance is required (≤2,000 characters); outputCount is 1–4. referenceImages accepts at most one owned image. Reference images and animaLoras cannot be combined; without a reference, a compatible style selection is required.
create_lip_sync_video
mcp:generate
Animate an owned image or existing Character using owned audio.
drivenAudio is required. Provide sourceImage or an existing character ID. Choose model from talking-head-models. Infinitalk: up to 15s, 480p/720p. OmniHuman 2.0: MP3/WAV under 15 MB, 4–300s, fixed 720p, 60 Gems per started audio second.
create_music_generation
mcp:generate
Generate music from a prompt, optionally using an owned cover audio reference.
Inputs depend on musicMode. Simple mode uses a song-idea prompt (up to 3,000 characters). Advanced mode requires style and title, with prompt carrying lyrics (up to 5,000 characters) when vocals are requested. coverAudio is optional; sound-effect mode has separate options. Discover accepted fields and option keys first.
create_voice_speech
mcp:generate
Generate speech using an existing authorized voice or a consented owned reference recording.
prompt is required (≤2,000 characters). Use a visible voiceProfileId, or provide an owned referenceAudio with referenceConsent: confirmed and no voiceProfileId. Reference recordings must pass voice-reference validation. Model-specific speech tuning fields are described by discovery. MCP does not manage or list voice profiles.
The catalog contains four Canvas tools, six generation tools and seven account, discovery, media and history tools. MCP does not expose publishing, deletion, checkout, Character profile creation or voice-profile management. create_character_image creates portraits; create_voice_speech uses an authorized voice or an owned, consented reference recording.
For Canvas, connect and read its graph schema before updating. Editing does not start paid generation or approve storyboard images: the creator reviews and generates in Canvas. See the Canvas handbook returned by the connection guide.
03 / Reference
Create parameters
All six Create tools use the same three top-level parameters:
Parameter
Type & requirement
Meaning
request
Required object
Values for the selected generator. Do not wrap them in draft or send an appId or definitionVersion.
idempotencyKey
Required string, 12–160 characters
Letters, digits, ., _, : and -. Keep the same key and request values when retrying one logical generation.
maxGemCost
Optional integer ≥0
Maximum total Gems approved for this Create call. The example requires an explicit limit. Omitting it removes this caller-provided price cap.
Asset inputs such as sourceImage, drivenAudio and referenceImages use owned asset IDs, not file bytes or media URLs. Import a public URL first. Selection options such as duration are strings; outputCount is an integer and prompt optimization fields are booleans.
Generator request field reference
These fields come from the shared built-in generator definitions. Conditional fields only apply when supported by the selected model or workflow; live capability discovery remains authoritative. Internal routing controls are omitted.
{"type":"asset-uploader-list","key":"referenceImages","required":false,"kind":"image","minCount":0,"maxCount":16,"purpose":"Visual references (each model has its own limit)"}
{"type":"image-uploader","key":"sourceImage","required":true,"purpose":"Source image to edit","visibleWhen":{"key":"model","equals":"ideogram-v4.5-edit"}}
For video, choose a compatible combination from models[].capabilities: inputs, aspectRatios, durations, resolutions, audio and audioRequired. Union lists under options do not mean every combination works for every model.
04 / Reference
Results & polling
Read machine-readable data from reply.structuredContent.result. A successful tool result also contains a short text summary; it is not the generation state. Business errors use isError: true and structuredContent.error. JSON-RPC and OAuth failures may instead be transport or protocol errors.
All example IDs, timestamps, prices, balances and media URLs on this page are illustrative fixtures, not a live generation transcript or a price promise.
Create returns a durable generationId immediately. Poll get_generation using that ID. Suggested client polling: once every five seconds with a ten-minute local deadline; these are example client settings, not server completion guarantees.
Generation outputs expose asset.assetId and a ready media url. Asset-list, asset-detail and import tools return asset.id instead. Pass either identifier as sourceImage when it is an owned image. Treat direct media links as share-sensitive capability URLs and observe account retention limits.
05 / Reference
Gems & spending limits
The platform validates the request, checks ownership and eligibility, calculates its current price, and reserves Gems before starting a generation. Pricing depends on the model and settings, including output count, duration, resolution and audio where applicable.
gemCost is the quoted total for the accepted run. settledGems is the amount settled so far; it can be zero while work is pending.
remainingGems is the current account balance returned with Create and get_generation. Generation-history entries omit it.
A final run settles successful outputs and releases unused reservations for failed or cancelled outputs. Check final status and settledGems, including partial outcomes.
Read tools do not create a new generation reservation. Media import does not itself reserve generation Gems; storage and retention restrictions still apply.
There is no separate public quote tool. Image-model creditCost metadata is guidance, not a guaranteed total for an arbitrary request. Use an approved maxGemCost; if the authoritative price exceeds it, Create returns PRICE_CHANGED without charging for that rejected submission.
Illustrative over-budget result
{
"isError": true,
"content": [
{
"type": "text",
"text": "The current price is above the requested Gem limit. Nothing was charged."
}
],
"structuredContent": {
"error": {
"code": "PRICE_CHANGED",
"message": "The current price is above the requested Gem limit. Nothing was charged.",
"retryable": false
}
}
}
Repeating the same key and equivalent request returns the same generation with created: false, rather than purchasing another run. Changing the request under that key produces IDEMPOTENCY_CONFLICT. A new key represents a new billable request; never generate one automatically to recover from an uncertain response.
Read account pricing and the Gems guides for purchasing and balance information. The values in this reference are not a fixed Gem or currency tariff.
06 / Reference
Complete image-to-video walkthrough
Start with an image you own, create one video, and keep the generation ID until it finishes. You need both mcp:read and mcp:generate, an eligible account with enough Gems, and an explicitly approved spending limit.
Discover the account and video inputs
Call get_account and list_generation_capabilities. Find video_generation, check its availability and select a model with first-frame in capabilities.inputs.
Get an owned starting-frame ID
Use list_media_assets with kind: "image", then get_media_asset to confirm it is ready. Alternatively import a direct public HTTPS image:
Save structuredContent.result.asset.id. Import downloads must be public HTTPS, without credentials or a custom port; redirects and destination addresses are checked. Limits are 20 MiB for images, 25 MiB for audio and 64 MiB for video, with additional file-type and inspection checks. A share-page URL or local filesystem path is not a media file.
One-shot imports are temporary, hidden from the regular library list, and currently use a seven-day retention period. Keep the returned ID. Import has no idempotency key; repeating it may create another asset.
Create once, within the approved budget
Use the imported or selected ID as request.sourceImage. The following model settings are an example supported by the current source catalog; rediscover live options before submitting. The 120-Gem cap is an illustrative limit, not a price quote.
Create parameters
{
"name": "create_video_generation",
"arguments": {
"request": {
"mode": "image-to-video",
"sourceImage": "asset_example_image",
"model": "grok-imagine",
"prompt": "A gentle breeze moves the leaves. The camera slowly pushes in. Preserve the subject and composition.",
"duration": "6",
"ratio": "16:9",
"resolution": "480p",
"audio": "on"
},
"idempotencyKey": "example-video-20261023-001",
"maxGemCost": 120
}
}
Poll the returned generation ID
Read structuredContent.result.generation.generationId. Call get_generation until a terminal state. Keep the same generation ID after a polling failure; do not submit another Create.
Use the completed video
Find a successful output whose asset.kind is video. Its asset.url is the delivery link and asset.assetId is the owned asset ID. Inspect gemCost, settledGems and remainingGems for accounting.
07 / Reference
Runnable Node.js example
This example discovers a compatible video model, imports or checks an image, creates one video with a Gem cap, and polls to a terminal result. The same exported function can use an already connected MCP SDK client whose OAuth provider handles browser consent and refresh.
For the standalone CLI, supply an OAuth access token issued for this production MCP resource through an authorized OAuth client. It is not an API key. The fixed-token example does not perform browser login or token refresh; use an SDK authProvider for interactive applications. Keep tokens out of source files, URLs and logs.
Environment inputs · running this can spend Gems
# Supply the OAuth token through your secure environment, not this file.
# LETSGEN_ACCESS_TOKEN must already be set.
export LETSGEN_ASSET_ID='YOUR_READY_OWNED_IMAGE_ID'
# Or set LETSGEN_IMAGE_URL instead of LETSGEN_ASSET_ID.
export LETSGEN_MAX_GEMS='YOUR_APPROVED_INTEGER_LIMIT'
export LETSGEN_IDEMPOTENCY_KEY='YOUR_UNIQUE_GENERATION_KEY'
# Optional: LETSGEN_VIDEO_MODEL, chosen from capability discovery.
node letsgen-image-to-video.mjs
The script prints a prepared checkpoint before Create and an accepted checkpoint with the generation ID. Save them. To recover from an uncertain Create response, reuse the exact saved arguments; reimporting a URL produces a different asset ID and can cause an idempotency conflict. A local polling timeout or closing the client does not cancel the server-side job.
Read the complete example source
letsgen-image-to-video.mjs
/**
* Lets Gen MCP image-to-video example. Node.js 22+.
* Install @modelcontextprotocol/sdk@1.30.0 to use the command-line entry point.
* Running the example can import media and spend Gems up to maxGemCost.
* No retries of imports or Create are performed automatically.
*/
export async function runImageToVideo(client, options, dependencies = {}) {
const { assetId, imageUrl, maxGemCost, idempotencyKey, modelKey, signal } = options;
if (Boolean(assetId) === Boolean(imageUrl)) throw new Error("Provide exactly one owned assetId or public imageUrl.");
if (!Number.isSafeInteger(maxGemCost) || maxGemCost < 0) throw new Error("Provide an approved integer maxGemCost of zero or more.");
if (typeof idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{12,160}$/.test(idempotencyKey)) {
throw new Error("Provide an idempotencyKey of 12–160 letters, digits, dots, underscores, colons or hyphens.");
}
const pollIntervalMs = options.pollIntervalMs ?? 5000;
const timeoutMs = options.timeoutMs ?? 600000;
if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0 || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
throw new Error("Polling interval and timeout must be positive milliseconds.");
}
const sleep = dependencies.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
const now = dependencies.now ?? Date.now;
const report = dependencies.onProgress ?? (() => {});
async function call(name, args = {}) {
signal?.throwIfAborted();
const reply = await client.callTool({ name, arguments: args });
const structured = reply.structuredContent;
if (reply.isError || structured?.error) {
const failure = structured?.error;
const error = new Error(failure?.message ?? `Tool ${name} could not complete the request.`);
error.code = failure?.code;
error.retryable = failure?.retryable ?? false;
throw error;
}
if (!structured || !("result" in structured)) throw new Error(`Tool ${name} returned no structured result.`);
return structured.result;
}
const account = await call("get_account");
if (!(account.gemBalance > 0)) throw new Error("This account needs a positive Gem balance before creating video.");
const { capabilities } = await call("list_generation_capabilities");
const video = capabilities.find((entry) => entry.capability === "video_generation");
if (video?.availability !== "available") throw new Error("Video generation is currently unavailable.");
const model = video.models?.find((entry) =>
(!modelKey || entry.key === modelKey) && entry.capabilities?.inputs?.includes("first-frame")
);
const settings = model?.capabilities;
if (!settings?.durations?.length || !settings.resolutions?.length || !settings.aspectRatios?.length) {
throw new Error("No matching first-frame model with documented duration, resolution and ratio options was found.");
}
const { asset } = imageUrl
? await call("import_media_from_url", { url: imageUrl, kind: "image", originalName: "starting-frame.png" })
: await call("get_media_asset", { assetId });
if (!asset?.id || asset.kind !== "image" || asset.state !== "ready") {
throw new Error("The starting frame must be a ready image owned by this account.");
}
const request = {
mode: "image-to-video",
sourceImage: asset.id,
model: model.key,
prompt: options.prompt ?? "A gentle breeze moves the leaves. The camera slowly pushes in. Preserve the subject and composition.",
duration: String(settings.durations.includes(6) ? 6 : settings.durations[0]),
ratio: settings.aspectRatios.includes("16:9") ? "16:9" : settings.aspectRatios[0],
resolution: settings.resolutions.includes("480p") ? "480p" : settings.resolutions[0],
audio: settings.audioRequired ? "on" : "off",
};
const createArguments = { request, idempotencyKey, maxGemCost };
// Save this checkpoint. After an interrupted Create, reuse these exact
// arguments; reimporting the URL would produce a different sourceImage ID.
report({ event: "prepared", sourceAssetId: asset.id, createArguments });
const accepted = await call("create_video_generation", createArguments);
let generation = accepted.generation;
if (!generation?.generationId) throw new Error("Create returned no generation ID.");
const generationId = generation.generationId;
report({ event: "accepted", generationId, created: accepted.created, gemCost: generation.gemCost });
const deadline = now() + timeoutMs;
const terminal = new Set(["succeeded", "partial", "failed", "cancelled"]);
while (!terminal.has(generation.status)) {
signal?.throwIfAborted();
const remaining = deadline - now();
if (remaining <= 0) {
throw new Error(`Polling timed out. The job may still be running; resume get_generation with generationId ${generationId}.`);
}
await sleep(Math.min(pollIntervalMs, remaining));
generation = (await call("get_generation", { generationId })).generation;
if (!generation || generation.generationId !== generationId) throw new Error("Polling returned an unexpected generation.");
report({ event: "progress", generationId, status: generation.status });
}
const outputs = (generation.outputs ?? []).filter((output) =>
output.status === "succeeded" && output.asset?.kind === "video" && output.asset.url
);
if (!["succeeded", "partial"].includes(generation.status) || !outputs.length) {
throw new Error(`Generation ${generationId} ended with ${generation.status}: ${generation.error?.message ?? "No ready video output."}`);
}
return { generation, outputs };
}
async function main() {
const env = process.env;
const accessToken = env.LETSGEN_ACCESS_TOKEN;
if (!accessToken) throw new Error("Set LETSGEN_ACCESS_TOKEN to an OAuth access token issued for https://mcp.letsgen.app/mcp.");
if (!env.LETSGEN_MAX_GEMS) throw new Error("Set LETSGEN_MAX_GEMS to your explicitly approved spending limit.");
const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
const client = new Client({ name: "letsgen-image-to-video-example", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(new URL("https://mcp.letsgen.app/mcp"), {
requestInit: { headers: { Authorization: `Bearer ${accessToken}` } },
});
try {
await client.connect(transport);
const result = await runImageToVideo(client, {
assetId: env.LETSGEN_ASSET_ID,
imageUrl: env.LETSGEN_IMAGE_URL,
maxGemCost: Number(env.LETSGEN_MAX_GEMS),
idempotencyKey: env.LETSGEN_IDEMPOTENCY_KEY,
modelKey: env.LETSGEN_VIDEO_MODEL,
}, { onProgress: (progress) => console.log(JSON.stringify(progress)) });
console.log(JSON.stringify(result, null, 2));
} finally {
await client.close();
}
}
if (typeof process !== "undefined" && process.argv[1]) {
const { pathToFileURL } = await import("node:url");
if (import.meta.url === pathToFileURL(process.argv[1]).href) {
main().catch((error) => {
console.error(error.message);
process.exitCode = 1;
});
}
}
The example is exercised against the actual MCP handler and local contract fixtures. It has not been presented as a paid provider run or a live production generation.
08 / Reference
Errors & recovery
Inspect structuredContent.error.code, message and retryable for tool errors. A retryable error is not permission to increase a spending limit or submit a duplicate generation.
Code
Next action
INVALID_REQUEST
Refresh capability definitions and correct the input types, model options or owned asset IDs.
NOT_FOUND / OWNERSHIP_DENIED
Use an existing resource belonging to the connected account.
NOT_AVAILABLE
Choose an available generator or check your account's access.
NOT_AFFORDABLE
Check your Gem balance before creating another generation.
PRICE_CHANGED
Review the current request and obtain a new spending limit if needed. Do not silently raise maxGemCost.
IDEMPOTENCY_CONFLICT
Reuse the original arguments for that key. A genuinely new generation needs a new key and spending approval.
IMPORT_BLOCKED
Use a direct public HTTPS media file of the selected kind and within the import limits.
SECURITY_BLOCKED / SAFETY_BLOCKED
Review connection access or change the creative request as appropriate.
PROVIDER_FAILED / TEMPORARILY_UNAVAILABLE
Inspect the generation state and retryable flag. Do not create a duplicate job just because polling failed.
For OAuth or HTTP failures, let the client follow the server challenge and check the connection, resource and granted scopes. A 403 by itself does not identify expired credentials. Reconnect only when needed; never silently broaden access.
For pending work, use list_generations or the saved generation ID to find the original job. There is no public MCP cancellation or retry-generation tool.