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

Property	Value
Name	`tokenflux-images`
Version	`1.0.0`
Transport	Streamable HTTP
Endpoint	`POST/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:

Name	Type	Required	Description
`model_id`	string	Yes	The 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:

Name	Type	Required	Description
`model_id`	string	Yes	The ID of the model (from `list_models`)
`input`	object	Yes	Input 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:

Name	Type	Required	Description
`id`	string	Yes	The 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

Status	Meaning
`starting`	Job was accepted and queued
`processing`	Provider is generating the image
`succeeded`	Images are available in the `images` array
`failed`	Generation failed; `error` field contains details
`canceled`	Job was canceled

Recommended Workflow

For best results, AI assistants should follow this workflow:

Discover models: Call list_models to see available options
Get input schema: Call get_model to understand required parameters
Generate image: Call generate_image with proper input
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:

Error	Cause
`model_id is required`	Missing required parameter
`model not found: <id>`	Invalid model ID
`input is required and must be an object`	Missing or invalid input
`invalid id format`	Malformed UUID in `get_generation`

Example Conversation

User: Generate an image of a sunset over mountains Assistant (using MCP tools):

Calls list_models → finds black-forest-labs/flux-schnell
Calls get_model with model_id: "black-forest-labs/flux-schnell" → gets input schema

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"
  }
}

Returns image URL to user

Images REST API - Direct HTTP API for image generation
Model Context Protocol - MCP specification

LLM Endpoints

Image Generation

Images MCP Server

Images MCP Server

Server Information

Authentication

Configuration

Claude Desktop

Other MCP Clients

Available Tools

list_models

get_model

generate_image

get_generation

Status Values

Recommended Workflow

Error Handling

Example Conversation

​Images MCP Server

​Server Information

​Authentication

​Configuration

​Claude Desktop

​Other MCP Clients

​Available Tools

​list_models

​get_model

​generate_image

​get_generation

​Status Values

​Recommended Workflow

​Error Handling

​Example Conversation

​Related

Images MCP Server

Server Information

Authentication

Configuration

Claude Desktop

Other MCP Clients

Available Tools

list_models

get_model

generate_image

get_generation

Status Values

Recommended Workflow

Error Handling

Example Conversation

Related