Skip to main content
Glama
runapi-ai

GPT Image MCP Server

by runapi-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Why This Package?

@runapi.ai/gpt-image-mcp is a focused Model Context Protocol server for the GPT Image model line on RunAPI. It gives MCP-compatible assistants direct access to 2 endpoints and 1 model variant without loading the full RunAPI catalog.

Use this per-model server when an agent should stay scoped to GPT Image. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.

Related MCP server: grok-imagine-mcp

Install

Add it to Claude Code:

claude mcp add gpt-image -s user -- npx -y @runapi.ai/gpt-image-mcp

Use project scope when the server should be shared with a repository:

claude mcp add gpt-image -s project -- npx -y @runapi.ai/gpt-image-mcp

Codex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:

{
  "mcpServers": {
    "gpt-image": {
      "command": "npx",
      "args": ["-y", "@runapi.ai/gpt-image-mcp"]
    }
  }
}

check_pricing works before sign-in. For task creation and status polling, ask your assistant to call the login tool. It opens a browser login and saves credentials to ~/.config/runapi/config.json, the same file used by runapi login. Headless and CI hosts can still set RUNAPI_API_KEY before starting the MCP host.

Ready-made examples are in examples/ for Claude, Cursor, Windsurf, VS Code, and Roo Code.

Tools

Tool

Auth

Purpose

edit_image

Yes

Create a GPT Image edit image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

text_to_image

Yes

Create a GPT Image text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

get_task

Yes

Fetch the current status and latest payload for an existing task.

check_pricing

No

Look up current pricing for a GPT Image model and endpoint.

Models

GPT Image covers 1 model variant across 2 endpoints. Each tool accepts the models listed for it:

Tool

Models

edit_image

gpt-image-1.5

text_to_image

gpt-image-1.5

Model availability can change between releases. Use check_pricing or the GPT Image model page for the current catalog view.

Agent Prompts

Ask your assistant in natural language; it can inspect pricing, create the task, and return the task id plus output URLs.

Create a task

Run a GPT Image edit image task with RunAPI.

The assistant can call check_pricing, then edit_image, and return the task id, status, and output URLs.

Submit without waiting

Create the task but don't wait for it to finish.

The assistant calls the create tool with wait: false and returns the task id. Check on it later with get_task.

Check pricing before creating

Check current GPT Image pricing, then create the task if it matches my request.

The assistant calls check_pricing and can link to the GPT Image model page for the canonical catalog entry.

Configuration

The server resolves auth in this order:

  1. RUNAPI_API_KEY environment variable, useful for headless and CI hosts

  2. ~/.config/runapi/config.json, created by the MCP login tool or runapi login

  3. No key, which still allows check_pricing

The config file is normally managed by login. A pre-provisioned headless config can use:

{
  "apiKey": "your_runapi_key"
}

Do not commit real API keys.

Links

Resource

URL

GPT Image model page

https://runapi.ai/models/gpt-image

npm package

@runapi.ai/gpt-image-mcp

GitHub repository

runapi-ai/gpt-image-mcp

RunAPI MCP overview

runapi.ai/mcp

RunAPI docs

runapi.ai/docs

License

Licensed under the Apache License, Version 2.0.

Available Tools

5 tools
check_pricingC

Look up RunAPI pricing for the gpt-image model line.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoModel slug. Defaults to the line's primary model.
actionNoEndpoint name. Defaults to the endpoint that offers the model.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full behavioral burden. It implies a read-only lookup but does not state whether authentication is needed, whether the call is free or billable, or what the return format looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no wasted words. It states the operation and scope immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a lookup tool with no output schema and no annotations, the description is incomplete: it does not describe the returned pricing information (units, currency, format) or confirm that the operation is side-effect-free. The purpose is clear but callers lack enough context to interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both optional parameters and their defaults. The description adds no parameter-level detail beyond the schema, which is the baseline 3 when structured data does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('look up') and resource ('RunAPI pricing') scoped to the gpt-image model line. Clear enough to distinguish from sibling actions like edit_image or text_to_image, but it does not explicitly contrast itself with any alternative tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only implicit usage is that an agent should call it when pricing for this model line is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_imageB

Create a GPT Image task on RunAPI (edit image). Returns a task id, status, and output URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoPoll until the task reaches a terminal status.
modelNoRunAPI model slug for this model line.
promptYesDeclared type: string.
qualityYesDeclared type: string. Known values: "medium", "high".
timeout_msNo
aspect_ratioYesDeclared type: string. Known values: "1:1", "2:3", "3:2".
callback_urlNoDeclared type: string.
poll_interval_msNo
source_image_urlsYesDeclared type: array.

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden, and it does disclose that this is an asynchronous task-creation call returning a task id, status, and output URLs. However, it omits permissions/auth needs, rate limits, and the polling lifecycle (the schema's wait/poll_interval_ms hint at polling, and get_task exists as a sibling), which matters for a no-annotation mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and ends with the return contract; nothing is padded. The parenthetical "(edit image)" is mildly redundant with the tool name but does clarify the operation mode, so it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with no annotations and no output schema, the description is thin: it never explains the asynchronous polling model, how source_image_urls relates to prompt, or when to follow up with get_task. The one sentence on return values is helpful but does not cover enough for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 78%, so the schema documents most parameters (quality known values, aspect_ratio enums, wait semantics). The description adds no parameter-level meaning whatsoever, neither clarifying prompt, source_image_urls, nor the model slug. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Create a GPT Image task") and names the mode ("edit image"), which implicitly distinguishes it from the text_to_image sibling. It also names the return payload (task id, status, output URLs). It stops short of explicitly contrasting itself with text_to_image, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no routing to siblings like text_to_image or get_task. The only hint is the parenthetical "(edit image)", which implies an edit workflow but never says so explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_taskB

Fetch the current status and latest result payload for a gpt-image task.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAsynchronous endpoint the task was created on.
task_idYesTask id returned when the task was created.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about pending/in-progress tasks, whether the result payload is null until completion, rate limits, or error states. The read-only nature is only implied by 'Fetch'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler that names the action, the resource, and the payload returned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter polling tool with no annotations and no output schema, the description adequately identifies what is returned but omits the status semantics (possible values, pending behavior) an agent needs to interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are documented in the schema (task_id, action enum), so the description is not required to compensate. It adds no syntax, format, or pairing detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and resource ('current status and latest result payload for a gpt-image task'), which clearly separates polling from the sibling creation tools (edit_image, text_to_image). However, it never names those siblings or explicitly frames itself as the poll-for-results counterpart to them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to call this versus alternatives, and no mention that this is the polling tool for asynchronously created tasks. There is no advice on cadence, retry, or what to do if the task is not yet complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

loginA

Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNoRe-run browser login when the current credential comes from the local config file.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses the interactive browser flow and the file write side effect (config.json). However, it does not mention that it may overwrite existing credentials or that it could block waiting for user input, though these are implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action ('Authenticate RunAPI') and provides necessary details without extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple login tool with one optional parameter and no output schema, the description covers the core purpose and side effect. It lacks an explicit statement that this is a prerequisite for other tools, but that is implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the only parameter 'force' has a description). The tool description adds no additional meaning about parameters beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Authenticate'), target resource ('RunAPI'), method ('browser PKCE login flow'), and side effect (saving to config.json). It is distinct from sibling tools, none of which relate to authentication.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (to authenticate RunAPI) but does not explicitly say when to run it (e.g., before other RunAPI tools) or when to use the 'force' parameter. Since there are no alternative auth tools among siblings, 'vs alternatives' is not applicable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

text_to_imageB

Create a GPT Image task on RunAPI (text to image). Returns a task id, status, and output URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoPoll until the task reaches a terminal status.
modelNoRunAPI model slug for this model line.
promptYesDeclared type: string.
qualityYesDeclared type: string. Known values: "medium", "high".
timeout_msNo
aspect_ratioYesDeclared type: string. Known values: "1:1", "2:3", "3:2".
callback_urlNoDeclared type: string.
poll_interval_msNo

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose a meaningful behavioral trait: this is an async task-creation call that returns an id, status, and output URLs rather than the image itself. However it says nothing about authentication needs, cost implications, or how the 'wait' polling flag changes behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with the core action and the return shape front-loaded. There is no padding, though it is arguably too terse to cover the tool's async behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter async image-generation tool with no output schema, the description does state return values, which compensates somewhat. But it omits the polling/wait semantics, callback behavior, and routing guidance to sibling tools like get_task, leaving a partially complete picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, and the description adds no parameter-level detail at all. The schema already documents wait, model, quality values, and aspect_ratio values; the description does not compensate for the undocumented prompt, timeout_ms, poll_interval_ms, or callback_url. Baseline 3 given the reasonably high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a GPT Image task on RunAPI (text to image).' The parenthetical distinguishes it from the sibling edit_image, which is the nearest alternative. It stops short of naming siblings explicitly, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus edit_image or get_task, nor any prerequisites. The mention that it 'Returns a task id' only weakly implies that get_task is the follow-up call. An agent must infer the async workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.2.0
    • Changedcheck_pricing2 fields changed
      • removedInput schema / additionalProperties
        Removed value: -false
      • removedInput schema / properties / model / enum
        Removed value: -[
-  "gpt-image-1.5"
-]
    • Changededit_image11 fields changed
      • changedInput schema / additionalProperties
        Previous value: -falseNew value: +{}
      • addedInput schema / properties / aspect_ratio / description
        Added value: +"Declared type: string. Known values: \"1:1\", \"2:3\", \"3:2\"."
      • removedInput schema / properties / aspect_ratio / enum
        Removed value: -[
-  "1:1",
-  "2:3",
-  "3:2"
-]
      • addedInput schema / properties / callback_url / description
        Added value: +"Declared type: string."
      • removedInput schema / properties / model / enum
        Removed value: -[
-  "gpt-image-1.5"
-]
      • addedInput schema / properties / poll_interval_ms / maximum
        Added value: +9007199254740991
      • addedInput schema / properties / prompt / description
        Added value: +"Declared type: string."
      • addedInput schema / properties / quality / description
        Added value: +"Declared type: string. Known values: \"medium\", \"high\"."
      • removedInput schema / properties / quality / enum
        Removed value: -[
-  "medium",
-  "high"
-]
      • addedInput schema / properties / source_image_urls / description
        Added value: +"Declared type: array."
      • addedInput schema / properties / timeout_ms / maximum
        Added value: +9007199254740991
    • Changedget_task1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changedtext_to_image10 fields changed
      • changedInput schema / additionalProperties
        Previous value: -falseNew value: +{}
      • addedInput schema / properties / aspect_ratio / description
        Added value: +"Declared type: string. Known values: \"1:1\", \"2:3\", \"3:2\"."
      • removedInput schema / properties / aspect_ratio / enum
        Removed value: -[
-  "1:1",
-  "2:3",
-  "3:2"
-]
      • addedInput schema / properties / callback_url / description
        Added value: +"Declared type: string."
      • removedInput schema / properties / model / enum
        Removed value: -[
-  "gpt-image-1.5"
-]
      • addedInput schema / properties / poll_interval_ms / maximum
        Added value: +9007199254740991
      • addedInput schema / properties / prompt / description
        Added value: +"Declared type: string."
      • addedInput schema / properties / quality / description
        Added value: +"Declared type: string. Known values: \"medium\", \"high\"."
      • removedInput schema / properties / quality / enum
        Removed value: -[
-  "medium",
-  "high"
-]
      • addedInput schema / properties / timeout_ms / maximum
        Added value: +9007199254740991
  2. 3 tool updatesv0.1.8
    • Changededit_image5 fields changed
      • addedInput schema / properties / callback_url
        Added value: +{
+  "type": "string"
+}
      • addedInput schema / properties / prompt / type
        Added value: +"string"
      • addedInput schema / properties / source_image_urls / items
        Added value: +{}
      • addedInput schema / properties / source_image_urls / type
        Added value: +"array"
      • changedInput schema / required
        Previous value: -[
-  "quality",
-  "aspect_ratio"
-]New value: +[
+  "prompt",
+  "source_image_urls",
+  "aspect_ratio",
+  "quality"
+]
    • Changedget_task1 field changed
      • changedInput schema / properties / action / description
        Previous value: -"Endpoint the task was created on."New value: +"Asynchronous endpoint the task was created on."
    • Changedtext_to_image3 fields changed
      • addedInput schema / properties / callback_url
        Added value: +{
+  "type": "string"
+}
      • addedInput schema / properties / prompt / type
        Added value: +"string"
      • changedInput schema / required
        Previous value: -[
-  "quality",
-  "aspect_ratio"
-]New value: +[
+  "prompt",
+  "aspect_ratio",
+  "quality"
+]
  3. 1 tool updatev0.1.6
    • Addedlogin
  4. 4 tool updatesv0.1.0
    • First observedcheck_pricing
    • First observededit_image
    • First observedget_task
    • First observedtext_to_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct action: authentication, two clearly separated generation modes (edit vs text-to-image), task polling, and pricing lookup. There is no overlap between edit_image and text_to_image since their purposes are explicitly differentiated.

Naming Consistency4/5

Names are consistently snake_case verb_noun (edit_image, text_to_image, get_task, check_pricing), which is predictable. The lone deviation is 'login', a bare verb that breaks the otherwise uniform pattern.

Tool Count5/5

Five tools is well-scoped for a focused image-generation service. Each tool earns its place: auth, two task-creation paths, polling, and cost lookup.

Completeness4/5

The core lifecycle (login -> create task -> poll result) plus pricing is covered. Minor gaps exist: no task listing, cancellation, or deletion, but these are workarounds an agent can live without for the primary generation workflow.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers