MCP tool reference

The server at https://keytween.com/mcp exposes tools, resources and prompts. Setup is in Connect your agent. Every tool publishes a JSON Schema for its input and output, so the authoritative, always-current parameter list is what your client shows from tools/list; this page is the map.

Tools #

Tool	What it does
`get_guide`	Prompting guides, workflows, sizes, pricing, job handling and API reference as markdown.
`get_account`	Credit balance, its dollar value, limits and what the account may do.
`get_pricing`	What every kind of generation costs, in credits and dollars, plus credit packs.
`estimate_cost`	Exact credit and dollar cost of a planned set of generations, checked against the balance.
`get_service_status`	Whether rendering is online, how busy the queue is and typical render times.
`list_credit_history`	Recent charges, refunds and purchases.
`generate_image`	Text to image up to 4 megapixels, optionally guided by @reference images.
`edit_image`	Change an existing image with a text instruction, optionally pulling in @reference images.
`generate_video`	Text to video, image to video, or first and last frame to video, with sound.
`generate_sprite`	Game-ready sprite, icon or tile from text: 8-512 px PNG with transparency, outline and exact palette.
`edit_sprite`	Change a sprite (or turn any image into one) with an instruction: recolours, tiers, other facings, poses, walk frames, bigger versions.
`animate_sprite`	Describe an action and get 2-8 animation frames of an existing sprite, with a packed sheet.
`generate_walk_sheet`	A 16-frame 32x32 RPG walk sheet in four directions, from a description or an existing character.
`create_style_kit`	Save a game's look (style sprites, style sentence, outline, palette) once and apply it to every sprite and animation.
`list_style_kits`	The style kits saved on this account.
`update_style_kit`	Change a style kit's name, style sprites, sentence, outline or palette.
`delete_style_kit`	Delete a saved style kit; the sprites themselves are kept.
`export_sprite`	Free: another size, palette, padding, outline, anchor, tile setting or a mirrored copy of a sprite, or a cutout of any flat-background image.
`learn_sprite_palette`	Free: learn one #rrggbb palette from a set of sprites, to pass as palette so the whole set uses the same colours.
`pack_sprite_sheet`	Free: pack sprites into one PNG sheet with each sprite's rectangle, for an engine atlas, an animation strip or a side-by-side review.
`get_sprite_links`	Fresh download links and names for up to 100 sprites or sprite sheets at once.
`get_job`	Current status, progress, queue position and outputs of one generation.
`wait_for_job`	Waits for a generation to finish, reporting progress along the way.
`list_jobs`	Recent or currently active generations.
`cancel_job`	Stops a queued or running generation and refunds it.
`create_sequence`	Starts a new sequence, empty or from an existing image.
`list_sequences`	Your sequences, most recently changed first.
`get_sequence`	Steps, selected frames, candidates, takes, references and exports of one sequence.
`rename_sequence`	Changes a sequence's title.
`delete_sequence`	Permanently deletes a sequence and everything in it.
`select_frames`	Chooses which start frame, end frame or take a step uses.
`accept_step`	Locks a step's take and opens the next step from its last frame.
`reopen_step`	Un-accepts a step so it can be changed; deletes every later step.
`export_sequence`	Joins the selected takes of every step into a single MP4.
`get_asset`	Details, a fresh download link and a visual preview of one image or video.
`list_assets`	Everything you have made or uploaded, across the image library and all sequences.
`delete_asset`	Permanently deletes one image, take, reference or export.
`create_upload_url`	Returns a short-lived link and command for uploading a local image to the library, as a start frame or as a reference.
`add_reference`	Copies one of your images into a sequence or the image library as an @label reference.
`update_reference`	Changes a reference's @label or crops it to the part that matters.

Conventions #

Names. Parameters and result fields are snake_case. Ids are UUIDs: sequence_id, step_id, asset_id, job_id.
Results. Each result is returned twice: as structuredContent matching the tool's output schema, and as the same JSON in a text block for clients that only read text. Finished images and videos add an image block with a small preview the model can look at.
next. Results of generate, wait and sequence tools include a next field saying what to do next in plain words.
Roles. An asset's role is start_frame, end_frame, take (a video clip), last_frame (the final frame of a take), reference or export.
Sizes. aspect_ratio with megapixels, or width with height. See Sizes and durations.
Waiting. wait_seconds on generate tools and timeout_seconds on wait_for_job. See Jobs, waiting and limits.
Errors. isError: true with {"error": {"code", "message", "hint"}}.
Annotations. Read-only tools are marked readOnlyHint; delete_sequence, delete_asset and reopen_step are marked destructiveHint, so clients can ask for confirmation.
Cost. Only generate_image, edit_image and generate_video spend credits. Everything else is free.

Choosing a generate tool #

Goal	Tool and key parameters
Image from a description, up to 4 MP	`generate_image` without `sequence_id`
Opening frame for a video	`generate_image` with `sequence_id`
Image containing a specific subject or style	`generate_image` with `@label` references in the prompt
Change any image, keep the result as an image	`edit_image` (default `save_as: "image"`)
Animate an existing image	`create_sequence` with `from_asset_id`, then `generate_video`
Game sprite, UI icon or seamless tile at an exact pixel size, with transparency	`generate_sprite`; change it with `edit_sprite`; other sizes, outline, padding or a mirrored copy free with `export_sprite`
Animate a sprite from a described action	`animate_sprite`; a 4-direction RPG walk sheet with `generate_walk_sheet`
A whole game art set	a style kit (`create_style_kit`, then `style_kit_id` on every call), the sprite tools, `learn_sprite_palette` (one shared palette), `pack_sprite_sheet` (atlas or animation strip) and `get_sprite_links` (fresh named download links)
Define where a shot ends	`edit_image` with `save_as: "end_frame"`
Video from a description	`generate_video` with `mode: "text_to_video"`
Animate an image, open ending	`generate_video` with `mode: "image_to_video"`
Video between two exact images	`generate_video` with `mode: "first_last_frame"`
Continue with another shot	`accept_step`, then the same tools on the new step
One finished file	`export_sequence`

Working with local files #

MCP tool calls carry text, so files move over plain HTTP links instead:

Download: every finished asset has a download_url that needs no credentials for one hour. curl -sS -o out.png "<download_url>".
Upload: create_upload_url returns a link valid for 15 minutes and the matching command, curl -sS -F "file=@/path/to/image.png" "<upload_url>". The response is the new asset as JSON; its id is the asset_id.

Resources #

Each guide is an MCP resource with the URI keytween://guides/<topic> and the MIME type text/markdown. The same text is returned by the get_guide tool, for clients that do not surface resources to the model.

overview: What you can build, the core concepts and which path to take.
mcp-setup: Add the MCP server to Claude Code, Cursor, VS Code, Codex, Gemini CLI and other agent harnesses.
workflows: Which calls to make for images, edits, references, each video mode and multi-shot films.
sprites: Exact-size transparent PNG sprites and UI icons for games: generating, editing, sizes and consistent sets.
image-prompting: How to write text-to-image prompts: structure, composition, lighting and text in images.
edit-prompting: Instruction-style edits, what to keep, and carrying subjects over with @references.
video-prompting: Shot, scene, action, camera and audio for text, image and first-and-last-frame video.
sizes: Every aspect ratio and resolution, clip lengths and frame rates.
pricing: What each generation costs, how to estimate a project and how refunds work.
jobs: Statuses, timeouts, queueing, concurrency limits and error codes.
mcp-tools: Every MCP tool, resource and prompt the server exposes.
rest-api: Authentication, endpoints, request bodies and errors.
your-data: Where API and agent creations are stored, how to review them and how to delete them.

Prompts #

Prompts appear as slash commands in clients that support them (in Claude Code: /mcp__keytween__storyboard).

Prompt	Arguments	What it does
`storyboard`	`concept`, `shots`, `aspect_ratio`	Plans a multi-shot video as chained steps, quotes the cost, waits for your go-ahead, then builds and exports it
`image_prompt`	`idea`, `aspect_ratio`	Turns a rough idea into a production-ready image prompt and quotes it
`video_prompt`	`idea`, `mode`	Turns a rough idea into a production-ready video prompt with sound, and quotes it

Protocol details #

Transport: Streamable HTTP, POST https://keytween.com/mcp. The server is stateless: there are no sessions, and GET and DELETE on the endpoint answer 405.
Protocol revisions: 2026-07-28, and the 2025 revisions through the standard initialize handshake.
Responses are sent as a server-sent event stream so that progress notifications and keep-alive frames can be delivered during long calls.
Authentication: Authorization: Bearer <API key> on every request. OAuth is not used.
Progress: tools that wait send notifications/progress (0 to 100) when the request carries a progress token.