Skip to main content
Glama
runapi-ai

Topaz MCP Server

by runapi-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Why This Package?

@runapi.ai/topaz-mcp is a focused Model Context Protocol server for the Topaz model line on RunAPI. It gives MCP-compatible assistants direct access to 2 endpoints and 2 model variants without loading the full RunAPI catalog.

Use this per-model server when an agent should stay scoped to Topaz. 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 topaz -s user -- npx -y @runapi.ai/topaz-mcp

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

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

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

{
  "mcpServers": {
    "topaz": {
      "command": "npx",
      "args": ["-y", "@runapi.ai/topaz-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

upscale_image

Yes

Create a Topaz upscale image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

upscale_video

Yes

Create a Topaz upscale video 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 Topaz model and endpoint.

Models

Topaz covers 2 model variants across 2 endpoints. Each tool accepts the models listed for it:

Tool

Models

upscale_image

topaz-upscale-image

upscale_video

topaz-upscale-video

Model availability can change between releases. Use check_pricing or the Topaz 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 Topaz upscale image task with RunAPI.

The assistant can call check_pricing, then upscale_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 Topaz pricing, then create the task if it matches my request.

The assistant calls check_pricing and can link to the Topaz 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

Topaz model page

https://runapi.ai/models/topaz

npm package

@runapi.ai/topaz-mcp

GitHub repository

runapi-ai/topaz-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_pricingB

Look up RunAPI pricing for the topaz 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

B3.3/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. 'Look up' implies a read-only operation, but the description does not disclose authentication needs, rate limits, error behavior, or the format of the returned pricing data.

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, front-loaded sentence with no wasted words. It delivers the essential purpose efficiently.

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 simple lookup tool with full schema coverage, the description is minimally adequate. However, since there is no output schema, it should explain what pricing information is returned, and it also omits any usage context.

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 fully documents both parameters and their defaults. The description adds no parameter syntax or meaning beyond what the schema already provides, making the baseline score of 3 appropriate.

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 states a specific verb ('Look up') and resource ('RunAPI pricing') scoped to the 'topaz model line'. It is clearly distinct from siblings like upscale_image, get_task, and login, so an agent can identify it immediately.

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 explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. The description only states the purpose, leaving the agent to infer that it should be called whenever pricing is needed.

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

get_taskC

Fetch the current status and latest result payload for a topaz task.

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

TDQS

C2.9/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. 'Fetch' implies a safe read, and 'latest result payload' hints that results may not exist yet, but it says nothing about whether the call blocks, what status values exist, whether results expire, or any rate limits.

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?

A single efficient sentence with the resource front-loaded and no filler. It is appropriately sized, though it is so terse that it omits useful context rather than earning extra credit.

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 simple two-parameter read tool with full schema coverage this is nearly adequate, but with no output schema and no annotations the description should at least sketch the return shape (status values, presence/absence of payload), which it does not.

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%, with both task_id and the action enum fully documented in the schema, so the baseline is 3. The description adds no parameter detail beyond what the schema already provides.

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) scoped to 'a topaz task'. This clearly distinguishes it from the sibling creation tools upscale_image/upscale_video and from login/check_pricing, though it never names a sibling explicitly.

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 explicit when-to-use guidance, no mention that this is the follow-up to an asynchronous upscale task, and no statement about polling cadence or alternatives. The phrase 'current status' weakly implies a polling use case but leaves the agent to infer it.

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.

upscale_imageB

Create a Topaz task on RunAPI (upscale 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.
timeout_msNo
callback_urlNoWebhook URL for terminal Task delivery. Declared type: string.
upscale_factorYesImage upscale multiplier. Declared type: integer. Known values: 1, 2, 4.
poll_interval_msNo
source_image_urlYesPublic source image URL. Declared type: string.

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 behavioral burden. It usefully discloses that the operation is asynchronous and returns a task id, status and output URLs, but says nothing about cost, auth requirements, failure behavior, or the polling semantics implied by wait/timeout_ms/poll_interval_ms.

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 tight sentences with the action front-loaded and the return shape second. The parenthetical '(upscale image)' is mildly redundant with the tool name but costs almost nothing.

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 7-parameter, no-annotation, no-output-schema tool, the description does compensate by naming the return fields, but it omits how the async flow works (wait vs callback), cost implications, and any error behavior — all of which an agent needs to invoke this 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 description coverage is 71%, so the schema already documents most parameters (wait, model, callback_url, upscale_factor, source_image_url). The description adds no parameter-level meaning beyond that, so the 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 concrete action and resource: creating a Topaz task to upscale an image, with the async-task framing made explicit. It is distinguishable from upscale_video by resource, though it never names that sibling or contrasts itself with it.

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 guidance on when to use this versus upscale_video, or when to let the default wait=true poll versus supplying a callback_url. The description also does not mention check_pricing or get_task, which are the obvious companions for a paid async job.

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

upscale_videoB

Create a Topaz task on RunAPI (upscale video). 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.
timeout_msNo
callback_urlNoWebhook URL for terminal Task delivery. Declared type: string.
upscale_factorNoVideo upscale multiplier. Declared type: integer. Known values: 1, 2, 4.
poll_interval_msNo
source_video_urlYesPublic source video URL. Declared type: string.

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries the full burden. It notes the tool creates a task and returns id/status/output URLs (useful since there is no output schema), but omits key behavior: that creation is asynchronous, that 'wait' defaults to true and may block/poll, callback/webhook semantics, and any permission or rate-limit constraints.

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?

Two short sentences, fully front-loaded with the action and resource, then the return values. No filler or repetition.

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 7-parameter async task-creation tool with no annotations, the description covers the return shape (compensating for the absent output schema) but leaves behavioral context — async polling, wait default, callbacks, auth — and usage routing incomplete.

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 71% (missing docs for timeout_ms and poll_interval_ms), so baseline is 3. The description adds no parameter meaning beyond the schema — it never mentions upscale_factor, wait, callback_url, or model semantics.

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 ('Create') and resource ('Topaz task on RunAPI') with the operation 'upscale video' made explicit, so it is distinguishable from upscale_image. It does not explicitly name or contrast with siblings, 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?

No guidance on when to use this versus alternatives such as upscale_image (different media type) or get_task (polling an existing task). No prerequisites or conditions are stated; the agent must infer usage entirely.

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: -[
-  "topaz-upscale-image",
-  "topaz-upscale-video"
-]
    • Changedget_task1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changedupscale_image9 fields changed
      • changedInput schema / additionalProperties
        Previous value: -falseNew value: +{}
      • changedInput schema / properties / callback_url / description
        Previous value: -"Webhook URL for terminal Task delivery."New value: +"Webhook URL for terminal Task delivery. Declared type: string."
      • removedInput schema / properties / model / enum
        Removed value: -[
-  "topaz-upscale-image"
-]
      • addedInput schema / properties / poll_interval_ms / maximum
        Added value: +9007199254740991
      • changedInput schema / properties / source_image_url / description
        Previous value: -"Public source image URL."New value: +"Public source image URL. Declared type: string."
      • addedInput schema / properties / timeout_ms / maximum
        Added value: +9007199254740991
      • changedInput schema / properties / upscale_factor / description
        Previous value: -"Image upscale multiplier."New value: +"Image upscale multiplier. Declared type: integer. Known values: 1, 2, 4."
      • removedInput schema / properties / upscale_factor / enum
        Removed value: -[
-  1,
-  2,
-  4,
-  8
-]
      • changedInput schema / properties / upscale_factor / type
        Previous value: -"number"New value: +"integer"
    • Changedupscale_video9 fields changed
      • changedInput schema / additionalProperties
        Previous value: -falseNew value: +{}
      • changedInput schema / properties / callback_url / description
        Previous value: -"Webhook URL for terminal Task delivery."New value: +"Webhook URL for terminal Task delivery. Declared type: string."
      • removedInput schema / properties / model / enum
        Removed value: -[
-  "topaz-upscale-video"
-]
      • addedInput schema / properties / poll_interval_ms / maximum
        Added value: +9007199254740991
      • changedInput schema / properties / source_video_url / description
        Previous value: -"Public source video URL."New value: +"Public source video URL. Declared type: string."
      • addedInput schema / properties / timeout_ms / maximum
        Added value: +9007199254740991
      • changedInput schema / properties / upscale_factor / description
        Previous value: -"Video upscale multiplier."New value: +"Video upscale multiplier. Declared type: integer. Known values: 1, 2, 4."
      • removedInput schema / properties / upscale_factor / enum
        Removed value: -[
-  1,
-  2,
-  4
-]
      • changedInput schema / properties / upscale_factor / type
        Previous value: -"number"New value: +"integer"
  2. 3 tool updatesv0.1.7
    • 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."
    • Changedupscale_image5 fields changed
      • addedInput schema / properties / callback_url
        Added value: +{
+  "description": "Webhook URL for terminal Task delivery.",
+  "type": "string"
+}
      • addedInput schema / properties / source_image_url / description
        Added value: +"Public source image URL."
      • addedInput schema / properties / source_image_url / type
        Added value: +"string"
      • addedInput schema / properties / upscale_factor / description
        Added value: +"Image upscale multiplier."
      • changedInput schema / required
        Previous value: -[
-  "upscale_factor"
-]New value: +[
+  "source_image_url",
+  "upscale_factor"
+]
    • Changedupscale_video5 fields changed
      • addedInput schema / properties / callback_url
        Added value: +{
+  "description": "Webhook URL for terminal Task delivery.",
+  "type": "string"
+}
      • addedInput schema / properties / source_video_url / description
        Added value: +"Public source video URL."
      • addedInput schema / properties / source_video_url / type
        Added value: +"string"
      • addedInput schema / properties / upscale_factor / description
        Added value: +"Video upscale multiplier."
      • addedInput schema / required
        Added value: +[
+  "source_video_url"
+]
  3. 1 tool updatev0.1.6
    • Addedlogin
  4. 4 tool updatesv0.1.1
    • First observedcheck_pricing
    • First observedget_task
    • First observedupscale_image
    • First observedupscale_video
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 clearly distinct action: upscale_image and upscale_video split by media type, get_task polls status, check_pricing handles billing lookup, and login handles auth. No two tools could reasonably be confused for one another.

Naming Consistency4/5

Four of five tools follow a clean verb_noun pattern (upscale_image, upscale_video, get_task, check_pricing). Only 'login' deviates as a bare verb, which is a minor but forgivable inconsistency.

Tool Count5/5

Five tools is well-scoped for a focused image/video upscaling service: two task-creation tools, one status poller, one pricing lookup, and one auth tool. Nothing feels padded or missing at the count level.

Completeness4/5

The core lifecycle (auth, create upscale task, poll status, check pricing) is covered, and results come back as output URLs. However, there is no cancel/delete task, no list-tasks, and no explicit result-download tool, leaving minor gaps an agent must work around.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers