APIKO

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.

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.

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-mcpcd apiko-mcpnpm installnpm run build        # writes dist/index.js

and 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-mcp

or 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

Tools

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 by resolution (or by an explicit WxH size for gpt-image-2), flat per-image prices, and per-second video prices by resolution × duration, including reference videos once you pass reference_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). An indicative_usd figure 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; use get_task.
• client_request_id stops 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_balance reads 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 at https://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 installnpm test            # builds, then runs the tests against a local mock API

src/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.