Skip to main content

​
Images MCP Server

TokenFlux provides a Model Context Protocol (MCP) server for image generation, enabling AI assistants like Claude to generate images through a standardized tool interface.

​
Server Information

PropertyValue
Nametokenflux-images
Version1.0.0
TransportStreamable HTTP
EndpointPOST/GET /v1/images/mcp

​
Authentication

The MCP endpoint requires authentication via one of:
  • Authorization: Bearer <api_key> header
  • X-Api-Key: <api_key> header
Requests are rejected with 403 Forbidden when the caller has less than 0.01 credits remaining.

​
Configuration

​
Claude Desktop

Add the following to your Claude Desktop configuration (claude_desktop_config.json): 
{
  "mcpServers": {
    "tokenflux-images": {
      "url": "https://tokenflux.ai/v1/images/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

​
Other MCP Clients

For other MCP-compatible clients, use:
  • URL: https://tokenflux.ai/v1/images/mcp
  • Transport: streamable-http (stateless)
  • Auth Header: Authorization: Bearer YOUR_API_KEY

​
Available Tools

The MCP server exposes 4 tools for image generation:

​
list_models

List all available VLM models with their IDs, names, descriptions, and pricing. Parameters: None Response: 
[
  {
    "id": "black-forest-labs/flux-schnell",
    "name": "FLUX.1 [schnell]",
    "description": "The fastest image generation model tailored for local development",
    "pricing": { "price": 0.025, "currency": "USD", "unit": 1 }
  }
]

​
get_model

Get detailed information about a specific model including its input schema. Parameters:
NameTypeRequiredDescription
model_idstringYesThe ID of the model (from list_models)
Response: 
{
  "id": "black-forest-labs/flux-schnell",
  "name": "FLUX.1 [schnell]",
  "description": "The fastest image generation model tailored for local development",
  "pricing": { "price": 0.025, "currency": "USD", "unit": 1 },
  "input_schema": {
    "properties": {
      "prompt": { "type": "string", "description": "Prompt for generated image" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "21:9", "3:2"] },
      "num_outputs": { "type": "integer", "default": 1 }
    }
  }
}

​
generate_image

Generate an image using a VLM model.
Always call get_model first to get the correct input_schema for your model.
Parameters:
NameTypeRequiredDescription
model_idstringYesThe ID of the model (from list_models)
inputobjectYesInput parameters conforming to the model’s input_schema
Behavior:
  • Waits up to 30 seconds for the image to complete
  • If completed: returns status: "succeeded" with images array
  • If still processing: returns status: "processing" with id for polling
Response (completed): 
{
  "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
  "status": "succeeded",
  "images": [
    { "url": "https://replicate.delivery/pbxt/abc123.png" }
  ]
}
Response (still processing): 
{
  "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
  "status": "processing"
}

​
get_generation

Get the status and result of an image generation request. Parameters:
NameTypeRequiredDescription
idstringYesThe UUID of the generation (from generate_image)
Response: 
{
  "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
  "model": "black-forest-labs/flux-schnell",
  "status": "succeeded",
  "images": [
    { "url": "https://replicate.delivery/pbxt/abc123.png" }
  ],
  "cost": 0.025
}

​
Status Values

StatusMeaning
startingJob was accepted and queued
processingProvider is generating the image
succeededImages are available in the images array
failedGeneration failed; error field contains details
canceledJob was canceled
For best results, AI assistants should follow this workflow:
  1. Discover models: Call list_models to see available options
  2. Get input schema: Call get_model to understand required parameters
  3. Generate image: Call generate_image with proper input
  4. Poll if needed: If status is processing, call get_generation until complete

​
Error Handling

MCP tool errors are returned with IsError: true and a text message:
ErrorCause
model_id is requiredMissing required parameter
model not found: <id>Invalid model ID
input is required and must be an objectMissing or invalid input
invalid id formatMalformed UUID in get_generation

​
Example Conversation

User: Generate an image of a sunset over mountains Assistant (using MCP tools):
  1. Calls list_models → finds black-forest-labs/flux-schnell
  2. Calls get_model with model_id: "black-forest-labs/flux-schnell" → gets input schema
  3. Calls generate_image with: 
    {
  "model_id": "black-forest-labs/flux-schnell",
  "input": {
    "prompt": "A beautiful sunset over snow-capped mountains, golden hour lighting, photorealistic",
    "aspect_ratio": "16:9"
  }
}
  4. Returns image URL to user