Generate and edit images via an MCP server using Azure Foundry by default, with diagnostics and operation recovery.
Use get_capabilities for nonbillable configuration/capability checks; optional credential acquisition does not prove inference permission.
Use generate_image to create one new billable immutable PNG at 1536x864/high from a prompt and caller-supplied UUID; identical replay recovers the same artifact without resubmission.
Use edit_image to create one new billable image from exactly one source artifact UUID or approved absolute local PNG path, with a new UUID; the source stays unchanged; masks, URLs, and multiple references are unsupported.
Use get_operation to look up a retained UUID and recover a committed artifact after interruption without resubmitting.
Work through MCP clients such as Copilot CLI/VS Code; Azure remains default and uses local Azure CLI identity, while an experimental native Copilot backend exists only in source candidate/revisions, not the published 0.1.0 package.
Feed full-resolution artifacts into editable presentation workflows such as the PptxGenJS example; generation/editing is billable, diagnostics are not.
Provides image generation and editing tools that integrate with GitHub Copilot, enabling AI-assisted creation and modification of images through an Azure Foundry deployment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@image-gen-mcp Generate a 1536x864 hero image with negative space for a presentation slide."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local Model Context Protocol (MCP) server for generating and editing images through your own Azure Foundry deployment, with GitHub Copilot and editable presentation workflows.
Status: @juanmicrosoft/image-gen-mcp@0.1.0 is published. Anonymous archive
integrity, fresh registry installation and MCP discovery are
verified. The implemented
tools have real Azure evidence,
actual Copilot CLI evidence and a
rendered presentation example.
Verified paths include local macOS / Node 22.22.2 / Copilot CLI 1.0.79 and
the CLI-backed VS Code 1.139.0 session with CLI-token generation/editing from
an installed tarball. Native Local Copilot Chat has a demonstrated preview-off
recovery/edit workflow; inline previews encountered a host image-transport
failure. Do not equate the two session backends.
See the qualification matrix and boundaries.
A separate data-only Azure principal
also generated and edited while an authenticated management read was denied.
Live expired-session behavior remains unverified; ambiguous diagnostics do not
claim a unique cause. Publishing-token revocation remains an
open cleanup gate.
The configured model profile is gpt-image-2.5-sunburst. V1 deliberately enables
only the live-verified 1536x864, high-quality PNG combination: one image,
one concurrent submission, no automatic retries, prompt rewrites or model
fallback. No exact ChatGPT backend or output parity is claimed.
The current source candidate, not the published 0.1.0 package, also contains an optional experimental native GitHub Copilot backend. Four bounded local macOS cases now qualify generation and selected-reference editing through both a stock directly launched Copilot runtime and an isolated Agency-launched Copilot child; see the public proof, mixed source revisions and exact boundaries. Azure remains the default and retains the live evidence described above. Copilot mode requires an explicit expected OAuth login, executes the native image tool directly through pinned @github/copilot-sdk@1.0.20 / runtime 1.0.96 without a chat turn, and refuses account, endpoint or backend fallback. The live result does not publish this backend, replace final review or qualify other platforms, plans, authentication modes or persistent/global installation.
Tool | Purpose |
| Nonbillable diagnostics; keeps configured, observed and unverified facts separate |
| One new immutable image, identified by a caller-retained operation UUID |
| One explicit artifact or approved local PNG reference; immutable parent/child lineage |
| Recover a saved result after interruption without submitting again |
Let your coding agent do the setup. Use Copilot CLI, VS Code Copilot in a local agent session, or Claude Code on the machine where the MCP will run. Send the single prompt below as your message. No Azure portal configuration is needed: the agent uses Azure CLI and this repository's provisioning script. You still complete interactive sign-in and approve subscription, resource costs and permissions. A subscription with model access/quota is required; an agent cannot bypass an administrator or capacity restriction.
Here, Claude means Claude Code, not Claude web or Claude Desktop. The Copilot workflows have live qualification; Claude Code setup is based on its documented stdio interface, not a live-tested image workflow. These instructions are for local agents, not a hosted coding agent that cannot access your local Azure login or files.
Send this as your own message. Some hosts treat a bare paste as quoted content rather than your instruction and will ask you to confirm before acting. The detailed procedure lives in docs/agent-setup.md, so the prompt stays short and changes with the code.
Set up the image-gen MCP server from https://github.com/juanmicrosoft/image-gen-mcp
on this machine, end to end: provision (or reuse) an Azure image deployment with
Azure CLI, install the server, and register it globally (user scope) in this
coding agent.
Clone the repository to a private persistent directory and follow
docs/agent-setup.md, which links the other guides you need.
Ground rules:
- Read-only checks (tool versions, az account show, providers, quota, pricing,
RBAC) need no Azure write approval (host tool approval still applies).
Never ask me to paste credentials; let me run sign-in.
- Before creating any Azure resource, registering a provider or assigning a
role, show me one plan (tenant/subscription, region, model, resource names,
estimated cost, role and scope) and wait for my explicit approval of it.
- Use Azure CLI auth (no API keys) and, for a new deployment, the
repository's scripts/azure.mjs.
- Install one pinned version (no @latest in the launcher) and add the server
without overwriting other MCP servers; stop on a name conflict.
- If I need to sign in, choose, approve or restart, stop and tell me exactly
what to do.
- Do not generate images during setup. At the end, offer one test image and
wait for my yes.
- Finish with the installed version, configuration locations and anything
unverified.The agent will pause for your replies, not for another setup prompt. A short new/reuse choice confirms the displayed scope for read-only work; a separate precise approval authorizes the final write plan. If npm is unreachable, an approved compatible GitHub Releases bundle is the fallback. If neither route works, the default is to wait, but you may explicitly approve provisioning despite the blocked runtime installation and possible resource costs.
A private checkpoint carries progress across replies and client restarts.
Hosts may enforce forms or end each task automatically; a prompt cannot change
those runtime policies. The agent must label the workflow incomplete and provide
a supported continuation path, not treat a missing reply as approval.
The resume guide explains the checkpoint.
The agent can
use az login --use-device-code when normal interactive login is unavailable.
Sign-in may open a browser; that is authentication, not portal resource setup.
Provisioning uses the ownership-safe source script, not
the npm runtime package. The client guide provides commands.
The prompt selects the latest release once and installs that exact version;
starting the MCP does not trigger automatic upgrades. The manual example below
remains pinned to verified 0.1.0; its evidence does not certify future versions.
There is no MCP OAuth login: the local server uses your authorized Azure CLI
identity. Configuration and diagnostics do not prove inference permission.
Declining the optional paid test does not prevent completing client setup.
To remove a new, task-owned deployment later, ask the agent to read the saved state, show the exact resource group and deletion impact, obtain your explicit approval, then run the documented ownership-checked cleanup command. Do not apply that cleanup to a reused deployment.
For an existing compatible deployment:
Install the pinned release in a persistent directory:
npm install --prefix "$HOME/.local/share/image-gen-mcp" --registry=https://registry.npmjs.org/ --ignore-scripts --no-audit --no-fund @juanmicrosoft/image-gen-mcp@0.1.0Or build from source:
git clone https://github.com/juanmicrosoft/image-gen-mcp.git
cd image-gen-mcp
npm ci
npm run buildThen follow existing-deployment setup to select credentials, set the inference endpoint/deployment/output directory, and create a private client configuration. Pin the package version and never paste a key into shell history. The server is a stdio protocol process, not an interactive image-generation command.
To evaluate the source-candidate Copilot route instead of Azure, build the intended source revision and use the separate native Copilot configuration and example MCP entry. These files are not present in the already-published 0.1.0 package. The retained qualification intentionally spans revisions: stock generation used 1027224, while stock edit and both Agency cases used 49e36bf; the later change was scoped to selected-reference reads and did not alter generation. Do not combine Azure credentials with Copilot mode, assume the parent MCP host's identity is inherited, or treat nonbillable account diagnostics alone as inference proof.
Starting from scratch? Use the separate owner-tagged Bicep/Azure CLI setup. The normal MCP never creates resources or retrieves management keys. The authorization record explains the required resource-scoped grant and remaining limits; a token or management access alone is not inference permission.
Ask Copilot to generate a hero with negative space, inspect it, then explicitly edit that artifact using a new operation UUID. Results include the immutable full-resolution path, dimensions, hash, lineage, available usage and an optional bounded image preview. Image requests are billable; diagnostics are not.
Related MCP server: platform-eng-copilot
The PptxGenJS example consumes full-resolution artifacts into three editable slides. Its dependencies stay outside the runtime. Reference continuity is probabilistic; generated art does not replace editable text.
Read configuration, client setup/limits, generation, editing, privacy/cost/recovery and bounded live evaluation. Previews can be disabled. Cancellation does not prove that a request stopped or was free; retain the operation ID and inspect it before explicitly submitting again.
For contributors, npm test is offline and requires no Azure credentials.
See testing, CONTRIBUTING.md and
AGENTS.md for the individual-PR, independent-review and evidence rules.
The changelog and release evidence/gates
separate registry verification from bounded live-client evidence and remaining cleanup.
The software and documentation are MIT licensed. See SECURITY.md. This license does not replace Azure/OpenAI service terms or guarantee rights in generated images or third-party source assets.
Create one new billable image from exactly one explicit source_artifact_id or approved absolute PNG source_path. Provide a self-contained prompt and new operation UUID. The source remains unchanged; masks, URLs and multiple references are unsupported.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1536x864 | |
| prompt | Yes | ||
| quality | No | high | |
| source_path | No | Absolute .png path inside an explicitly configured input root. Choose exactly one source; omit source_artifact_id when using this path. | |
| operation_id | Yes | ||
| source_artifact_id | No | Choose exactly one source. Omit source_path when using this artifact ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=false, destructiveHint=false and idempotentHint=true, but the description adds genuinely non-structured context: the call is billable, the source image is left unchanged, and several input shapes (masks, URLs, multiple references) are rejected. It doesn't describe the async/polling behavior or what the call returns, which matters for a create-and-bill operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler; the core action and its source constraint are front-loaded, followed by required inputs, then limitations. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, it covers cost, source immutability, parameter conflicts and input limits well. The main gap is that it never says the operation is asynchronous or that get_operation should be used to retrieve the resulting image, which an agent would need to complete the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (source_path and source_artifact_id documented), but the description adds meaning the schema lacks: prompt must be 'self-contained' and operation_id must be 'new'. The size/quality parameters are single-value enums with defaults, so they need no prose; the mutual-exclusion rule for the two source params largely repeats the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create one new billable image') plus the required input ('from exactly one explicit source_artifact_id or approved absolute PNG source_path'). The source-based framing implicitly separates it from generate_image, but the sibling is never named, so the agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear operational constraints: exactly one source, a self-contained prompt, a new operation UUID, and an explicit when-not list ('masks, URLs and multiple references are unsupported'). It stops short of naming generate_image as the alternative when no source exists, so the routing decision is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate one billable Azure PNG at native 1536x864/high. Supply and retain a fresh UUID operation_id; replaying identical arguments recovers the same artifact without another submission. No retries, resizing or prompt rewrites.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1536x864 | |
| prompt | Yes | ||
| quality | No | high | |
| operation_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint=true, so replay behavior is partly structured, but the description adds valuable detail: the operation_id must be fresh and retained, replaying identical arguments returns the same artifact without another submission, and the tool performs no retries, resizing, or prompt rewrites. The billing note is also an important side effect that annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver a high density of useful information with no filler. The core outcome is front-loaded, and each clause adds a distinct constraint or behavioral detail. Nothing in the description is redundant with the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the essential operational facts: output type, dimensions, quality, billing, idempotency, and explicit non-behaviors. It does not describe the exact response envelope or authentication requirements, but it supplies enough for an agent to invoke the tool and understand the artifact contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the bare schema. It explicitly covers operation_id semantics (fresh UUID, replay behavior), names the exact accepted size and quality ('native 1536x864/high'), and implies the prompt is used verbatim via 'no prompt rewrites'. This meaningfully supplements the schema, even though prompt constraints like maxLength are not restated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Generate one billable Azure PNG'. It also fixes the native size and quality, making the tool's purpose unambiguous. The action clearly contrasts with sibling tools like edit_image and get_operation, so an agent can identify this as the creation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Generate' and the sizing/quality constraints imply the tool is for creating new images, but the description never explicitly says when to prefer it over siblings or what conditions would call for edit_image or get_operation. It provides clear operational context, such as the need for a UUID, but no direct when-to-use versus when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Nonbillable configuration and capability diagnostics. Optional credential acquisition does NOT verify inference permission or deployment identity.
| Name | Required | Description | Default |
|---|---|---|---|
| check_credentials | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which conveys safety. The description adds a critical behavioral caveat: optional credential acquisition does NOT verify inference permission or deployment identity, which is valuable for the agent to know. However, it does not elaborate on other behaviors such as what 'capability diagnostics' includes or any side effects beyond the annotation, so it earns a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and front-loaded with the core purpose. The caveat about credential acquisition is placed second, which is effective. It is concise without unnecessary fluff, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's relative simplicity (one optional parameter, no output schema), the description covers the essential purpose and a key behavioral caveat. However, it lacks specifics on what 'capability diagnostics' return or how to interpret results, and it does not clarify whether credentials are required for certain operations. This is a moderate gap, so a 3 is justified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameter 'check_credentials'. It mentions 'optional credential acquisition', which relates to the parameter, but it does not explicitly state that setting check_credentials to true will attempt credential acquisition or what the implications are. The parameter's meaning is partially implied but not fully specified, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the resource ('configuration and capability diagnostics') and a domain ('nonbillable'), but the verb 'get' is generic, and the purpose is somewhat vague. It does not clearly distinguish from siblings like get_operation, which also retrieves information. The mention of 'Nonbillable' hints at a billing context, but the overall purpose could be more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like get_operation. The description implies it is for diagnostics, but does not state when it should be preferred over other sibling tools, nor does it provide context for when credential checking is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a retained operation UUID and recover a committed artifact after interruption. Never submits or resubmits an image request. Unknown completion may still incur charges.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds two valuable behavioral details: it never submits or resubmits (consistent with readOnly) and warns that unknown completion may still incur charges. This charge caveat is beyond what annotations provide and is important for cost awareness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero filler. The purpose is front-loaded, the exclusion is stated immediately, and the cost warning is a final compact addition. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description covers what it does, when to use it, what it doesn't do, and a financial caveat. Annotations handle the safety profile. Nothing critical is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the parameter operation_id at all. However, the schema already provides format: uuid, making the parameter self-explanatory. With a single parameter and clear schema, the description adds no extra meaning but also doesn't need to. Baseline for low schema coverage is 3, and here it's adequate because the parameter is trivial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Look up' and the resource 'retained operation UUID' and 'committed artifact', and explicitly distinguishes it from submission tools by saying it never submits or resubmits an image request. This makes it easy for an agent to understand this is a retrieval/status tool, distinct from generate_image and edit_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after interruption for recovering artifacts, which provides clear context. It explicitly states it never submits or resubmits, ruling out using this tool for creation. However, it doesn't name the sibling tools directly or explicitly say 'use this instead of generate_image when you need the result of a prior call', so the guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
edit_image3 fields changedInput schema / oneOfRemoved value: -[
- {
- "required": [
- "source_artifact_id"
- ]
- },
- {
- "required": [
- "source_path"
- ]
- }
-]Input schema / properties / source_artifact_id / descriptionAdded value: +"Choose exactly one source. Omit source_path when using this artifact ID."Input schema / properties / source_path / descriptionPrevious value: -"Absolute .png path inside an explicitly configured input root."New value: +"Absolute .png path inside an explicitly configured input root. Choose exactly one source; omit source_artifact_id when using this path."v0.1.0edit_imagegenerate_imageget_capabilitiesget_operationScored across 4 tools
Each tool has a clearly distinct purpose: generate_image creates new images, edit_image transforms an existing artifact, get_capabilities reports config, and get_operation looks up prior operations. The descriptions explicitly delimit boundaries (e.g. get_operation never submits requests, edit_image requires a source artifact).
All four names follow a strict verb_noun snake_case pattern (edit_image, generate_image, get_capabilities, get_operation). The convention is predictable and consistent throughout.
Four tools is a small but coherent set for a focused image generation/editing server. It is slightly lean, but each tool earns its place without overlap.
Core lifecycle is covered: generate, edit, capability diagnostics, and operation retrieval for recovery after interruption. Minor gaps exist, such as no operation listing/enumeration or cleanup, but the essential workflows are present.
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
Generate AI images, video, speech, music and presentations from Claude, ChatGPT and Cursor.
Multi-model AI image and video generator. 14 models behind one OAuth-secured MCP endpoint.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
