APIKO MCP
APIKO MCP lets an MCP client use your APIKO API key to discover models, estimate prices, and run billable image/video generation tasks.
Search available image, video, and chat models by query/category.
Get a model's request schema, endpoints, modes, and price tiers.
Validate inputs and estimate list-price cost before submitting.
Generate or edit images, or submit video generation tasks, with paid calls.
Upload local or remote reference images and get public URLs.
Check task status, progress, results, and failure reasons.
Check what the API key has spent and any key-specific spending limit.
Hide paid generation/upload tools with read-only mode for free lookups, quotes, task checks, and usage checks.
APIKO MCP server
Use APIKO image and video models from Claude Code, Codex, Cursor, Claude Desktop and other MCP clients. The server runs locally over stdio with your own APIKO API key: the agent can look up models and request fields, quote a list price, generate images and videos, follow tasks, check what the key has spent, and upload reference images.
Generation is billed to your APIKO balance at API prices. The server tells the agent to quote first and wait for your approval before every paid call.
Overview, supported models and prices: APIKO MCP server.
Works with
Any client that can start a local stdio MCP server can run npx -y apiko-mcp.
Client | How to add it | Tested by us |
Claude Code (CLI and desktop app) |
| yes |
Codex (CLI, IDE extension, desktop app) |
| yes |
Cursor |
| config follows Cursor's docs |
Claude Desktop |
| config follows the MCP docs |
Other stdio clients (Windsurf, Cline, VS Code agent mode, ...) | command | no |
The rows marked "follows the docs" use each client's documented mcpServers
format with the same command that is tested in Claude Code and Codex. If one of
them does not work for you, please open an issue.
Related MCP server: Image MCP
Requirements
Node.js 18.17 or newer
An APIKO API key from https://apiko.app/dashboard/apikeys
Install
The server is published on npm as apiko-mcp
and runs with npx -y apiko-mcp. To run it from source instead:
git clone <this repo> apiko-mcp
cd apiko-mcp
npm install
npm run build # writes dist/index.jsand replace npx -y apiko-mcp below with
node /absolute/path/to/apiko-mcp/dist/index.js.
Claude Code (CLI and desktop app)
claude mcp add apiko --scope user -e APIKO_API_KEY=sk-... -- npx -y apiko-mcp--scope user stores the server in ~/.claude.json, which the Claude Code
desktop app (Code tab) also loads. Run /mcp in Claude Code to check that
apiko is connected.
Codex (CLI, IDE extension, desktop app)
codex mcp add apiko --env APIKO_API_KEY=sk-... -- npx -y apiko-mcpor add this to ~/.codex/config.toml, which the Codex CLI, the IDE extension
and the ChatGPT desktop app share:
[mcp_servers.apiko]
command = "npx"
args = ["-y", "apiko-mcp"]
env = { APIKO_API_KEY = "sk-..." }Cursor
Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a
project root:
{
"mcpServers": {
"apiko": {
"type": "stdio",
"command": "npx",
"args": ["-y", "apiko-mcp"],
"env": { "APIKO_API_KEY": "sk-..." }
}
}
}Claude Desktop
Settings → Developer → Edit Config opens claude_desktop_config.json
(~/Library/Application Support/Claude/ on macOS,
%APPDATA%\Claude\ on Windows). Add the server and restart the app:
{
"mcpServers": {
"apiko": {
"command": "npx",
"args": ["-y", "apiko-mcp"],
"env": { "APIKO_API_KEY": "sk-..." }
}
}
}If a desktop app reports that node or npx cannot be found, use the full
path from which node.
Try it without spending anything
Add APIKO_MCP_READ_ONLY=1 to the server's env (-e APIKO_MCP_READ_ONLY=1 or
--env APIKO_MCP_READ_ONLY=1). The generate and upload tools are then hidden;
model lookup, quotes, task checks and the key's usage still work.
Environment variables
Variable | Default | Meaning |
| required | Your APIKO key. Never paste it into a chat. |
| off |
|
|
| API base URL. |
|
| Where the public price catalog is read from. |
| unset | Used only when set. Node's built-in fetch ignores them, so the server switches to a proxy-aware client when they are present. |
Tools
Tool | Cost | What it does |
| free | Lists the models your key can use, with category, list price and modes. Filter by |
| free | One model's |
| free | Validates an input against the schema and quotes the list price without submitting. |
| paid | Generates, or edits when |
| paid | Submits a video task ( |
| free | Status, progress, result URLs and failure reason of a task; can wait up to 45 s. |
| free | What this key has spent and its own spending limit, if any. |
| free | Uploads a local JPEG/PNG/WebP (or copies a public image URL) and returns a public |
Typical flow: search_models → get_model → upload_image (if you have local
references) → estimate_cost → you approve → generate_image /
generate_video → get_task.
Cost estimates
estimate_cost (and the generate tools' cost field) returns one of:
estimated: a number, when the price follows directly from the input: per-image tiers chosen byresolution(or by an explicitWxHsize forgpt-image-2), flat per-image prices, and per-second video prices byresolution×duration, including reference videos once you passreference_video_seconds.needs_input: something the price depends on is missing, usually the total length of reference videos. You also get the range and the amount held from your balance at submission (hold_usd), which is refunded down to the real charge when the task settles.token_billed: billed by tokens (GPT Image 2.5 Flare / Sunburst, text models). Anindicative_usdfigure may be shown, but it is not a quote.unknown: no published price or no reliable rule; never treat it as free.
All figures are list prices in USD from the public catalog at apiko.app. The gateway's charge at settlement is final. Failed tasks are refunded automatically.
max_cost_usd on the generate tools refuses the call when the estimate, or its
guaranteed upper bound, is above the cap, or when no reliable figure exists.
Billing notes
Each
generate_*call creates a paid task. Calling it again to check progress would pay twice; useget_task.client_request_idstops a repeated call from being submitted twice while the same server process is running. If a submission times out, the server does not retry it: check https://apiko.app/dashboard/usage first.Result links are signed and kept for 24 hours. Uploaded references are public to anyone with the link and are deleted after 72 hours.
check_balancereads the key, not the account. Keys created on apiko.app have no limit of their own and draw on the account balance, which only the dashboard shows (https://apiko.app/dashboard/billing).Text models appear in
search_models, but you call them through the OpenAI-compatible API athttps://api.apiko.app/v1, not through this server.
Timeouts
Codex gives each MCP tool call 60 seconds by default, so no tool here waits
longer than 45 seconds; long tasks are followed with get_task. The rare
sync-only image model can take longer: raise tool_timeout_sec under
[mcp_servers.apiko] if you use one.
Development
npm install
npm test # builds, then runs the tests against a local mock APIsrc/tools.ts holds the tool logic and src/server.ts builds an McpServer
from it, independent of the transport; src/index.ts is the stdio entry point.
The tests never call the production API.
Available Tools
8 toolscheck_balanceCheck key limit and usageARead-onlyIdempotent
Show what this API key has spent and its own spending limit, if it has one. Free. Keys without a limit draw on the account balance, which API keys cannot read; the user sees it at https://apiko.app/dashboard/billing.
Inputs: no named parameters.
estimate_costEstimate generation costARead-onlyIdempotent
Validate a planned input against the model schema and quote its list price without submitting anything. Free. status "estimated" gives a number; "needs_input" names what is missing (e.g. reference_video_seconds); "token_billed" and "unknown" mean no reliable number exists, so never present them as a price. Show the user the model, input and estimate and wait for explicit approval before calling generate_image or generate_video.
Inputs: model (required), input, reference_video_seconds.
generate_imageGenerate or edit an image (billable)A
BILLABLE: creates a paid image task charged to the user's APIKO balance. Only call after estimate_cost on the same input and the user's explicit approval of the model and cost. With reference images in input.images it edits (POST /v1/images/edits), otherwise it generates. The input is validated against the model schema first. Runs async when the model supports it and waits up to wait_seconds; if not done, poll with get_task. Never call again to check progress.
Inputs: model (required), input, prompt, max_cost_usd, +2 more.
generate_videoGenerate a video (billable)A
BILLABLE: creates a paid video task (POST /v1/videos) charged per second to the user's APIKO balance. Only call after estimate_cost on the same input and the user's explicit approval of the model, duration, resolution and cost. Reference videos add billed seconds. Returns a task_id at once; poll with get_task (videos take minutes). Never call again to check progress.
Inputs: model (required), input, prompt, max_cost_usd, +3 more.
get_modelGet APIKO model detailsARead-onlyIdempotent
Read one model's request fields (input_schema: types, enums, defaults, required fields), endpoints, async/sync modes and price tiers. Free. Send only fields from input_schema to estimate_cost and the generate tools.
Inputs: model (required).
get_taskGet task status and resultsARead-onlyIdempotent
Read an image or video task: status (queued, in_progress, completed, failed), progress, result_urls and fail_reason. Free. wait_seconds (0-45, default 30) keeps polling until the task finishes or the time runs out. Failed tasks are refunded automatically. Result links last 24 hours.
Inputs: task_id (required), wait_seconds.
search_modelsSearch APIKO modelsARead-onlyIdempotent
List the APIKO models this API key can use, with category (image / video / chat), list prices and generation modes. Free. Use it before get_model; never guess model ids. Text models are listed for reference: call them with the OpenAI-compatible API, not through this server.
Inputs: limit, query, category.
upload_imageUpload a reference imageA
Upload a JPEG, PNG or WebP (up to 10 MB) and get a public https://img.apiko.app URL for reference fields such as images, first_image_url or reference_image_urls. Free (per key: 60 per minute, 1,000 per day). Give exactly one of path (a local file the user named) or url. The uploaded copy is public to anyone with the link and deleted after 72 hours, so only upload files the user asked to use.
Inputs: url, path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct step in the workflow: discovery (search_models vs get_model), quoting (estimate_cost), billable creation (generate_image vs generate_video), polling (get_task), asset upload, and balance. Descriptions explicitly fence off overlap, e.g. 'never call generate again to check progress' and 'use search_models before get_model'.
Uniform snake_case verb_noun pattern across all eight tools (check_balance, search_models, get_model, estimate_cost, generate_image, generate_video, get_task, upload_image). Verbs are used consistently with their intent (get for single reads, search for listing).
Eight tools is well-scoped for a media generation API: each maps to a necessary stage (discover, inspect, quote, generate, poll, upload, balance) with no redundant entries. Nothing feels padded or missing at the count level.
The surface covers the full paid-generation lifecycle including cost safety, asset upload, and async polling, and result links are returned. Minor gaps: no task listing or cancellation tool, and text/chat is deliberately out of scope (deferred to the OpenAI-compatible API), which agents can work around but leaves a small hole.
Maintenance
Related MCP Connectors
Make images and videos, price requests, list AI models and read your balance, from one API key.
Generate images and video from Claude with one API key.
Generate images, videos and audio across many AI models via one API, with quotes before you pay.
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.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegrates MuAPI with Claude Code to enable image and video generation, editing, model discovery, and prediction tracking through natural language commands.964 npm4MIT
- AlicenseAqualityBmaintenanceConnects Claude Code to image generation models (OpenAI GPT Image 2, Google Nano Banana) for generating, editing, and converting images via natural language.638 npmMIT
- AlicenseNot gradedqualityCmaintenanceGenerate AI images and videos from Claude, Cursor or any MCP client: 48+ models on one account (Flux 2, Nano Banana 2, Seedream 5, Kling V3, Seedance 2.5, Veo 3.1), with the exact cost in credits returned on every call.1MIT
- FlicenseNot gradedqualityCmaintenanceEnables Claude to generate images and video clips through kie.ai models, create videos from frames or reference images, check rendering job status, and manage credits.-