@runapi.ai/flux-kontext-mcp
This MCP server provides focused access to RunAPI's Flux Kontext image generation API, enabling AI agents to create images, monitor tasks, and check pricing.
Generate images from text (
text_to_image): Submit a prompt to create an image usingflux-kontext-maxorflux-kontext-pro, with options for:Aspect ratio (
21:9,16:9,4:3,1:1,3:4,9:16) and output format (jpegorpng)Source image URL for image-to-image generation
Wait for completion or return immediately with a task ID
Additional options: watermark, safety tolerance, prompt expansion, translation, callback URL, and polling interval
Check task status (
get_task): Retrieve the current status and result payload (including output URLs) for a previously submitted task using its task ID.Look up pricing (
check_pricing): Query current pricing for Flux Kontext models and endpoints — no API key required, useful for cost checks before submitting a task.
Click on "Deploy 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., "@@runapi.ai/flux-kontext-mcpgenerate an image of a cat in space using flux-kontext-max"
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.
Why This Package?
@runapi.ai/flux-kontext-mcp is a focused Model Context Protocol server for the Flux Kontext model line on RunAPI.
It gives MCP-compatible assistants direct access to 1 endpoint and 2 model variants without loading the full RunAPI catalog.
Use this per-model server when an agent should stay scoped to Flux Kontext. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.
Related MCP server: Image Generation MCP Server
Install
Add it to Claude Code:
claude mcp add flux-kontext -s user -- npx -y @runapi.ai/flux-kontext-mcpUse project scope when the server should be shared with a repository:
claude mcp add flux-kontext -s project -- npx -y @runapi.ai/flux-kontext-mcpCodex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:
{
"mcpServers": {
"flux-kontext": {
"command": "npx",
"args": ["-y", "@runapi.ai/flux-kontext-mcp"]
}
}
}check_pricing works before sign-in. For task creation and status polling, ask your assistant to call the login tool. It opens a browser login and saves credentials to ~/.config/runapi/config.json, the same file used by runapi login.
Headless and CI hosts can still set RUNAPI_API_KEY before starting the MCP host.
Ready-made examples are in examples/ for Claude, Cursor, Windsurf, VS Code, and Roo Code.
Tools
Tool | Auth | Purpose |
| Yes | Create a Flux Kontext text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Fetch the current status and latest payload for an existing task. |
| No | Look up current pricing for a Flux Kontext model and endpoint. |
Models
Flux Kontext covers 2 model variants across 1 endpoint. Each tool accepts the models listed for it:
Tool | Models |
|
|
Model availability can change between releases. Use check_pricing or the Flux Kontext model page for the current catalog view.
Agent Prompts
Ask your assistant in natural language; it can inspect pricing, create the task, and return the task id plus output URLs.
Create a task
Run a Flux Kontext text to image task with RunAPI.The assistant can call check_pricing, then text_to_image, and return the task id, status, and output URLs.
Submit without waiting
Create the task but don't wait for it to finish.The assistant calls the create tool with wait: false and returns the task id. Check on it later with get_task.
Check pricing before creating
Check current Flux Kontext pricing, then create the task if it matches my request.The assistant calls check_pricing and can link to the Flux Kontext model page for the canonical catalog entry.
Configuration
The server resolves auth in this order:
RUNAPI_API_KEYenvironment variable, useful for headless and CI hosts~/.config/runapi/config.json, created by the MCPlogintool orrunapi loginNo key, which still allows
check_pricing
The config file is normally managed by login. A pre-provisioned headless config can use:
{
"apiKey": "your_runapi_key"
}Do not commit real API keys.
Links
Resource | URL |
Flux Kontext model page | |
npm package | |
GitHub repository | |
RunAPI MCP overview | |
RunAPI docs |
License
Licensed under the Apache License, Version 2.0.
Available Tools
4 toolscheck_pricingB
Look up RunAPI pricing for the flux-kontext model line.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model slug. Defaults to the line's primary model. | |
| action | No | Endpoint name. Defaults to the endpoint that offers the model. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Look up' weakly implies a read-only operation, but the description says nothing about authentication, whether pricing data is live or cached, rate limits, or cost of calling. Significant gaps for a tool with zero annotation coverage.
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?
A single, front-loaded sentence with no waste. It could be slightly more informative given its brevity, but nothing is redundant or padded.
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 two-parameter, zero-required tool with full schema coverage and no output schema, the description is minimally adequate. It identifies the resource but does not hint at the shape or units of the returned pricing, which would help since no output schema exists.
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 both 'model' and 'action' are already documented in the schema and the baseline is 3. The description adds the flux-kontext model line as a domain context but no syntax, defaults, or format detail beyond 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?
States a specific verb ('look up') and resource ('RunAPI pricing') and scopes it to the flux-kontext model line. It is easily distinguished from siblings like text_to_image, get_task, and login, though the model-line scoping is slightly narrower than the free-form 'model' parameter implies.
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 purpose makes usage implied — an agent consults this when it needs pricing before calling text_to_image — but there is no explicit when-to-use, when-not-to-use, or alternative routing. No prerequisites or context of use are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_taskB
Fetch the current status and latest result payload for a flux-kontext task.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | Asynchronous endpoint the task was created on. Defaults to the line's only asynchronous endpoint. | |
| task_id | Yes | Task id returned when the task was created. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It implies a read-only retrieval but does not disclose idempotency, authentication requirements, rate limits, polling expectations, possible task states, or error behavior.
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 definition is a single, front-loaded sentence with no wasted words. It states the core retrieval purpose directly and efficiently.
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 two-parameter retrieval tool, the description covers the basic purpose, but with no annotations or output schema it omits important context such as return shape, asynchronous status semantics, and polling or retry guidance.
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 has 100% description coverage, so both parameters are already explained in structured form. The description adds no additional syntax, defaults, or meaning beyond what the schema provides, which is the expected baseline.
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 names a specific verb and resource: fetching current status and latest result payload for a flux-kontext task. It is clear enough to distinguish from sibling tools like text_to_image, but it does not explicitly mention siblings or scope boundaries.
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?
There is no explicit guidance on when to use this tool versus alternatives, when not to use it, or how it should be used in a polling workflow after task creation. The description only states what it fetches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
loginA
Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Re-run browser login when the current credential comes from the local config file. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the interactive browser flow and the file write side effect (config.json). However, it does not mention that it may overwrite existing credentials or that it could block waiting for user input, though these are implied.
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 a single, well-structured sentence that front-loads the action ('Authenticate RunAPI') and provides necessary details without extraneous information.
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 login tool with one optional parameter and no output schema, the description covers the core purpose and side effect. It lacks an explicit statement that this is a prerequisite for other tools, but that is implied.
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% (the only parameter 'force' has a description). The tool description adds no additional meaning about parameters beyond the schema, so the baseline of 3 applies.
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 with a specific verb ('Authenticate'), target resource ('RunAPI'), method ('browser PKCE login flow'), and side effect (saving to config.json). It is distinct from sibling tools, none of which relate to authentication.
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 usage (to authenticate RunAPI) but does not explicitly say when to run it (e.g., before other RunAPI tools) or when to use the 'force' parameter. Since there are no alternative auth tools among siblings, 'vs alternatives' is not applicable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
text_to_imageB
Create a Flux Kontext task on RunAPI (text to image). Returns a task id, status, and output URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Poll until the task reaches a terminal status. | |
| model | No | RunAPI model slug for this model line. | |
| prompt | Yes | Image description (English only). Declared type: string. | |
| watermark | No | Watermark identifier. Declared type: string. | |
| timeout_ms | No | ||
| aspect_ratio | No | Output aspect ratio. Default: 16:9. Declared type: string. Known values: "21:9", "16:9", "4:3", "1:1", "3:4", "9:16". | |
| callback_url | No | Webhook URL for async notifications. Declared type: string. | |
| output_format | No | Output format. Default: jpeg. Declared type: string. Known values: "jpeg", "png". | |
| poll_interval_ms | No | ||
| safety_tolerance | No | Content safety threshold. 0-6 for generation, 0-2 for editing. Default: 2. Declared type: integer. | |
| source_image_url | No | Source image URL for editing mode. Declared type: string. | |
| enable_translation | No | Auto-translate non-English prompts. Default: true. Declared type: boolean. | |
| enable_prompt_expansion | No | Expand the prompt with more detail. Default: false. Declared type: boolean. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the return shape ('task id, status, and output URLs'), which is valuable since there is no output schema. However, it omits async/polling behavior, the meaning of the wait flag, cost implications (check_pricing is a sibling), and auth requirements, leaving meaningful behavioral gaps.
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 tightly written sentences with zero filler, and the core action is front-loaded before the return-value note. Nothing is padded or redundant.
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 13-parameter generation tool with no annotations and no output schema, the definition is minimal. It covers the return values, which partly compensates for the missing output schema, but leaves async behavior, credits/cost, editing mode, and usage routing unexplained.
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 high at 85%, so the schema already documents most of the 13 parameters including defaults and known values. The description adds essentially no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.
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?
States a specific verb and resource: 'Create a Flux Kontext task on RunAPI (text to image)'. This clearly tells the agent it initiates an image generation task. It does not, however, name or differentiate itself from siblings like get_task, so an agent must infer that this is the creation step versus the retrieval step.
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 offers no when-to-use guidance, no mention of alternatives such as get_task for polling or check_pricing for cost, and no note that the tool also supports an editing mode via source_image_url despite being labeled 'text to image'. The agent gets no routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.2.0- Changed
check_pricing2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - removed
Input schema / properties / model / enumRemoved value: -[ - "flux-kontext-max", - "flux-kontext-pro" -]
- Changed
get_task1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
text_to_image16 fields changed- added
Input schema / additionalPropertiesAdded value: +{} - removed
Input schema / properties / aspect_ratio / anyOfRemoved value: -[ - { - "const": "21:9", - "type": "string" - }, - { - "const": "16:9", - "type": "string" - }, - { - "const": "4:3", - "type": "string" - }, - { - "const": "1:1", - "type": "string" - }, - { - "const": "3:4", - "type": "string" - }, - { - "const": "9:16", - "type": "string" - } -] - changed
Input schema / properties / aspect_ratio / descriptionPrevious value: -"Output aspect ratio. Default: 16:9."New value: +"Output aspect ratio. Default: 16:9. Declared type: string. Known values: \"21:9\", \"16:9\", \"4:3\", \"1:1\", \"3:4\", \"9:16\"." - added
Input schema / properties / aspect_ratio / typeAdded value: +"string" - changed
Input schema / properties / callback_url / descriptionPrevious value: -"Webhook URL for async notifications."New value: +"Webhook URL for async notifications. Declared type: string." - changed
Input schema / properties / enable_prompt_expansion / descriptionPrevious value: -"Expand the prompt with more detail. Default: false."New value: +"Expand the prompt with more detail. Default: false. Declared type: boolean." - changed
Input schema / properties / enable_translation / descriptionPrevious value: -"Auto-translate non-English prompts. Default: true."New value: +"Auto-translate non-English prompts. Default: true. Declared type: boolean." - removed
Input schema / properties / model / enumRemoved value: -[ - "flux-kontext-max", - "flux-kontext-pro" -] - removed
Input schema / properties / output_format / anyOfRemoved value: -[ - { - "const": "jpeg", - "type": "string" - }, - { - "const": "png", - "type": "string" - } -] - changed
Input schema / properties / output_format / descriptionPrevious value: -"Output format. Default: jpeg."New value: +"Output format. Default: jpeg. Declared type: string. Known values: \"jpeg\", \"png\"." - added
Input schema / properties / output_format / typeAdded value: +"string" - changed
Input schema / properties / prompt / descriptionPrevious value: -"Image description (English only)."New value: +"Image description (English only). Declared type: string." - changed
Input schema / properties / safety_tolerance / descriptionPrevious value: -"Content safety threshold. 0-6 for generation, 0-2 for editing. Default: 2."New value: +"Content safety threshold. 0-6 for generation, 0-2 for editing. Default: 2. Declared type: integer." - changed
Input schema / properties / safety_tolerance / typePrevious value: -"number"New value: +"integer" - changed
Input schema / properties / source_image_url / descriptionPrevious value: -"Source image URL for editing mode."New value: +"Source image URL for editing mode. Declared type: string." - changed
Input schema / properties / watermark / descriptionPrevious value: -"Watermark identifier."New value: +"Watermark identifier. Declared type: string."
1 tool update
v0.1.13- Changed
text_to_image9 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - added
Input schema / properties / aspect_ratio / anyOfAdded value: +[ + { + "const": "21:9", + "type": "string" + }, + { + "const": "16:9", + "type": "string" + }, + { + "const": "4:3", + "type": "string" + }, + { + "const": "1:1", + "type": "string" + }, + { + "const": "3:4", + "type": "string" + }, + { + "const": "9:16", + "type": "string" + } +] - removed
Input schema / properties / aspect_ratio / enumRemoved value: -[ - "21:9", - "16:9", - "4:3", - "1:1", - "3:4", - "9:16" -] - removed
Input schema / properties / aspect_ratio / typeRemoved value: -"string" - added
Input schema / properties / output_format / anyOfAdded value: +[ + { + "const": "jpeg", + "type": "string" + }, + { + "const": "png", + "type": "string" + } +] - removed
Input schema / properties / output_format / enumRemoved value: -[ - "jpeg", - "png" -] - removed
Input schema / properties / output_format / typeRemoved value: -"string" - added
Input schema / properties / poll_interval_ms / maximumAdded value: +9007199254740991 - added
Input schema / properties / timeout_ms / maximumAdded value: +9007199254740991
2 tool updates
v0.1.11- Changed
get_task1 field changed- changed
Input schema / properties / action / descriptionPrevious value: -"Endpoint the task was created on. Defaults to the line's only endpoint."New value: +"Asynchronous endpoint the task was created on. Defaults to the line's only asynchronous endpoint."
- Changed
text_to_image9 fields changed- added
Input schema / properties / aspect_ratio / descriptionAdded value: +"Output aspect ratio. Default: 16:9." - added
Input schema / properties / callback_url / descriptionAdded value: +"Webhook URL for async notifications." - added
Input schema / properties / enable_prompt_expansion / descriptionAdded value: +"Expand the prompt with more detail. Default: false." - added
Input schema / properties / enable_translation / descriptionAdded value: +"Auto-translate non-English prompts. Default: true." - added
Input schema / properties / output_format / descriptionAdded value: +"Output format. Default: jpeg." - added
Input schema / properties / prompt / descriptionAdded value: +"Image description (English only)." - added
Input schema / properties / safety_tolerance / descriptionAdded value: +"Content safety threshold. 0-6 for generation, 0-2 for editing. Default: 2." - added
Input schema / properties / source_image_url / descriptionAdded value: +"Source image URL for editing mode." - added
Input schema / properties / watermark / descriptionAdded value: +"Watermark identifier."
1 tool update
v0.1.9- Added
login
2 tool updates
v0.1.2- Changed
check_pricing1 field changed- changed
Input schema / properties / action / descriptionPrevious value: -"Endpoint name. Defaults to the line's primary endpoint."New value: +"Endpoint name. Defaults to the endpoint that offers the model."
- Changed
text_to_image5 fields changed- added
Input schema / properties / callback_url / typeAdded value: +"string" - added
Input schema / properties / prompt / typeAdded value: +"string" - added
Input schema / properties / source_image_url / typeAdded value: +"string" - added
Input schema / properties / watermark / typeAdded value: +"string" - added
Input schema / requiredAdded value: +[ + "prompt" +]
3 tool updates
v0.1.0- First observed
check_pricing - First observed
get_task - First observed
text_to_image
TDQS
Scored across 4 tools
Each tool targets a distinct operation: task creation, task status retrieval, pricing lookup, and authentication. There is no overlap in purpose, so an agent can easily select the correct tool.
Names are mostly snake_case and readable, with get_task and check_pricing following a clear verb_noun pattern. The only minor deviation is login (no underscore), but it does not significantly hinder clarity.
Four tools is reasonable for a focused API wrapper covering generation, status polling, pricing, and auth. It is slightly thin but not problematic for the stated scope.
The server covers task creation, status retrieval, pricing, and authentication, but lacks lifecycle operations like cancel, list, or delete for tasks. Also, despite the 'kontext' model often supporting image editing, only text-to-image is exposed, leaving a notable gap.
Maintenance
Related MCP Connectors
MCP server for Flux AI image generation
Official FLUX MCP server. Generate, edit, vary, and browse images from Black Forest Labs.
MCP server for Qwen Image 3 AI image generation
MCP server for Pixapi: check live credit pricing and balance, then generate images and video.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceImplements a Model Context Protocol (MCP) server powered by Flux API from Cephalon Cloud, enabling users to utilize advanced AI capabilities through standardized communication.31MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables high-quality image generation using the Flux.1 Schnell model via Together AI with customizable parameters.125 npm9MIT
- AlicenseNot gradedqualityDmaintenanceA server that enables generating images through the Replicate API by calling the Flux Schnell model via the Model Context Protocol (MCP).2MIT
- FlicenseBqualityDmaintenanceAn MCP image generation server based on the Flux Schnell model that provides API access for generating images from text prompts with customizable dimensions and seeds.11-