ImageGenMcp.Server 3.0.0

{
  "inputs": [
    {
      "type": "promptString",
      "id": "AzureFoundry__Endpoint",
      "description": "Azure AI Foundry / Azure OpenAI resource endpoint, e.g. https://YOUR-RESOURCE-NAME.openai.azure.com/"
    },
    {
      "type": "promptString",
      "id": "AzureFoundry__ApiKey",
      "description": "Azure OpenAI API key. Leave empty and set AzureFoundry__Authentication=EntraId to use DefaultAzureCredential instead.",
      "password": true
    },
    {
      "type": "pickString",
      "id": "AzureFoundry__Authentication",
      "description": "ApiKey (default) or EntraId.",
      "default": "ApiKey",
      "options": ["ApiKey", "EntraId"]
    },
    {
      "type": "promptString",
      "id": "AzureFoundry__Models__premium__Model",
      "description": "Model or deployment name for the 'premium' tier (default tier). Highest quality and most precise edits.",
      "default": "gpt-image-2.5-sunburst"
    },
    {
      "type": "promptString",
      "id": "AzureFoundry__Models__fast__Model",
      "description": "Model or deployment name for the 'fast' tier. Low latency, strong everyday quality.",
      "default": "gpt-image-2.5-flare"
    },
    {
      "type": "promptString",
      "id": "AzureFoundry__Models__legacy__Model",
      "description": "Model or deployment name for the 'legacy' tier (previous-generation engine).",
      "default": "gpt-image-2"
    },
    {
      "type": "pickString",
      "id": "AzureFoundry__DefaultTier",
      "description": "Tier used when a client does not choose one.",
      "default": "premium",
      "options": ["premium", "fast", "legacy"]
    },
    {
      "type": "promptString",
      "id": "AzureFoundry__OutputDirectory",
      "description": "Directory where generated and edited images are saved so follow-up edits can chain on the returned path. Defaults to %TEMP%/image-gen-mcp."
    }
  ],
  "servers": {
    "imagegenmcp.server": {
      "type": "stdio",
      "command": "dnx",
      "args": ["imagegenmcp.server@3.0.0", "--yes"],
      "env": {
        "AzureFoundry__Endpoint": "${input:AzureFoundry__Endpoint}",
        "AzureFoundry__ApiKey": "${input:AzureFoundry__ApiKey}",
        "AzureFoundry__Authentication": "${input:AzureFoundry__Authentication}",
        "AzureFoundry__Models__premium__Model": "${input:AzureFoundry__Models__premium__Model}",
        "AzureFoundry__Models__fast__Model": "${input:AzureFoundry__Models__fast__Model}",
        "AzureFoundry__Models__legacy__Model": "${input:AzureFoundry__Models__legacy__Model}",
        "AzureFoundry__DefaultTier": "${input:AzureFoundry__DefaultTier}",
        "AzureFoundry__OutputDirectory": "${input:AzureFoundry__OutputDirectory}"
      }
    }
  }
}
                    
This package contains an MCP Server. The server can be used in VS Code by copying the generated JSON to your VS Code workspace's .vscode/mcp.json settings file.
dotnet tool install --global ImageGenMcp.Server --version 3.0.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local ImageGenMcp.Server --version 3.0.0
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=ImageGenMcp.Server&version=3.0.0
                    
nuke :add-package ImageGenMcp.Server --version 3.0.0
                    

ImageGen MCP Server

A .NET/C# Model Context Protocol (MCP) server over stdio for creating and editing images through Azure AI Foundry / Azure OpenAI. It supports OpenAI's GPT Image 2.5 models (gpt-image-2.5-sunburst and gpt-image-2.5-flare) alongside gpt-image-2, exposes them to MCP clients as intent-based tiers, and returns actual MCP image content blocks (image/png, image/jpeg, or image/webp) instead of plain URLs.

Quick start

With .NET SDK 10 or later, add the package to your MCP client (VS Code, Visual Studio, Claude Code, Cursor, ...) and run it with dnx:

{
  "servers": {
    "image-gen": {
      "type": "stdio",
      "command": "dnx",
      "args": ["ImageGenMcp.Server@3.0.0", "--yes"],
      "env": {
        "AzureFoundry__Endpoint": "https://YOUR-RESOURCE-NAME.openai.azure.com/",
        "AzureFoundry__ApiKey": "YOUR_AZURE_OPENAI_API_KEY"
      }
    }
  }
}

That is enough to get the built-in tiers (premium = gpt-image-2.5-sunburst, fast = gpt-image-2.5-flare, legacy = gpt-image-2). If your Azure resource uses different deployment names, see Configuration.

What is included

  • generate_image MCP tool for image creation.
  • edit_image MCP tool for image editing from local file paths, with an optional mask and up to 15 extra reference images.
  • describe_image_capabilities MCP tool that reports the configured tiers, defaults, and supported options.
  • Multi-model support: a configurable tier → model/deployment catalog with a default tier (Sunburst) and an optional separate default for edits.
  • MCP server instructions, generated from the live catalog, that tell the client which tier to pick for what kind of work and how to write effective edit prompts.
  • Automatic persistence of every result to an output directory so edits can chain on the returned path.
  • Azure Foundry v1 image endpoint support: /openai/v1/images/{generations|edits}?api-version=preview.
  • Azure deployment endpoint compatibility: /openai/deployments/{deployment}/images/{generations|edits}?api-version=....
  • API key auth and Microsoft Entra ID auth with configurable token scope.
  • Hardened local file handling: absolute local paths only, full PNG/JPEG/WebP decoding, MIME detection from bytes, mask alpha/dimension validation, per-file and aggregate size budgets, bounded response bodies, and URL-only responses rejected.
  • Tests around the model catalog, request construction, per-model validation, response decoding, output persistence, tool contracts, and DI wiring.

Package baseline

Package Version Purpose
ModelContextProtocol 1.2.0 Official C# MCP SDK, stdio transport, tool attributes, image content blocks, server instructions
Microsoft.Extensions.Hosting 10.0.7 Generic host for the stdio server
Microsoft.Extensions.Http 10.0.7 Typed HttpClient for Azure Foundry calls
Microsoft.Extensions.Options.ConfigurationExtensions 10.0.7 Configuration binding
Microsoft.Extensions.Configuration.UserSecrets 10.0.7 Local secret support
Microsoft.Extensions.Logging.Console 10.0.7 Logging to stderr for MCP stdio safety
Azure.Identity 1.21.0 Optional Entra ID auth with DefaultAzureCredential
SixLabors.ImageSharp 3.1.11 Managed PNG/JPEG/WebP decoding and mask metadata validation

Note: The OpenAI/Azure .NET SDKs expose image functionality, but the newest image model surfaces can lag in strongly typed SDK options. This server calls the Azure Foundry image REST endpoints directly and exposes only image-generation/editing controls that are useful to an MCP client.

Model tiers

MCP clients never see raw model names. They choose a tier by intent (or omit it), and configuration maps each tier to a model (v1 flow) or deployment name (deployment flow). The built-in catalog, used when nothing is configured, is:

Tier Default model Family Use it for
premium (default) gpt-image-2.5-sunburst GPT Image 2.5 Final assets, complex compositions, legible text/diagrams, and edits that must preserve identity, product geometry, layout, or background.
fast gpt-image-2.5-flare GPT Image 2.5 Drafts, brainstorming, many variations, quick iterations, latency-sensitive work. Roughly half the latency of gpt-image-2 with comparable or better quality.
legacy gpt-image-2 GPT Image 2 Only when explicitly requested, or as a rollback target.

How the choice gets made:

  1. Server instructions. On initialize, the server sends instructions listing the configured tiers, which is the default for generation and for edits, what quality/format/background options each supports, and short rules for choosing. Most MCP clients feed this to the model as system context.
  2. Tool parameter guidance. The tier parameter description on both tools explains premium/fast/legacy in terms of the type of work, so the model can map a user's request ("quick mockup", "final hero image", "keep the product exactly the same") to a tier.
  3. No silent substitution. If a client asks for a tier that is not configured, the call fails with the list of configured tiers (a different model could change cost and latency). In single-model mode the tier is ignored and the response says so.
  4. Discovery. describe_image_capabilities returns the same report on demand for clients that do not surface server instructions.

The family determines validation. It is inferred from the model name (gpt-image-2.5, sunburst, flare → GPT Image 2.5; gpt-image-2 → GPT Image 2) and can be overridden per tier with Family when you use custom deployment names. Unknown families are validated leniently and let the API report unsupported options.

Capability GPT Image 2 GPT Image 2.5 (Flare, Sunburst)
quality auto, low, medium, high auto, low, medium, high, xhigh, max
outputFormat png, jpeg, webp png, jpeg, webp
outputCompression jpeg or webp jpeg or webp
background=transparent not supported (rejected with guidance) supported with png or webp
Custom size multiples of 16, long edge ⇐ 3840, aspect ⇐ 3:1, 655,360-8,294,400 px same

Configuration

The server reads configuration from appsettings.json, environment variables, user-secrets, and a local .env file (ignored by git).

Recommended API key setup with all three tiers:

AzureFoundry__Endpoint=https://YOUR-RESOURCE-NAME.openai.azure.com/
AzureFoundry__ApiKey=YOUR_AZURE_OPENAI_API_KEY
AzureFoundry__ApiVersion=preview
AzureFoundry__EndpointMode=V1Images
AzureFoundry__Authentication=ApiKey

AzureFoundry__Models__premium__Model=gpt-image-2.5-sunburst
AzureFoundry__Models__fast__Model=gpt-image-2.5-flare
AzureFoundry__Models__legacy__Model=gpt-image-2
AzureFoundry__DefaultTier=premium

Useful variations:

# Fast for everyday generation, Sunburst for edits
AzureFoundry__DefaultTier=fast
AzureFoundry__DefaultEditTier=premium

# Custom deployment names that cannot be inferred
AzureFoundry__Models__premium__Model=img-prod-a
AzureFoundry__Models__premium__Family=gpt-image-2.5
AzureFoundry__Models__premium__Description=Client-approved renders only.

# 2.x single-model mode: only gpt-image-2 is deployed (every tier resolves to it)
AzureFoundry__Model=gpt-image-2
AzureFoundry__ModelFamily=gpt-image-2

Resolution rules: if any AzureFoundry__Models__* entries exist they define the catalog and AzureFoundry__Model is ignored (with a warning); every entry must set Model, and the names auto/default are reserved. If no entries exist but AzureFoundry__Model is set, the server runs in 2.x-compatible single-model mode (ModelFamily still selects validation). If neither is set, the built-in GPT Image 2.5 catalog above is used. DefaultTier (and DefaultEditTier when set) must name a configured tier; otherwise startup fails with a clear message.

For Entra ID / managed identity:

AzureFoundry__Endpoint=https://YOUR-RESOURCE-NAME.openai.azure.com/
AzureFoundry__ApiVersion=preview
AzureFoundry__EndpointMode=V1Images
AzureFoundry__Authentication=EntraId
AzureFoundry__TokenScope=https://ai.azure.com/.default

If your Azure resource requires the classic Azure OpenAI audience instead, set:

AzureFoundry__TokenScope=https://cognitiveservices.azure.com/.default

Endpoint modes

Mode URL shape When to use
V1Images /openai/v1/images/generations?api-version=preview with the tier's model in the body Preferred Azure Foundry/OpenAI-compatible v1 flow
DeploymentImages /openai/deployments/{tier model}/images/generations?api-version=2025-04-01-preview Older Azure OpenAI deployment-name flow; each tier's Model is the deployment name

Output persistence

Setting Default Purpose
PersistOutputs true Save every generated/edited image (unless the caller passes saveToPath) and return the path so edits can chain.
OutputDirectory %TEMP%/image-gen-mcp Where auto-saved results go. Files are named generated-<utc timestamp>-<id>.<ext> / edited-....

Safety limits

Setting Default Purpose
MaxPromptCharacters 32000 Bounds prompt size
MaxImagesPerRequest 10 Bounds n
MaxInputImageBytes 52428800 Configured per-file ceiling; the provider's strict < 50 MiB hard limit still applies
MaxInputRequestBytes 209715200 Aggregate byte budget across primary, mask, and reference images
MaxOutputImageBytes 52428800 Bounds each decoded base64 image
MaxResponseBodyBytes 209715200 Bounds the complete Azure response body before JSON parsing
TimeoutSeconds 300 Bounds Azure Foundry calls

MCP client registration

Package-based (recommended), pinned to a version:

{
  "mcpServers": {
    "image-gen": {
      "command": "dnx",
      "args": ["ImageGenMcp.Server@3.0.0", "--yes"]
    }
  }
}

If the package is on a private feed, add the feed either through nuget.config or with --add-source https://YOUR-FEED-URL/index.json after the package reference. dnx downloads and runs the tool without permanently installing it. The packaged tool command name is image-gen-mcp, which is used when installing the package as a global or local .NET tool.

From source:

{
  "mcpServers": {
    "image-gen": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "D:\\git\\image-gen\\src\\ImageGenMcp.Server\\ImageGenMcp.Server.csproj"
      ]
    }
  }
}

Tools

generate_image

Use when a user wants a new image created from a text description. The tool returns image content directly and, by default, saves it and returns the path.

Parameter Default Notes
prompt required Describe subject, setting, style, composition, lighting, colors, mood, camera/framing, exact text, and constraints.
tier configured default premium, fast, or legacy (or any custom configured tier). Omit for the default. Unknown tiers are rejected with the list of configured tiers.
size auto Use auto unless exact dimensions/aspect ratio matter. Custom dimensions use WIDTHxHEIGHT; both edges must be multiples of 16, long edge ⇐ 3840px, aspect ratio ⇐ 3:1, and total pixels between 655,360 and 8,294,400.
quality high low drafts, medium balanced, high final. xhigh/max for maximum detail on GPT Image 2.5 tiers (more latency/cost). auto lets the model choose.
background unset (auto) opaque forces a solid background; transparent produces an alpha cutout (GPT Image 2.5 tiers, png/webp only).
n 1 Number of alternatives.
outputFormat png png for graphics/text/UI/transparency; jpeg for photos or lower latency; webp for compact web assets.
outputCompression unset 0-100 for jpeg/webp.
saveToPath unset Explicit save path. When omitted and PersistOutputs is on, the image is saved to OutputDirectory and the path is returned.

Example:

{
  "prompt": "A cinematic macro photograph of a crystal fox in a snowy pine forest, volumetric dawn light",
  "tier": "premium",
  "size": "3840x2160",
  "quality": "xhigh",
  "outputFormat": "jpeg",
  "outputCompression": 90
}

edit_image

Use when a user has an image file, including one previously produced by this server, and wants it changed: localized edits, restyling, background replacement, object removal/insertion, text changes, clothing/color changes, combining reference images, sketch-to-photo, transparent cutouts, or iterative refinement.

Edit-specific parameters (shared parameters behave as in generate_image):

Parameter Default Notes
prompt required Phrase edits narrowly: exactly what should change, and an explicit list of what must stay identical (identity, pose, framing, lighting, background, text, layout). Repeat preservation requirements on every iterative edit.
imagePath required Absolute path to a local PNG, JPEG, or WebP image readable by the MCP server process. Pass a path returned by a previous call to refine that result. The MIME type is detected from file bytes, not trusted from the extension.
maskPath unset Absolute path to an optional PNG mask with an alpha channel and the same dimensions as the first input image. Transparent pixels mark the editable area. Masking is prompt-guided rather than pixel-exact.
additionalImagePaths unset Up to 15 absolute paths to extra PNG, JPEG, or WebP references (16 inputs total). Borrow style, identity, objects, or composition, or combine elements from several images.
tier configured edit default Precise, preservation-heavy edits benefit most from premium.
background unset transparent extracts a subject/product onto an alpha background (GPT Image 2.5 tiers, png/webp).

Example:

{
  "prompt": "Change only the mug color from red to cobalt blue. Keep the logo, shape, lighting, shadows, framing, and background exactly as they are.",
  "imagePath": "C:/art/source-mug.png",
  "additionalImagePaths": [
    "C:/art/cobalt-reference.jpg"
  ],
  "tier": "premium",
  "outputFormat": "webp",
  "outputCompression": 50
}

The paths are resolved on the machine running the MCP server, not on a remote model host. Relative paths, Windows network shares, and Windows device paths are rejected. Files are fully decoded before upload; changing an unsupported file's extension does not make it valid.

Iterative workflow: call generate_image, take the Saved to: path from the response, and pass it as imagePath to edit_image; repeat with each returned path. If a region must remain pixel-identical across many edits, composite the approved edited region back onto the original outside the model.

describe_image_capabilities

Read-only. Returns the configured tiers, which is the default for generation and edits, the quality/format/background options each supports, the output directory, and tier-selection and edit-prompting tips. Useful for clients that do not surface server instructions.

Response shape

Each result starts with a text block such as Generated image result: returned 1 image(s) using tier 'premium' (gpt-image-2.5-sunburst)., followed by an optional Note: (e.g. tier ignored in single-model mode), a Saved to: line with the persisted path(s), any revised prompts, and the image content block(s). Saving is best-effort: if the disk write fails, the image is still returned inline with a Warning: line instead of a tool error, so a billed result is never lost.

GPT Image 2.5 / GPT Image 2 coverage

Implemented as AI-facing first-class parameters: prompt, tier selection, custom size validation, quality (including xhigh/max), background (including transparent), n, PNG/JPEG/WebP output, JPEG/WebP compression, local edit image paths, masks, reference images, and up to 16 total edit inputs.

Deliberately not exposed as MCP tool parameters: raw model/deployment names (tiers abstract them), user, response_format, raw stream, partial_images, moderation, input_fidelity, and arbitrary JSON pass-through. Those are configuration, telemetry, transport, or API escape-hatch details rather than reliable MCP image-creation controls. partial_images is not exposed because MCP tool calls return a final tool result, not incremental image-generation events. input_fidelity is not sent because GPT Image 2 and 2.5 process edit inputs at high fidelity and reject attempts to change it.

API contract validation

  • The preferred request paths are /openai/v1/images/generations and /openai/v1/images/edits with ?api-version=preview. V1 requests identify the model with the model body/form field; the older deployment URL remains available as a compatibility mode.
  • Generation uses JSON; edits use multipart/form-data. A single edit input uses image; multiple inputs use repeated image[] parts, each with its own detected MIME type. background is only sent when non-auto and the tier's family supports it.
  • GPT Image responses contain base64 image data, which the server decodes and returns as MCP image content. URL-only results are rejected and never fetched.
  • A mask applies to the first input image. It must be PNG, include an alpha channel, and match the first image's dimensions. The server decodes and validates these properties before the Azure request.
  • GPT Image 2.5 (gpt-image-2.5-sunburst, gpt-image-2.5-flare) adds xhigh/max quality and background: transparent (png/webp). Both 2.5 models share GPT Image 2's token pricing but may consume different token counts per image; validate against your own deployments and check Azure model region availability before rollout.

References: Azure v1 preview image REST API, Azure v1 API lifecycle, GPT Image generation guide, GPT Image 2.5 Sunburst, GPT Image 2.5 Flare, and Azure model region availability.

Upgrading from 2.x

  • Default model changed. 2.x defaulted to gpt-image-2; 3.0 defaults to gpt-image-2.5-sunburst (tier premium). Keep AzureFoundry__Model=gpt-image-2 (+ ModelFamily) to stay on the old behavior, or configure tiers as shown above.
  • New parameters tier and background on both tools are optional; existing calls keep working.
  • New tool describe_image_capabilities.
  • Results are saved to disk by default (PersistOutputs=true, %TEMP%/image-gen-mcp) and the path is returned so edits can chain. Set AzureFoundry__PersistOutputs=false to restore 2.x behavior.
  • Result text now includes the tier and model used.

Development

Restore/build/test:

dotnet restore
dotnet build
dotnet test

Run locally as an MCP stdio server:

dotnet run --project src/ImageGenMcp.Server/ImageGenMcp.Server.csproj

The process waits for MCP JSON-RPC on stdin. Logs are written to stderr so stdout stays protocol-clean.

Package as a .NET tool / MCP server package:

dotnet pack src/ImageGenMcp.Server/ImageGenMcp.Server.csproj -c Release

The package is written to artifacts/packages/ and includes .mcp/server.json so NuGet.org and MCP clients recognize it as an MCP server. To test it locally with dnx, use that directory as an additional package source:

dnx ImageGenMcp.Server@3.0.0 --add-source ./artifacts/packages --yes

Security and operational notes

  • Do not commit real .env values. Use user-secrets, environment variables, managed identity, or a vault-backed deployment.
  • Prompt, aggregate input, response body, and decoded output image sizes are bounded to reduce accidental runaway cost and resource usage.
  • Local edit paths are required to be absolute and local to the machine. Files are size-checked before allocation, fully decoded as PNG/JPEG/WebP content, and uploaded with sanitized filenames.
  • The MCP server can read images using the operating-system permissions of its process, and result persistence writes to OutputDirectory (or a caller-supplied saveToPath). Only provide paths that the server is intended to access; set PersistOutputs=false to disable automatic saving.
  • The server logs the tier and model used per call but does not log prompts, image bytes, masks, or API keys.
  • GPT Image responses must contain b64_json; URL-only image results are rejected and are never fetched by the server.
  • NuGet audit is enabled in the server project for moderate-or-higher vulnerabilities across direct and transitive dependencies.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
3.0.0 206 9/12/2026
2.0.0 174 7/15/2026
1.0.0 164 6/23/2026

3.0.0: GPT Image 2.5 support (gpt-image-2.5-sunburst, gpt-image-2.5-flare) alongside gpt-image-2. Breaking: the default model is now gpt-image-2.5-sunburst; configure AzureFoundry__Model (legacy single-model mode) or AzureFoundry__Models__{tier}__Model to pin models. New: intent-based tier parameter (premium/fast/legacy), background=transparent, xhigh/max quality, describe_image_capabilities tool, MCP server instructions, automatic result persistence for chained edits.