Skip to main content
Glama
runapi-ai

@runapi.ai/flux-2-mcp

Official
by runapi-ai

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-mcp

Use project scope when the server should be shared with a repository:

claude mcp add flux-2 -s project -- npx -y @runapi.ai/flux-2-mcp

Codex, 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

remix_image

Yes

Create a Flux 2 remix image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

text_to_image

Yes

Create a Flux 2 text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

get_task

Yes

Fetch the current status and latest payload for an existing task.

check_pricing

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

remix_image

flux-2-flex-remix-image, flux-2-max-remix-image, flux-2-pro-remix-image

text_to_image

flux-2-flex-text-to-image, flux-2-max-text-to-image, flux-2-pro-text-to-image

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:

  1. RUNAPI_API_KEY environment variable, useful for headless and CI hosts

  2. ~/.config/runapi/config.json, created by the MCP login tool or runapi login

  3. No 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.


Resource

URL

Flux 2 model page

https://runapi.ai/models/flux-2

npm package

@runapi.ai/flux-2-mcp

GitHub repository

runapi-ai/flux-2-mcp

RunAPI MCP overview

runapi.ai/mcp

RunAPI docs

runapi.ai/docs


License

Licensed under the Apache License, Version 2.0.

Available Tools

5 tools
check_pricingA

Look up RunAPI pricing for the flux-2 model line.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoModel slug. Defaults to the line's primary model.
actionNoEndpoint name. Defaults to the endpoint that offers the model.

TDQS

A3.7/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAsynchronous endpoint the task was created on.
task_idYesTask id returned when the task was created.

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNoRe-run browser login when the current credential comes from the local config file.

TDQS

A4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoPoll until the task reaches a terminal status.
modelNoRunAPI model slug for this model line.
promptYesImage editing instruction.
timeout_msNo
aspect_ratioNoOutput aspect ratio.
callback_urlNoWebhook URL for async notifications.
output_countNoNumber of images to generate.
poll_interval_msNo
output_resolutionNoOutput resolution.
source_image_urlsYesPublic source image URLs.
enable_safety_checkerNoEnable the safety checker.

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoPoll until the task reaches a terminal status.
modelNoRunAPI model slug for this model line.
promptYesImage description.
timeout_msNo
aspect_ratioNoOutput aspect ratio.
callback_urlNoWebhook URL for async notifications.
output_countNoNumber of images to generate.
poll_interval_msNo
output_resolutionNoOutput resolution.
enable_safety_checkerNoEnable the safety checker.

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv0.2.1
    • Changedcheck_pricing1 field changed
      • changedInput schema / properties / model / enum
        Previous 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"
        +]
    • Changedget_task1 field changed
      • changedInput schema / properties / action / description
        Previous value: -"Endpoint the task was created on."New value: +"Asynchronous endpoint the task was created on."
    • Changedremix_image16 fields changed
      • addedInput schema / properties / aspect_ratio / description
        Added value: +"Output aspect ratio."
      • addedInput schema / properties / callback_url
        Added value: +{
        +  "description": "Webhook URL for async notifications.",
        +  "type": "string"
        +}
      • addedInput schema / properties / enable_safety_checker
        Added value: +{
        +  "description": "Enable the safety checker.",
        +  "type": "boolean"
        +}
      • changedInput schema / properties / model / enum
        Previous 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"
        +]
      • addedInput schema / properties / output_count
        Added value: +{
        +  "description": "Number of images to generate.",
        +  "enum": [
        +    1
        +  ],
        +  "type": "number"
        +}
      • addedInput schema / properties / output_resolution / description
        Added value: +"Output resolution."
      • addedInput schema / properties / prompt / description
        Added value: +"Image editing instruction."
      • addedInput schema / properties / prompt / maxLength
        Added value: +5000
      • addedInput schema / properties / prompt / minLength
        Added value: +3
      • addedInput schema / properties / prompt / type
        Added value: +"string"
      • addedInput schema / properties / source_image_urls / description
        Added value: +"Public source image URLs."
      • addedInput schema / properties / source_image_urls / items
        Added value: +{}
      • addedInput schema / properties / source_image_urls / maxItems
        Added value: +8
      • addedInput schema / properties / source_image_urls / minItems
        Added value: +1
      • addedInput schema / properties / source_image_urls / type
        Added value: +"array"
      • addedInput schema / required
        Added value: +[
        +  "prompt",
        +  "source_image_urls"
        +]
    • Changedtext_to_image11 fields changed
      • addedInput schema / properties / aspect_ratio / description
        Added value: +"Output aspect ratio."
      • addedInput schema / properties / callback_url
        Added value: +{
        +  "description": "Webhook URL for async notifications.",
        +  "type": "string"
        +}
      • addedInput schema / properties / enable_safety_checker
        Added value: +{
        +  "description": "Enable the safety checker.",
        +  "type": "boolean"
        +}
      • changedInput schema / properties / model / enum
        Previous 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"
        +]
      • addedInput schema / properties / output_count
        Added value: +{
        +  "description": "Number of images to generate.",
        +  "enum": [
        +    1
        +  ],
        +  "type": "number"
        +}
      • addedInput schema / properties / output_resolution / description
        Added value: +"Output resolution."
      • addedInput schema / properties / prompt / description
        Added value: +"Image description."
      • addedInput schema / properties / prompt / maxLength
        Added value: +5000
      • addedInput schema / properties / prompt / minLength
        Added value: +3
      • addedInput schema / properties / prompt / type
        Added value: +"string"
      • addedInput schema / required
        Added value: +[
        +  "prompt"
        +]
  2. 1 tool updatev0.1.6
    • Addedlogin
  3. 4 tool updatesv0.1.0
    • First observedcheck_pricing
    • First observedget_task
    • First observedremix_image
    • First observedtext_to_image

TDQS

A3.9/5.0

Scored across 5 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivitySlowing
ResponsivenessNo issues

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

Related MCP Servers