Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bfl.ml/llms.txt

Use this file to discover all available pages before exploring further.

FLUX integrates with AI agents through two complementary channels:
  • MCP (Model Context Protocol) lets Claude Desktop, Claude.ai, or any MCP-compatible app generate and edit images directly with FLUX.
  • Agent Skills teach AI coding assistants (Claude Code, Cursor, Windsurf, …) how to prompt FLUX effectively and integrate the API correctly.
MCPAgent Skills
What it doesLets your agent generate images directlyTeaches your agent FLUX knowledge
Use caseGenerating images in conversationWriting code that uses FLUX
Install onClaude Desktop / Claude.aiAny agent system (Claude Code, Cursor, Windsurf, …)
You can use both together. MCP handles direct image generation in Claude, Skills helps you write FLUX integrations in your codebase.

​
MCP Integration

The FLUX MCP server provides access to all FLUX models through the Model Context Protocol. Generate and edit images using natural language in Claude.

​
Available models

  • FLUX.2 [pro] — Best balance of quality, speed, and cost. Recommended default for all tasks. Supports text-to-image and image-to-image with up to 8 reference images.
  • FLUX.2 [max] — Highest quality output. Use for hero images and final deliverables. Up to 8 reference images.
  • FLUX.2 [flex] — Optimized for text and typography rendering. Up to 8 reference images.
  • FLUX.2 [klein] 9B — Fast and affordable with good quality. Up to 4 reference images.
  • FLUX.2 [klein] 4B — Fastest and cheapest. Great for rapid iterations. Up to 4 reference images.

​
Setup Instructions

​
Claude Code

1

Add the MCP server

Run the following command in your terminal:
claude mcp add --transport http bfl-flux https://bfl-mcp-production.up.railway.app
2

Sign in with your BFL account

On first use, a browser window opens for OAuth sign-in. Select which organization to use for billing and approve the connection.

​
Claude Desktop & Claude.ai

In Claude Desktop or on Claude.ai, go to Settings → Developer Settings → Edit Config to open claude_desktop_config.json, then add the BFL MCP server under Local MCP Servers.
1

Add MCP server configuration

Add the following to your claude_desktop_config.json file:
{
  "mcpServers": {
    "bfl-flux": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://bfl-mcp-production.up.railway.app"
      ]
    }
  }
}
2

Restart and sign in

Quit and restart Claude Desktop (or refresh Claude.ai). On first use, a browser window opens where you sign in with your BFL account and select which organization to use for billing. The FLUX tools then appear automatically in Claude’s tool list.

​
Usage

Once connected, ask Claude to generate or edit images in natural language. You can specify which model to use, or let Claude pick one based on your prompt.
Describe what you want — portraits, illustrations, product shots, wildlife, and more.

​
Pricing

Usage is billed to the BFL organization you selected during the OAuth sign-in. See current pricing at bfl.ai/pricing.

​
Troubleshooting

  1. Verify your claude_desktop_config.json is formatted correctly (valid JSON)
  2. Ensure you’ve fully restarted Claude Desktop (quit and reopen)
  3. Check that the OAuth sign-in completed successfully in your browser
  4. Look for error messages in Claude Desktop’s developer console
  • Make sure you have a BFL account at bfl.ai
  • Try disconnecting and reconnecting the MCP server to redo the OAuth flow
  • Check that your account has sufficient credits for generation
  • If the browser sign-in window did not appear, ensure pop-ups are not blocked
  • The default timeout is 300 seconds (5 minutes)
  • Check the BFL API status at status.bfl.ai
  • Try again with a simpler prompt or lower resolution
  • Verify your network connection is stable
  • Use more detailed and specific prompts
  • Try FLUX.2 [flex]
  • Refer to the Prompting Guide for best practices
  • Experiment with different aspect ratios and parameters
To bill a different organization, disconnect the BFL MCP server from your client and reconnect it. The OAuth flow will prompt you to select an organization again.

​
Best Practices

  • Use specific prompts: Include details about style, lighting, composition, and subject for best results
  • Start with FLUX.2 [pro]: Best balance of quality, speed, and cost for both generation and editing
  • Iterate on results: Refine your prompt if the first generation isn’t perfect
  • Monitor usage: Track API usage through the BFL dashboard

​
Agent Skills

Skills are reusable capabilities for AI agents. Install them with a single command to enhance your agent with access to procedural knowledge — in this case, everything about FLUX prompting and API integration. When you install BFL Skills, your AI coding assistant (Claude Code, Cursor, Windsurf, or any compatible tool) gains expert-level knowledge of FLUX. It knows how to write effective prompts, which model to use for each task, and how to integrate the API properly.

​
Installation

/plugin marketplace add black-forest-labs/skills
/plugin install flux-best-practices@bfl-skills

​
What Your Agent Learns

​
flux-best-practices

Prompting knowledge for all FLUX models:
  • Prompt structure — The formula that works: [Subject] + [Action] + [Style] + [Context] + [Lighting] + [Technical]
  • No negative prompts — FLUX doesn’t support them. Describe what you want, not what you don’t.
  • Lighting vocabulary — Golden hour, softbox, rim light, Rembrandt, volumetric fog, and more
  • Hex colors — Precise color control with #RRGGBB format
  • Typography — How to render text in images using quoted strings
  • Model selection — When to use FLUX.2 [klein] vs [max] vs [pro], when to use Kontext, etc.

​
bfl-api

API integration patterns:
  • Async polling — Use the polling_url from responses, implement exponential backoff
  • Rate limits — 24 concurrent requests (6 for Kontext Max), how to handle 429s
  • URL expiration — Download images within 10 minutes
  • Regional endpoints — api.eu.bfl.ai for GDPR, api.us.bfl.ai for US data residency
  • Webhooks — Production webhook setup and verification

​
Example: Before and After

Without skills, your agent might generate this prompt: 
a cat sitting
With BFL Skills, your agent writes prompts like this: 
A fluffy orange tabby cat with bright green eyes sitting regally on a vintage
velvet armchair, afternoon sunlight streaming through lace curtains creating
warm golden hour lighting, shallow depth of field with soft bokeh background,
shot on medium format camera
And when writing integration code, it knows to: 
# Use the polling_url (don't construct URLs manually)
polling_url = response.json()["polling_url"]

# Poll with exponential backoff
delay = 1
while True:
    result = requests.get(polling_url, headers={"x-key": API_KEY}).json()
    if result["status"] == "completed":
        # Download immediately — URL expires in 10 min
        image_url = result["result"]["url"]
        break
    time.sleep(delay)
    delay = min(delay * 2, 30)

​
Updating

npx skills update black-forest-labs/skills

​
Resources