OpenCode Integration with Flux MCP

📘 Overview：OpenCode MCP Overview →

Flux supports realistic style image generation and Kontext image editing. After integrating the Flux MCP Server into OpenCode, images can be generated or edited based on the current conversation context.

Flux MCP is suitable for creating product hero images, realistic portraits, commercial advertising materials, and for editing existing images based on text descriptions using 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 the same Token, and the acquisition process is the same:

  1. Open the Ace Data Cloud Console - Application List to obtain your API Token for future use.
  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 come with a free quota, allowing you to experience the Flux MCP service for free.

Obtain Ace Data Cloud API Key

One Token can be used for all MCP Servers provided by Ace Data Cloud, and there is no need to apply separately for Flux. The documentation and screenshots suggest displaying only a masked format, such as YOUR_ACEDATACLOUD_API_KEY, and not posting the full Token in 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 file to describe all MCP Servers, which can be placed in two locations; choose one based on the "scope" below. The field structure in both locations is identical, 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 automatically redirect 401 as an OAuth challenge, resulting in opencode mcp list showing 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 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 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).

Verify Connection

After configuration, run:

opencode mcp list
opencode mcp debug flux

Seeing flux connected indicates a successful handshake. If it fails, check whether ACEDATACLOUD_API_KEY has been exported, whether oauth is set to false, and whether Authorization includes the Bearer prefix. The model and tool Schema will continue to change, so please select models that support native tool calls from the current directory.

Typical Scenarios

After configuration, 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 Edit Existing Image

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; you can obtain the current complete list by using 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"}':

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