OpenCode Integration with Flux MCP

📘 Overview：OpenCode MCP Overview →

The Flux series produced by Black Forest Labs is one of the strongest open-source image models in terms of realistic style performance and the most convenient image editing capabilities (Kontext). After connecting the Flux MCP Server in OpenCode, AI can directly generate or edit images based on the current conversation context, suitable for commercial materials and high-fidelity illustrations.

Flux MCP is suitable for creating product hero images, realistic portraits, commercial advertising materials, and editing existing images based on text descriptions through the Kontext model—such as changing backgrounds, styles, or text.

Obtain API Token

Before using the Flux MCP Server, you need to prepare an Ace Data Cloud API Token. OpenCode and Claude Code share a set of Tokens, and the acquisition process is the same:

  1. Open the Ace Data Cloud Console - Application List to obtain your API Token for backup.
  2. If you are not logged in or registered, you will be automatically redirected to the login page; after logging in or registering, you will be automatically returned to the current page.
  3. The first application will have a free quota granted, allowing you to experience the Flux MCP service for free.

One Token can be used for all 11 MCP Servers provided by AceData Cloud, without needing to apply separately for Flux. The documentation and screenshots suggest displaying only a desensitized form, such as 3b78cc40dd3b43db806a4300...., and do not paste the complete Token into public repositories, issues, screenshots, or chat records.

Want to use Claude Desktop / Claude.ai web version for direct OAuth one-click authorization? Please see the Claude.ai / Desktop tutorial for Flux MCP.

Configure OpenCode

OpenCode uses a single opencode.json to describe all MCP Servers, and the file can be placed in two locations; choose one according to the "scope of application" below. The field structure in both locations is exactly the same, with the only difference being priority.

It is strongly recommended to first write the Token to an environment variable:

export ACEDATACLOUD_API_KEY="replace with your real Token"

Then reference it in opencode.json using the {env:ACEDATACLOUD_API_KEY} placeholder to avoid writing the real Token into the file.

Global: Shared by all projects

File location: ~/.config/opencode/opencode.json, suitable for "my own machine, configured once, usable by all projects."

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

⚠️ "oauth": false cannot be omitted. AceData's MCP Server uses Bearer Token authentication and does not go through the OAuth process; OpenCode will by default treat 401 as an OAuth challenge and automatically redirect, causing opencode mcp list to show SSE error: Non-200 status code (401). Explicitly declaring "oauth": false allows OpenCode to call directly with Authorization: Bearer ..., and opencode mcp debug flux will also echo OAuth explicitly disabled, indicating it is effective.

Project-level: Effective only for the current project

File location: opencode.json in the current project root directory, which will override the global configuration. Suitable for team sharing, single repository customization, or temporarily enabling a specific MCP in a certain project.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

If the project-level opencode.json will be committed to Git, please ensure to use the {env:ACEDATACLOUD_API_KEY} placeholder instead of the real Token to avoid leakage.

💡 If the .env in Shell is not explicitly exported, you need to use set -a && source .env && set +a to pass the variables to the OpenCode process; otherwise, opencode debug config will show "Authorization": "Bearer " (placeholder not resolved).

Actual Run Results

Below is the desensitized output after actual execution in OpenCode 1.15.13 using an isolated temporary directory. The command used the real AceData Cloud Token, and the Token in the output has been replaced with 357265014ad145fc8ab2...., and the temporary configuration has been deleted.

$ opencode --version
1.15.13

$ opencode mcp list

┌  MCP Servers
│
●  ✓ flux connected
│      https://flux.mcp.acedata.cloud/mcp
│
└  1 server(s)

Seeing ✓ flux connected indicates that the Flux MCP has been successfully integrated. If it shows ✗ or unauthorized, please check whether ACEDATACLOUD_API_KEY is set, whether the Token is copied completely, and whether the Authorization prefix is Bearer (pay attention to case and spaces).

To debug the connection details of a specific MCP:

opencode mcp debug flux

After a successful handshake, OpenCode's INFO log will output service=mcp key=flux transport=StreamableHTTP connected and service=mcp key=flux toolCount=6 (tested with 6 tools), indicating that the Flux MCP is ready to be called by the model.

🤖 Model selection testing suggestions: To truly allow the model to actively call Flux MCP in OpenCode, please prioritize using OpenAI series models (such as acedatacloud/gpt-5-mini, acedatacloud/gpt-5). When the Claude series models on AceData are exposed through the OpenAI compatible interface, tool calls often return Improperly formed request (tested: acedatacloud/claude-haiku-4-5-20251001, acedatacloud/claude-sonnet-4-6 reported this error when mounting multiple MCPs). Claude models can be used normally when only doing conversations without calling tools.

Typical Scenarios

After configuration is complete, you can directly call using natural language in the OpenCode session without switching to /mcp:

Quick Image Generation

Generate a cyberpunk style city night scene with neon lights, rainy night, and wet streets using Flux.

Kontext Editing of Existing Images

Change this image (link xxx) to a watercolor style.

Generate Product Hero Image

Generate a 1024x1024 product hero image: black metallic headphones floating on a white background.

Tool List

The table below lists the main tools (The Flux MCP Server has exposed a total of 6 tools, which can be obtained through curl -X POST https://flux.mcp.acedata.cloud/mcp -H 'Authorization: Bearer <token>' -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' for a complete list):

Tool Description
flux_generate_image Text-to-image (Flux pro / dev / ultra)
flux_edit_image Edit existing images based on prompts (Flux Kontext pro / max)