MCP Support

Remix Studio exposes a streamable HTTP Model Context Protocol (MCP) endpoint at /mcp. It lets an external client work with the same user-scoped libraries, projects, models, storage summaries, campaigns, and posts used by the web interface.

The in-app assistant is built on the same tool registry, but authentication and write confirmation differ.

Capabilities

Available MCP capabilities include:

• Create libraries and create text prompts, including batch prompt creation.
• Search library items across libraries, or browse a single library with pagination and tag filters.
• Update a single text prompt's content, title, or tags with update_prompt.
• Delete a single text prompt from a text library with delete_prompt.
• Inspect storage usage, albums, libraries, library items, and usable model/provider pairings.
• Browse the items inside a project album with get_album_items, including each item's filename, prompt, tags, format, aspect ratio, size, and storage keys, plus a tagCounts roll-up of every tag in the album. Filter with tags and tag_match.
• Read one item by ID with get_album_item (its full prompt and, for a text project, the full generated text, with the project's name and link) or get_library_item (the full text, or the storage key of a media item, with the library's name, type and link). Both take the IDs from a reference the user copied with Copy ID for AI — see item references.
• Tag album items with tag_album_items — add, remove, or replace tags on the ids given in item_ids, or on every item in the album with all_items, optionally narrowed by filter_tags and aspect_ratios.
• Rename album items with rename_album_items — rename specific items with updates, or batch-replace / prepend / strip filename prefixes across item_ids or all_items with old_prefix and new_prefix while keeping storage keys, thumbnails, optimized files, and originating job records in sync.
• Download stored files with get_file_urls, which converts internal storage keys into temporary presigned URLs (optionally as save-as download links).
• Upload image, video and audio files with create_upload, then add them to a library (add_files_to_library), pin them in a project workflow (uploadId on update_project / create_project_with_workflow items), or post them to a campaign (create_posts_from_files, add_media_to_post). See file uploads.
• Export a project album as a .zip with export_project_album, or a whole project as a portable bundle with export_project.
• Create and update workflow-backed projects, including Civitai projects.
• Stage and run generation: draft_jobs builds draft jobs from a project's workflow, start_jobs queues all of them or a chosen number, and get_project_job_counts reports drafts, queue depth, completed runs, and album totals.
• Monitor the queue across every project with get_queue_status, which returns the counts behind the queue monitor page — running, queued, failed, and provider slots — with breakdown reproducing either tab of that page (providers for each provider queue's slots, limit, and depth; projects for each project holding jobs), and never the job list itself.
• Clear failed jobs with clear_failed_jobs, the same action as the queue monitor's clear buttons — scoped to one project (projectId), one provider queue (providerId), or the whole account when neither is given.

Write and destructive tools are confirmation-gated. Prompt deletion is scoped to one item in a text library and requires an explicit confirmed tool call, and so does clearing failed jobs.

Exports

export_project_album archives the media saved in a project's album — the entire album by default, or just the ids passed in item_ids. export_project archives a whole project (settings, workflow, album metadata, and every media file they reference) as a bundle another Remix Studio installation can import.

Both are queued in the background, exactly like an export started from the web interface:

• The call waits up to wait_seconds (default 120, max 600) and returns downloadUrl once the archive is ready — a temporary link valid for about 24 hours.
• If the archive is still building when the wait runs out, the response carries status, filesArchived/filesTotal, and a taskId. Re-call the same tool with task_id to keep waiting; do not start a second export.
• Finished archives appear in the user's exports list and count against their storage quota, so an export can be refused with a storage-limit error.

File access

Read tools return storage keys, not links. To fetch, view, or download a file, pass those keys to get_file_urls:

• Accepts up to 50 keys per call, with expires_in between 60 and 86400 seconds (default 1 hour) and download: true for an attachment (save-as) URL.
• Signs a key only when it is still referenced by media the authenticated user owns — library items, album items, job outputs, project workflow items, or campaign post media. Everything else is returned under denied with a reason, and values that are already absolute URLs are rejected as needing no signing.
• Returned URLs are temporary; request new ones rather than reusing expired links. When the deployment sets S3_PUBLIC_CUSTOM_DOMAIN, storage returns a direct public URL instead of a signed one.

File uploads

File bytes never travel inside a tool call. A client that has the file on disk (a shell, a script, a code sandbox) stages it first and attaches it second:

1. Stage. create_upload takes each file's filename, mimeType and exact size in bytes and returns an uploadId and a one-time uploadUrl, plus a ready curl command. It needs no confirmation, because staging changes nothing the user can see.
2. Send the bytes. PUT the raw file to the uploadUrl — curl -sS -T hero.png "<uploadUrl>". No Authorization header and no multipart encoding: the single-use token in the URL is the credential. A successful upload answers 200 with "status": "ready".
3. Attach. Pass the uploadId to one of the attach tools, which go through the normal confirmation protocol:

Destination	Tool	What it creates
Image, video or audio library	add_files_to_library	A library item per file; the title defaults to the file name
Project workflow	update_project, create_project_with_workflow	An image, video or audio item with uploadId instead of value
Campaign	create_posts_from_files	One draft post per image or video, with the post watermark applied
Existing post	add_media_to_post	A post media item, processed in the background

Rules the server enforces:

• Supported types are images (PNG, JPEG, WebP, GIF; up to 50 MB), videos (MP4, MOV, WebM, MKV; up to 200 MB) and audio (MP3, AAC, M4A, WAV, OGG, WebM; up to 50 MB) — the same limits as uploads in the web app.
• The type is detected from the file's bytes. A file declared as an image whose contents are audio is refused, and so is a body whose length differs from the declared size.
• An uploadUrl accepts one PUT and expires after 15 minutes. A staged file can be attached any number of times for 24 hours; each attach makes its own copy, then the staged file is deleted.
• Staged files count toward the storage quota until they are deleted, and create_upload refuses files that would not fit. get_storage_usage reports them under staging.
• get_upload reports each upload's status: awaiting_upload, processing, ready, or failed with an error.

These tools are offered to external MCP clients only. The in-app assistant has no way to send file bytes, so it does not see them.

Civitai projects

create_project_with_workflow and update_project take type civitai. Set providerId to a Civitai provider — list_available_models lists them under civitaiAccounts — leave modelConfigId out, and put the shared settings in civitaiSettings, including mediaType: "video" and video (engine, resolution, length…) for a video project. The workflow also takes:

Item type	Holds
checkpoint	Images only; exactly one item, whose models lists one or more checkpoints by Civitai link or AIR — one per job
lora	Any number; each lists one or more LoRAs, LyCORIS, DoRAs or embeddings with their strengths — one per job
negative_text, negative_text_library	Text or a text library that feeds the negative prompt

Models are resolved with the project's Civitai account and reused as they are when carried forward from get_project. draft_jobs drafts Civitai combinations like any other.

ComfyUI projects are set up in the app, since they start from an exported workflow graph; an agent can read them, draft their jobs and start them.

Item references

Copy ID for AI in the app copies a reference that names the item and its parent, because every tool that acts on an item needs both:

Reference	Tools it fills
library:<libraryId>/item:<itemId>	get_library_item, update_library_item, update_prompt, delete_prompt
project:<projectId>/album-item:<itemId>	get_album_item, tag_album_items, rename_album_items, export_project_album (item_ids)
campaign:<campaignId>/post:<postId>	get_post, get_post_text, update_post, update_post_text, add_media_to_post, schedule_post

The server's instructions describe these shapes to the client, so a user can paste one into the chat and the agent reads or changes exactly that item.

Live page updates

Open Remix Studio pages show what an MCP client changes without a reload: a library the client creates appears in the libraries list, prompts it adds appear on the library page, a workflow it replaces with update_project appears in the open project, and posts it creates or edits appear on the campaign and post pages. Each signed-in browser tab keeps one change feed for its user; see live updates.

Record links

Tools return absolute Remix Studio links next to the raw ids, so a client can show the user where a record lives instead of quoting an id:

• url — the library, project, campaign, or post the call is about (list_libraries entries, get_project, create_campaign, get_post, …).
• libraryUrl / projectUrl / campaignUrl — the parent record when it is context for something else (search_library_items results, get_album_items, post tools).

The origin comes from APP_URL when it is configured; otherwise the server falls back to the origin of the incoming MCP request (honoring X-Forwarded-Proto / X-Forwarded-Host). Set APP_URL to the browser-visible origin of your deployment so the links are shareable.

Authentication

MCP requests require a bearer token obtained through either:

• OAuth 2.0 authorization code flow, with PKCE support and refresh tokens.
• A personal access token (PAT) created in Remix Studio.

Manage connections under Assistant Settings → MCP. PATs are shown only when created, are stored as hashes, can have an expiry, and can be revoked. All MCP tools use the mcp:tools scope and enforce the authenticated user's ownership in their handlers.

OAuth discovery metadata is available at:

• /.well-known/oauth-authorization-server
• /.well-known/oauth-protected-resource

The related endpoints are /register, /authorize, and /token. Dynamically registered clients are tied to the account that created them. The server rotates OAuth refresh tokens and detects reuse outside its recovery grace window.

Client Configuration with a PAT

{
  "mcpServers": {
    "remix-studio": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Replace the origin with the public APP_URL of your deployment. Use HTTPS outside local development because the token grants access to your Remix Studio data.

For clients without MCP support — scripts, curl, a language with no MCP SDK — the endpoint can be driven as plain JSON-RPC over HTTP. See Calling MCP Tools over HTTP.

Tool Catalog

The exact schemas are returned by MCP tool discovery. At the current source version, the catalog is:

Area	Read tools	Write/destructive tools
Account	get_current_account	—
Libraries	list_libraries, get_library_items, get_library_item, search_library_items	create_library, update_library, create_prompt, batch_create_prompts, update_prompt, update_library_item, batch_update_library_items, delete_prompt
Projects	get_project, list_albums, get_album_items, get_album_item, list_available_models, get_storage_usage	create_project_with_workflow, update_project, tag_album_items, rename_album_items, export_project, export_project_album
Jobs	get_project_job_counts, get_queue_status	draft_jobs, start_jobs, clear_failed_jobs
Files	get_file_urls, get_upload	create_upload, add_files_to_library, create_posts_from_files
Campaigns	list_social_accounts, list_campaigns	create_campaign, update_campaign
Posts	list_posts, get_post, get_post_text	create_post, update_post, update_post_text, add_media_to_post, schedule_post

Important boundaries:

• get_current_account reports the account the token resolves to — the same account every other tool reads and writes. It never exposes secrets (no password hash, no token material) and cannot look up other users.
• Prompt creation/deletion is for text libraries.
• update_library_item can update text content only for a text library; batch updates change titles/tags only and accept at most 100 items.
• update_project replaces the entire workflow when workflowItems is supplied. Call get_project immediately beforehand and carry forward every step that should remain.
• draft_jobs takes its prompts, provider, model, and generation settings from the project itself — set them with update_project first. It creates at most 10000 drafts per call; call it again for larger batches.
• start_jobs consumes drafts oldest first and runs generation against the user's provider, which costs credits. Omit count to start every draft.
• clear_failed_jobs deletes failed job records only — drafts, queued, running, and completed jobs are untouched, and album items already saved survive. A cleared failure can no longer be retried. projectId and providerId are alternatives, not filters to combine; omitting both clears every failed job in the account. Pending jobs in an affected project are re-enqueued, so a project stalled behind failures resumes on its own.
• tag_album_items takes exactly one of add, remove, or replace per call. replace discards whatever other tags the items carried, and replace: [] clears them entirely. Tags are normalised on write — trimmed, de-duplicated case-insensitively, capped at 64 characters each and 30 per item.
• Export tools are confirmation-gated writes because the archive they produce consumes the user's storage quota. Polling with task_id goes through the same protocol.
• Media added to a post must be an internal storage key already owned by the authenticated user and valid for that campaign, or an uploadId from create_upload.
• Image, video and audio workflow items may only name storage keys the authenticated user already owns (from get_project, get_library_items or get_album_items). Use uploadId to pin a new file.
• Scheduling requires a valid time, an active channel on the campaign, and ready media.

Write Confirmation Protocol

External MCP writes use an argument-bound two-call protocol:

1. Call the tool with the desired arguments and without confirmed: true.
2. The server returns a preview containing a summary, normalized arguments, and confirmationHash; no mutation has occurred.
3. Show that exact action to the user.
4. If approved, call the same tool again with the same arguments plus confirmed: true and the returned confirmationHash.

The hash binds approval to the tool name and normalized arguments. If any argument changes, the hash is rejected and a new preview is required.

Read-only tools do not need this protocol. External clients cannot use the in-app assistant's per-conversation approved-tools list.

Workflow Update Safety

Project workflow updates are replacement operations, not patches to one step. A safe client sequence is:

1. Call get_project.
2. Start from the newly returned workflowItems.
3. Apply the requested edit while preserving order, selected tags, and disabled state.
4. Preview update_project.
5. Confirm the exact replacement.

This prevents a long-running conversation from silently dropping workflow edits made elsewhere.

Inspecting the Server

During local development:

npm run mcp:inspect

The script launches the MCP Inspector against http://localhost:3000/mcp. Sign in or provide a token as required by the inspector.

For source-level details, see server/mcp/tool-definitions.ts and server/mcp/tool-confirmation.ts.