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}" } } } }
.vscode/mcp.json settings file.
dotnet tool install --global ImageGenMcp.Server --version 3.0.0
dotnet new tool-manifest
dotnet tool install --local ImageGenMcp.Server --version 3.0.0
#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_imageMCP tool for image creation.edit_imageMCP tool for image editing from local file paths, with an optional mask and up to 15 extra reference images.describe_image_capabilitiesMCP 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:
- 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. - Tool parameter guidance. The
tierparameter description on both tools explainspremium/fast/legacyin 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. - 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.
- Discovery.
describe_image_capabilitiesreturns 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/generationsand/openai/v1/images/editswith?api-version=preview. V1 requests identify the model with themodelbody/form field; the older deployment URL remains available as a compatibility mode. - Generation uses JSON; edits use
multipart/form-data. A single edit input usesimage; multiple inputs use repeatedimage[]parts, each with its own detected MIME type.backgroundis only sent when non-autoand 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) addsxhigh/maxquality andbackground: 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 togpt-image-2.5-sunburst(tierpremium). KeepAzureFoundry__Model=gpt-image-2(+ModelFamily) to stay on the old behavior, or configure tiers as shown above. - New parameters
tierandbackgroundon 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. SetAzureFoundry__PersistOutputs=falseto 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
.envvalues. 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-suppliedsaveToPath). Only provide paths that the server is intended to access; setPersistOutputs=falseto 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 | Versions 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. |
This package has no dependencies.
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.