Connect a Compatible Client
Configure a remote HTTP MCP server with the following URL and anAuthorization: Bearer <your Modellix API key> header:
mcpServers, url, and headers, the equivalent configuration is:
server/discover; requests carry MCP-Protocol-Version, Mcp-Method, the applicable Mcp-Name, and protocol/client-capability metadata. The client should construct these fields. Older clients receive a protocol error instead of silently selecting another version.
Verify the Connection
These Bash/curl examples perform public discovery only. They do not require an API key, submit a generation task, or upload a file. They also let you distinguish endpoint availability from your MCP client’s protocol support. Discover the server and its supported version:200, result.supportedVersions containing 2026-07-28, and result._meta["io.modelcontextprotocol/serverInfo"].name equal to modellix-media-generation.
List the eight tools:
200 with eight entries in result.tools. Discovery is anonymous; calling a protected tool still requires Authorization: Bearer <your Modellix API key>. modellix_get_schema is public. For tools/call, the client must also set Mcp-Name to the tool name in params.name and set Mcp-Method to tools/call; keep the per-request metadata in params._meta.
Troubleshoot Connection Errors
Inspect the JSON-RPC error body from the endpoint. A host may wrap its HTTP400 response in a generic 500 Failed to connect to MCP server message.
When reporting a failure, include the time and timezone, HTTP status, JSON-RPC error code/message, and response
X-Request-ID. Keep API keys, cookies, prompts, uploads, and signed URLs out of diagnostics. Server rejection logs record status, duration, a recognized request ID, and allowlisted protocol/method header values; they do not record request or response bodies. Unknown header values and unrecognized custom request IDs are redacted.
Generate Media
- Call
modellix_list_modelswith an optionaltypeorkeyword. Uselimitandoffsetto page through results; the default limit is 20 and the maximum is 100. - Read
modellix_get_schemausing the exactprovider/modelslug. This public request needs no API key and preserves required fields, defaults, enums, and schema references. - Upload an input only when the selected model requires one, or reuse an existing file URL.
- Confirm the model and input with the user, then call
modellix_submit_taskonce. Keep the returnedtask_id. - Call
modellix_wait_taskfor up to 45 seconds per call. A normal deadline returns a snapshot; continue waiting with the same ID. - Read successful outputs from
data.result.resourcesand save them before they expire.
modellix_get_schema returns the original API schema document with an input_schema projection and a reference_scope explanation. Resolve input-local references against input_schema, and document-scoped references against the original returned document. Keep the document root when its references use paths, post, or components; copying only the projection can break those references.
Upload and Reuse Inputs
Pass exactly one ofurl and base64_content. Base64 uploads also require a plain filename. Remote MCP cannot read a path on your computer. URL downloads accept public HTTP(S) destinations and reject private, local, reserved, or credential-bearing targets, including redirects.
MCP uploads are limited to 16 MiB (16777216 bytes). The REST API has a separate configurable limit. Supported extensions are JPG, JPEG, PNG, WebP, GIF, BMP, TIFF, TIF, HEIC, HEIF, MP4, M4V, WebM, MOV, MKV, AVI, MP3, WAV, M4A, AAC, OGG, FLAC, OPUS, and WEBA. The media API still validates content and team policy.
Default team settings allow 10 files, 2 concurrent uploads, and about 7 days of retention; your configuration may differ. On an upload quota error, list files, select an unneeded file_id, and explicitly approve its deletion. The tools never automatically delete files or retry uploads to free quota. Deleting an absent file succeeds with already_absent.
Recover Without Duplicate Submissions
modellix_submit_task and uploads are sent once. If the connection fails before a trustworthy response is received, submission_unknown means the operation may have succeeded. Inspect existing tasks or files before any manual retry. An unknown submission cannot guarantee a task ID.
- If you have a
task_id, usemodellix_get_taskormodellix_wait_taskwith that ID. - If the task ID was lost, query Media Request Logs using the same team’s API key and a narrow time window around the submission. The REST endpoint is
GET https://api.modellix.ai/api/v1/logs;start_timeandend_timeare UNIX seconds, the window cannot exceed 30 days, and results are paginated. Match the model, creation time, and request details before using a returnedtask_id. This MCP server has no task-history search tool. - For an uncertain upload, call
modellix_list_filesand compare the filename, size, and creation time before considering another upload. - A missing log or file entry alone does not prove the original request was never accepted. If the outcome remains uncertain, retain the available request ID and contact support before manually repeating a paid request.
modellix_get_task returns immediately. modellix_wait_task defaults to 30 seconds and accepts 1–45 seconds; a normal timeout is HTTP success with data.wait.timed_out=true, not a failed task. Terminal states are success, failed, and canceled.
The media endpoint does not advertise the official MCP Tasks extension, Apps UI, or enterprise identity-provider login. It does not choose a default model or estimate a price on your behalf.
Related Integrations
The Docs MCP searches documentation. The Plugin uses this Media Generation server when its tools are available and the input is not a local file, then the CLI, then REST. Agent Canvas remains a local stdio product.REST API
Submit async image, video, and speech tasks over HTTP.
Skill
Teach coding agents how to discover models and run generation.
CLI
Authenticate, submit tasks, wait, and download results from the terminal.
Playground
Generate and preview media in the browser with no code.