@runapi.ai/flux-2-mcp
OfficialThis server provides MCP-compatible AI agents with direct access to Flux 2 image generation via RunAPI, enabling task creation, status polling, and pricing queries.
Create remix image tasks (
remix_image): Generate images by remixing source images usingflux-2-flex-remix-imageorflux-2-pro-remix-image, with options for aspect ratio (1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, auto), output resolution (1k/2k), and optional polling until completion.Create text-to-image tasks (
text_to_image): Generate images from text prompts usingflux-2-flex-text-to-imageorflux-2-pro-text-to-image, with the same aspect ratio/resolution options and optional polling.Poll task status (
get_task): Fetch the current status and latest result payload (including output URLs) for any previously created task by providing a task ID.Check pricing (
check_pricing): Look up current pricing for any Flux 2 model/endpoint combination — the only tool that works without an API key.
Works with Claude Code, Codex, Cursor, Windsurf, VS Code, Roo Code, and any MCP-compatible host.
Click on "Install 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-2-mcpcreate an image of a golden retriever playing in snow"
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-2-mcp is a focused Model Context Protocol server for the Flux 2 model line on RunAPI.
It gives MCP-compatible assistants direct access to 2 endpoints and 6 model variants without loading the full RunAPI catalog.
Use this per-model server when an agent should stay scoped to Flux 2. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.
Related MCP server: flux-replicate-mcp
Install
Add it to Claude Code:
claude mcp add flux-2 -s user -- npx -y @runapi.ai/flux-2-mcpUse project scope when the server should be shared with a repository:
claude mcp add flux-2 -s project -- npx -y @runapi.ai/flux-2-mcpCodex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:
{
"mcpServers": {
"flux-2": {
"command": "npx",
"args": ["-y", "@runapi.ai/flux-2-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 2 remix image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Flux 2 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 2 model and endpoint. |
Models
Flux 2 covers 6 model variants across 2 endpoints. Each tool accepts the models listed for it:
Tool | Models |
|
|
|
|
Model availability can change between releases. Use check_pricing or the Flux 2 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 2 remix image task with RunAPI.The assistant can call check_pricing, then remix_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 2 pricing, then create the task if it matches my request.The assistant calls check_pricing and can link to the Flux 2 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 2 model page | |
npm package | |
GitHub repository | |
RunAPI MCP overview | |
RunAPI docs |
License
Licensed under the Apache License, Version 2.0.
Available Tools
5 toolscheck_pricingA
Look up RunAPI pricing for the flux-2 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?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It merely states 'look up' without mentioning read-only nature, required authentication, output format, or any side effects, leaving significant ambiguity.
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, efficient sentence that front-loads the verb and resource, with zero wasted words.
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?
Given the tool's simplicity (2 optional params, no output schema), the one-line description is minimally viable but incomplete: it does not explain what the return value contains or the effect of default parameter values, leaving gaps for an agent.
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 input schema fully documents both parameters (model and action) with enums and descriptions (100% coverage). The description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.
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 uses a specific verb ('look up') and identifies the exact resource ('RunAPI pricing for the flux-2 model line'), clearly distinguishing it from sibling tools like 'remix_image' and 'text_to_image' which focus on generation.
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 a clear use case: retrieve pricing information for flux-2 models. However, it lacks explicit exclusions or alternative suggestions, falling just short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_taskA
Fetch the current status and latest result payload for a flux-2 task.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Asynchronous endpoint the task was created on. | |
| 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, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only fetch operation and specifies the data returned (status and payload), but it does not disclose potential limitations such as pending tasks (no payload yet) or error behavior. This is basic behavior disclosure, not rich context.
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, front-loaded sentence with no redundant wording. It efficiently conveys the core function.
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?
The tool has no output schema and minimal annotations, so the description must compensate. While it states the high-level return (status and payload), it does not describe the response structure or behaviors like task not found or incomplete results. Given the simplicity of the tool, the description is usable but incomplete for an agent needing to handle edge cases.
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 input schema fully describes both parameters (task_id and action) with descriptions, including the enum for action. The description itself adds no additional parameter semantics, but since schema coverage is 100%, 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 uses a specific verb ('Fetch') and clearly identifies the resource ('current status and latest result payload for a flux-2 task'). It distinguishes from sibling tools like remix_image and text_to_image, which create tasks, by focusing on retrieval.
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 the tool is used to check on an existing task, but it does not explicitly state when to use it versus the creation tools or any prerequisites (e.g., 'call after creating a task'). The schema hints that action must match the creation endpoint, but the description itself offers no usage guidance.
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.
remix_imageA
Create a Flux 2 task on RunAPI (remix 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 editing instruction. | |
| timeout_ms | No | ||
| aspect_ratio | No | Output aspect ratio. | |
| callback_url | No | Webhook URL for async notifications. | |
| output_count | No | Number of images to generate. | |
| poll_interval_ms | No | ||
| output_resolution | No | Output resolution. | |
| source_image_urls | Yes | Public source image URLs. | |
| enable_safety_checker | No | Enable the safety checker. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses the asynchronous nature (returns a task id) and outputs, but does not mention auth, costs, or other behavioral traits like polling or safety checker defaults. Adequate but not rich.
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, front-loaded sentence that conveys purpose and return values without redundancy. Every word earns its place.
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?
Despite having 11 parameters and no output schema, the description covers the essential return contract (task id, status, output URLs) and the core action. This is sufficient for an asynchronous task tool, though more detail on workflow could improve completeness.
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 82%, which is high, so the schema already documents most parameters. The description adds no extra parameter guidance, but it is not needed given the strong schema coverage. Baseline 3 is appropriate.
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 verb 'Create', the resource 'Flux 2 task', and the parenthetical 'remix image' distinguishes it from the sibling 'text_to_image'. It also specifies the key return values (task id, status, output URLs), leaving no ambiguity about what the tool does.
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 for image remixing with 'Flux 2' and distinguishes from the text-to-image sibling, but it does not explicitly state when to use this tool versus alternatives or any exclusions. Context is clear but not explicit.
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 2 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. | |
| timeout_ms | No | ||
| aspect_ratio | No | Output aspect ratio. | |
| callback_url | No | Webhook URL for async notifications. | |
| output_count | No | Number of images to generate. | |
| poll_interval_ms | No | ||
| output_resolution | No | Output resolution. | |
| enable_safety_checker | No | Enable the safety checker. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It discloses that the tool returns a task id, status, and output URLs, but it does not mention the asynchronous task nature, polling behavior, safety checker, or prerequisite login/authentication.
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 concise and front-loaded with the primary action ('Create a Flux 2 task'). It efficiently conveys the return value but could be slightly more structured with an additional context sentence.
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?
The tool has 10 parameters and no output schema, yet the description only covers the basic creation and return values. Important context such as model options, aspect ratios, safety checking, and async completion is missing, making it insufficient for a complex tool.
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 80%, so the schema already documents most parameters. The description adds no parameter-level details beyond what the schema provides, so it neither elevates nor detracts from the 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 uses a specific verb and resource: 'Create a Flux 2 task on RunAPI (text to image).' It clearly states the tool's function and differentiates from siblings like remix_image or get_task by focusing on text-to-image generation.
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 for text-to-image generation but does not explicitly state when to use this tool versus alternatives such as remix_image. It lacks exclusions or guidance on when not to use it.
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.
4 tool updates
v0.2.1- Changed
check_pricing1 field changed- changed
Input schema / properties / model / enumPrevious value: -[ - "flux-2-flex-remix-image", - "flux-2-pro-remix-image", - "flux-2-flex-text-to-image", - "flux-2-pro-text-to-image" -]New value: +[ + "flux-2-flex-remix-image", + "flux-2-max-remix-image", + "flux-2-pro-remix-image", + "flux-2-flex-text-to-image", + "flux-2-max-text-to-image", + "flux-2-pro-text-to-image" +]
- Changed
get_task1 field changed- changed
Input schema / properties / action / descriptionPrevious value: -"Endpoint the task was created on."New value: +"Asynchronous endpoint the task was created on."
- Changed
remix_image16 fields changed- added
Input schema / properties / aspect_ratio / descriptionAdded value: +"Output aspect ratio." - added
Input schema / properties / callback_urlAdded value: +{ + "description": "Webhook URL for async notifications.", + "type": "string" +} - added
Input schema / properties / enable_safety_checkerAdded value: +{ + "description": "Enable the safety checker.", + "type": "boolean" +} - changed
Input schema / properties / model / enumPrevious value: -[ - "flux-2-flex-remix-image", - "flux-2-pro-remix-image" -]New value: +[ + "flux-2-flex-remix-image", + "flux-2-max-remix-image", + "flux-2-pro-remix-image" +] - added
Input schema / properties / output_countAdded value: +{ + "description": "Number of images to generate.", + "enum": [ + 1 + ], + "type": "number" +} - added
Input schema / properties / output_resolution / descriptionAdded value: +"Output resolution." - added
Input schema / properties / prompt / descriptionAdded value: +"Image editing instruction." - added
Input schema / properties / prompt / maxLengthAdded value: +5000 - added
Input schema / properties / prompt / minLengthAdded value: +3 - added
Input schema / properties / prompt / typeAdded value: +"string" - added
Input schema / properties / source_image_urls / descriptionAdded value: +"Public source image URLs." - added
Input schema / properties / source_image_urls / itemsAdded value: +{} - added
Input schema / properties / source_image_urls / maxItemsAdded value: +8 - added
Input schema / properties / source_image_urls / minItemsAdded value: +1 - added
Input schema / properties / source_image_urls / typeAdded value: +"array" - added
Input schema / requiredAdded value: +[ + "prompt", + "source_image_urls" +]
- Changed
text_to_image11 fields changed- added
Input schema / properties / aspect_ratio / descriptionAdded value: +"Output aspect ratio." - added
Input schema / properties / callback_urlAdded value: +{ + "description": "Webhook URL for async notifications.", + "type": "string" +} - added
Input schema / properties / enable_safety_checkerAdded value: +{ + "description": "Enable the safety checker.", + "type": "boolean" +} - changed
Input schema / properties / model / enumPrevious value: -[ - "flux-2-flex-text-to-image", - "flux-2-pro-text-to-image" -]New value: +[ + "flux-2-flex-text-to-image", + "flux-2-max-text-to-image", + "flux-2-pro-text-to-image" +] - added
Input schema / properties / output_countAdded value: +{ + "description": "Number of images to generate.", + "enum": [ + 1 + ], + "type": "number" +} - added
Input schema / properties / output_resolution / descriptionAdded value: +"Output resolution." - added
Input schema / properties / prompt / descriptionAdded value: +"Image description." - added
Input schema / properties / prompt / maxLengthAdded value: +5000 - added
Input schema / properties / prompt / minLengthAdded value: +3 - added
Input schema / properties / prompt / typeAdded value: +"string" - added
Input schema / requiredAdded value: +[ + "prompt" +]
1 tool update
v0.1.6- Added
login
4 tool updates
v0.1.0- First observed
check_pricing - First observed
get_task - First observed
remix_image - First observed
text_to_image
TDQS
Scored across 5 tools
Each tool serves a distinct function: authentication, task status, pricing lookup, and two clearly separated image generation operations (remix vs. text-to-image). There is no overlap or ambiguity between tool purposes.
Most tool names follow a verb_noun pattern (login, get_task, check_pricing, remix_image), but text_to_image deviates by being a noun phrase rather than a verb_noun construction like create_text_to_image. The pattern is otherwise consistent and readable.
With 5 tools, the server is tightly scoped to the core workflow: authenticate, create two types of tasks, check task status, and look up pricing. This is a well-sized set with no redundant or unnecessary tools.
The tool surface covers the full lifecycle for a Flux-2 image generation service: setup (login), execution (remix_image and text_to_image), monitoring (get_task), and cost planning (check_pricing). There are no obvious gaps that would prevent an agent from completing common tasks.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
MCP server for Flux AI image generation
Official FLUX MCP server. Generate, edit, vary, and browse images from Black Forest Labs.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for Pixapi: check live credit pricing and balance, then generate images and video.
Related MCP Servers
- AlicenseAqualityAmaintenanceMCP server for the Flux Kontext model line that enables text-to-image generation, task status polling, and pricing lookup via RunAPI.443Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA simple MCP server for generating images using Flux models via the Replicate API.19MIT
- AlicenseAqualityAmaintenanceRunAPI MCP server for the Hailuo model line. Create tasks, poll their status, and check pricing through a single RunAPI API key.571Apache 2.0
- AlicenseAqualityAmaintenanceRunAPI MCP server for the Imagen 4 model line. Create tasks, poll their status, and check pricing through a single RunAPI API key.565Apache 2.0