> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenflux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Images MCP Server

> Model Context Protocol server for AI-assisted image generation

# Images MCP Server

TokenFlux provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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`):

```json theme={null}
{
  "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**:

```json theme={null}
[
  {
    "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**:

```json theme={null}
{
  "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.

<Warning>
  Always call `get_model` first to get the correct `input_schema` for your model.
</Warning>

**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)**:

```json theme={null}
{
  "id": "0a4c1d62-2cd0-4cf1-9e0c-1b2f7f4f5678",
  "status": "succeeded",
  "images": [
    { "url": "https://replicate.delivery/pbxt/abc123.png" }
  ]
}
```

**Response (still processing)**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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:

```mermaid theme={null}
flowchart TD
    A[list_models] --> B[get_model]
    B --> C[generate_image]
    C --> D{status?}
    D -->|succeeded| E[Display images]
    D -->|processing| F[get_generation]
    F --> D
    D -->|failed| G[Show error]
```

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:

| 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):

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:
   ```json theme={null}
   {
     "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

## Related

* [Images REST API](./images) - Direct HTTP API for image generation
* [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification