PopNow API

PopNow Developer MCP Server: call any AI image, video and audio model from Claude Code, Cursor, Codex and your own code

The PopNow Developer MCP Server is a hosted Model Context Protocol server at https://api.popnow.ai/api/v1/mcp for developers. Add it to Claude Code, Cursor, Codex, VS Code or your own MCP client with a PopNow API key, and your agent can create images, videos, music and voiceovers, run any model by its API ID, follow tasks and install agent skills over one connection.

There is nothing to host. Every paid call is quoted in USD first and charged to your API balance only after you approve it. The key's model allow-list, IP allow-list and spend caps apply exactly as on the PopNow REST API.

This repository contains the setup guide, copy-paste client configs in examples/, an MCP registry manifest, and @popnow/mcp, a small stdio bridge for clients that only start local servers.

Want PopNow inside the ChatGPT or Claude apps with your PopNow account and website credits? Use popnow-mcp and popnow.ai/mcp instead.

Contents

• At a glance
• Quickstart
• Connect your client: Claude Code · Cursor · VS Code · Windsurf · Codex · Cline · Claude Desktop and stdio-only clients · Other clients · From your own code
• Tools
• Quotes and approval in USD
• Results and long jobs
• Limits
• Moving from the old address
• The stdio bridge (@popnow/mcp)
• Troubleshooting
• FAQ

At a glance

Endpoint	https://api.popnow.ai/api/v1/mcp
Transport	Streamable HTTP, stateless (POST; GET and DELETE return 405)
Authentication	Authorization: Bearer sk-popnow-... with a key from the API console. There is no OAuth sign-in on this endpoint
Billing	USD from your API balance. Every paid call returns a quote first and runs only with max_usd
Key rules	The key's model allow-list, IP allow-list and daily, monthly and lifetime spend caps
Tools	Media tools, create_task for any model ID, tasks, balance, saved recipes and agent skills (full list)
Server name	popnow-api

Quickstart

1. Create an API key in the API console. Giving your agent a key of its own with a low daily cap is a good habit: you can revoke it without touching your other integrations. If your API balance is $0, add funds in API billing.
2. Put the key in your environment. The configs below read it from POPNOW_API_KEY, so it stays out of files you commit:

   export POPNOW_API_KEY="sk-popnow-..."
   

3. Add the server. In Claude Code it is one command:

   claude mcp add --transport http popnow-api https://api.popnow.ai/api/v1/mcp \
     --header "Authorization: Bearer $POPNOW_API_KEY"
   

4. Ask for something. Ask your agent for an image, a clip or a soundtrack. It picks a PopNow tool, shows you the USD price and runs it once you approve.

Connect your client

Every client below talks to the same remote server with an API key. Ready-made files are in examples/.

Claude Code

claude mcp add --transport http popnow-api https://api.popnow.ai/api/v1/mcp \
  --header "Authorization: Bearer $POPNOW_API_KEY"

Your shell fills in $POPNOW_API_KEY when you run the command, and Claude Code stores the header in your local MCP settings. To share the server with a team through a project's .mcp.json, use the generic config instead: Claude Code expands ${POPNOW_API_KEY} from each person's environment.

Cursor

Add PopNow to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project (examples/cursor.mcp.json):

{
  "mcpServers": {
    "popnow-api": {
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:POPNOW_API_KEY}" }
    }
  }
}

VS Code

VS Code names the top-level key servers. This config asks for the key once and stores it securely (examples/vscode.mcp.json):

{
  "inputs": [
    { "type": "promptString", "id": "popnow-api-key", "description": "PopNow API key (sk-popnow-...)", "password": true }
  ],
  "servers": {
    "popnow-api": {
      "type": "http",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:popnow-api-key}" }
    }
  }
}

Windsurf

Remote servers use serverUrl in ~/.codeium/windsurf/mcp_config.json (examples/windsurf.mcp_config.json). Press Refresh in the MCP panel after saving.

{
  "mcpServers": {
    "popnow-api": {
      "serverUrl": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:POPNOW_API_KEY}" }
    }
  }
}

Codex

Edit ~/.codex/config.toml (examples/codex.config.toml); bearer_token_env_var reads the key from your environment:

[mcp_servers.popnow-api]
url = "https://api.popnow.ai/api/v1/mcp"
bearer_token_env_var = "POPNOW_API_KEY"

Cline

Open MCP Servers → Configure and add PopNow to cline_mcp_settings.json. Set type to streamableHttp explicitly; without it Cline falls back to the legacy SSE transport (examples/cline_mcp_settings.json):

{
  "mcpServers": {
    "popnow-api": {
      "type": "streamableHttp",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk-popnow-..." },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop and stdio-only clients

Clients that can only start local stdio servers can run the @popnow/mcp bridge with npx. From version 0.2.0 it connects to the developer endpoint by default. In Claude Desktop, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and restart the app (examples/claude-desktop.json):

{
  "mcpServers": {
    "popnow-api": {
      "command": "npx",
      "args": ["-y", "@popnow/mcp"],
      "env": { "POPNOW_API_KEY": "sk-popnow-..." }
    }
  }
}

The bridge needs Node.js 18 or newer.

Other clients

Most clients that support remote MCP servers accept this shape. It is also the format of a Claude Code project .mcp.json (examples/generic.json). Check how your client reads environment variables before you paste a key into a file that is committed anywhere.

{
  "mcpServers": {
    "popnow-api": {
      "type": "http",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${POPNOW_API_KEY}" }
    }
  }
}

From your own code

With the official Python SDK (pip install mcp):

import asyncio, os

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['POPNOW_API_KEY']}"}
    async with streamablehttp_client("https://api.popnow.ai/api/v1/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("check_balance", {})
            for part in result.content:
                print(part.type, getattr(part, "text", ""))

asyncio.run(main())

With the official TypeScript SDK (npm install @modelcontextprotocol/sdk):

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.popnow.ai/api/v1/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.POPNOW_API_KEY}` } },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({ name: 'check_balance', arguments: {} });
console.log(result.content[0].text);
await client.close();

Or with nothing but curl. The server is stateless, so every request stands alone; send both media types in Accept. This call asks for a quote and charges nothing:

curl -X POST "https://api.popnow.ai/api/v1/mcp" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_task", "arguments": {"model": "google/nano-banana-2.1/text-to-image", "input": {"prompt": "A paper boat on a rainy window sill, soft morning light", "aspect_ratio": "4:5"}}}}'

For production code that calls models directly, the REST API gives you more control: webhooks, idempotency keys and per-task retention. SDKs: Python · JavaScript / TypeScript · Go · Java · PHP.

Tools

Typical prices are for the default model and settings, in USD. Every paid tool quotes the exact amount before it runs. The full parameter reference is in the developer MCP docs.

Tool	What it does	Default	Typical price
create_image	A new picture from a description	Nano Banana 2.1, 1K, square	about $0.048
edit_image	Change a photo with words: style, outfit, background, add or remove things	Nano Banana 2.1	about $0.048
create_video	A short video from a description, or a photo brought to life	MiniMax H3, 768p, 5 seconds	about $0.185
create_music	An original song or instrumental	Suno v6	about $0.072
create_speech	Text read aloud in many voices and languages	Gemini 3.8 Flash TTS, voice Kore	a fraction of a cent, by length
apply_effect	Turn a photo into an effect video or a photo makeover	The effect's own model	$0.125 to $0.34 for video, $0.03 to $0.05 for photos
remove_background	Cut out the subject as a transparent PNG	Background Remover	$0.0048
upscale	Make a photo or a video sharper and bigger	Photo 4K, video 1080p	about $0.012 for a photo; video by length
add_sound	Sound effects and ambience that match a silent video	The tool's own model	quoted first
extend_video	Continue a video beyond its last frame	minimax-h3	quoted first
edit_video	Edit a video with words while keeping its motion	kling-o3	quoted first
copy_motion	Animate a character picture with motion from a video	kling-3-0	quoted first
create_video_from_references	A video that keeps subjects from reference pictures	minimax-h3	quoted first
transcribe_audio	Turn recorded speech into text	grok-stt	quoted first
create_sound_effects	Sound effects, ambience and spoken lines from a description	seed-audio-1-0	quoted first
split_layers	Separate a picture into editable transparent PNG layers	seedream-5-0-pro	quoted first
erase_object	Remove an object or person and fill the gap	object-eraser-v1	quoted first
expand_image	Extend a photo beyond its edges	image-expander-v1	quoted first
change_camera_angle	Show the scene from a different viewpoint	camera-angle-changer-v1	quoted first
change_pose	Match a person's pose to a reference picture	pose-changer-v1	quoted first
relight_photo	Change the lighting in a photo	relight-v1	quoted first
remove_shadow	Remove harsh shadows from a photo	shadow-remover-v1	quoted first
anime_to_real	Turn an anime or cartoon picture into a photorealistic image	anime-to-real-v1	quoted first
compose_video	Cut earlier results into one finished MP4 with optional music, narration, captions and a title		free
get_job	Check a task that is still running and return it when ready	Waits up to 30 s	free
list_my_creations	Recent tasks made with this key, with links	Last 10	free
check_balance	Available API balance and funds held for running tasks, in USD		free
list_models	Image, video and audio models with their exact API IDs, or every effect; with model, that model's inputs	image	free

Only tools that expose model accept a model from list_models; omit it to use the default. All tools carry the standard MCP hints (readOnlyHint, destructiveHint, openWorldHint), and no tool deletes anything.

Developer tools. Four tools exist only on this endpoint:

Tool	What it does	Parameters
create_task	Run any model by its exact API model ID with the model's own input, like createTask on the REST API	model (required, for example google/nano-banana-2.1/text-to-image), input, max_usd, currency
get_task	Same as get_job: check a task and collect its result	job_id (required), wait_seconds (0 to 50, default 30)
list_tasks	Same as list_my_creations: recent tasks made with this key	kind (image, video, audio), limit (1 to 20, default 10)
install_skill	The agent skill you picked: playbook, short-lived download link and install commands for your agent	slug (required), agent

Call list_models with a category to see every model's exact IDs, then with model for that model's inputs. create_task validates input against the model's schema before it quotes, so a missing or unknown field comes back as a message, not a charge.

Saved recipes and skills. list_my_recipes, run_my_recipe, get_recipe_run, resume_recipe_run, list_my_skills and use_my_skill reach the recipes, canvas workflows and skills you saved on popnow.ai, with the same USD quote and approval. See Your recipes, workflows and skills.

Agent skills. find_skills returns a few agent skills that match a request (preview video, cover image and what each needs); install_skill returns the chosen skill's SKILL.md, a package link that works for a few minutes, the install commands for your agent and which PopNow tools make its media. Both are free and read-only. More skills: popnow-skills.

Quotes and approval in USD

1. Quote. Call a paid tool without max_usd. Nothing starts and nothing is held. The result has needs_confirmation: true, currency: "USD", cost_usd and available_usd.
2. Approve. Show the price to the user. After they approve, call the tool again with the same arguments plus max_usd set to the quoted cost_usd.
3. Run. If the current price is within max_usd, the task starts. If it went up, you get a new quote to approve instead; nothing is charged.

max_usd is a nonnegative decimal string with up to nine decimal places, such as "0.012345678". JSON numbers, exponent notation and negative values are rejected. currency is optional and can only be USD. Every paid call needs this approval, including a zero-price quote; there is no automatic approval threshold.

When the balance cannot cover a quote, the tool says "Not enough API balance" with the cost and what is available, and charges nothing. Tasks follow the same rules as REST tasks: the highest possible price is held when a task starts, you pay what it actually used (never more than the hold), and a failed or expired task releases its hold. Identical calls with the same key within ten seconds create one task, so an agent that retries does not pay twice.

You:    Make a 9:16 clip of a vintage car cruising along the coast at golden hour, 10 seconds.
Agent:  (calls create_video → "Needs confirmation, nothing started yet. This costs $0.37 USD; API balance available: $12.40 USD.")
        That's $0.37 from your PopNow API balance. Go ahead?
You:    Yes.
Agent:  (calls create_video again with max_usd: "0.37" → job_id, then get_task)
        Done: coast.mp4. It's in your API logs too.

Results and long jobs

• Images come back as a preview plus a download link. Videos and audio come back as links.
• Download links are signed and expire after a while. Each result also has a popnow://g/<job>/<n> link that never expires and can be passed to another tool, so "now animate that picture" just works.
• A tool waits up to about 40 seconds for the result. Video usually takes longer, so the reply carries a job_id and the agent calls get_task to collect it.
• Every task is listed in the API console's logs with its key, model and USD amount.

Limits

What	Limit
Tool calls per account (including get_task polling)	240 per minute
New tasks per account	20 per minute
find_skills / install_skill per account	240 / 120 per hour

A task over the limit is not charged; the tool says how many seconds to wait. The key's spend caps apply to every call. REST API limits are separate and described in Rate limits.

Moving from the old address

Until 1 November 2026, API keys connected to https://api.popnow.ai/mcp. That address keeps accepting API keys until 31 January 2027 (00:00 UTC) and serves the same developer tools, with Deprecation, Sunset and Link headers on every response. After that it answers API keys with 401.

To move, change the URL in your MCP config to https://api.popnow.ai/api/v1/mcp. The key, the tools and USD billing stay the same. If you run the stdio bridge, upgrade to @popnow/mcp 0.2.0 or newer (npx -y @popnow/mcp picks it up), or set POPNOW_MCP_URL to the new address.

The stdio bridge (@popnow/mcp)

packages/popnow-mcp is a minimal TypeScript package (bin popnow-mcp) for MCP clients that can only launch local stdio servers. It connects a StdioServerTransport to a StreamableHTTPClientTransport from the official MCP SDK and forwards every message unchanged, so tools and prices always match the live server. It is published on npm as @popnow/mcp; see Claude Desktop and stdio-only clients for the config.

Environment variable	Required	Description
POPNOW_API_KEY	yes	PopNow API key (sk-popnow-...), sent as a Bearer token
POPNOW_MCP_URL	no	Remote endpoint, default https://api.popnow.ai/api/v1/mcp

To build and run it from source instead (Node.js 18 or newer):

git clone https://github.com/popnow-ai/popnow-api-mcp.git
cd popnow-api-mcp
npm --prefix packages/popnow-mcp install
npm --prefix packages/popnow-mcp test    # builds with tsc, then runs an end-to-end test against a local fake server
node packages/popnow-mcp/dist/cli.js --help

MCP registry manifest

server.json describes the server in the MCP registry format (schema 2025-12-11) as io.github.popnow-ai/popnow-api-mcp: the remote Streamable HTTP endpoint with a required Authorization header, and the @popnow/mcp npm package.

Troubleshooting

You see	Why	Fix
401 "This endpoint takes PopNow API keys"	No Authorization header, or a sign-in token instead of an API key	Send Authorization: Bearer with an active sk-popnow- key
401 "This API key isn't valid"	The key is wrong, revoked or expired	Create a key in the API console
403 or a tool error about the key	The key's model or IP allow-list blocks the call	Adjust the key's restrictions in the API console
Needs confirmation, nothing started yet	The tool is quoting first	Approve, then repeat the call with max_usd
"Not enough API balance"	The API balance cannot cover the quote	Add funds in API billing, or choose a cheaper model or a shorter video
A spend-cap message	The call would go over one of the key's caps	Raise the cap or wait for it to reset
"Too many creations at once. Nothing was charged."	More than 20 new tasks in a minute	Wait the number of seconds in the message
405 Method Not Allowed	GET or DELETE to the endpoint; the server is stateless	Use POST
Cline connects but nothing works	type missing, so Cline used legacy SSE	Set "type": "streamableHttp"

FAQ

Does the MCP server cost extra?

No. Connecting is free, and so are reading tools such as list_models, get_task and find_skills. Media tasks spend your API balance at the same model prices as the REST API, and every one is quoted first.

Can I connect with OAuth instead of an API key?

No. This endpoint only takes API keys, so every call is billed to the API balance and governed by the key's restrictions and caps. To use PopNow in the ChatGPT or Claude apps with your PopNow account, see popnow-mcp.

Which models can I call?

Every image, video and audio model in list_models, including Kling, Seedance, Wan, Vidu, MiniMax, Nano Banana, GPT Image, Flux and Suno. create_task takes any of their exact API IDs with the model's own inputs; the named tools cover the common jobs with sensible defaults.

Is there anything to install?

No. The server is remote; you only add its address. Clients that can only start local stdio servers can run the bridge with npx -y @popnow/mcp.

Where do my results go?

Results come back as links in the tool response. Every task also appears in the API console's logs, and list_tasks lists the recent ones for the key.

Links

• Developer MCP: popnow.ai/api/mcp · Docs · API console · API billing
• REST API: Quickstart · API reference · Models
• Other PopNow developer repos: popnow-skills · popnow-cli · popnow-python · popnow-js · popnow-api

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. For security issues, see SECURITY.md.

License

MIT © PopNow