popnow-api

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

Related MCP server: Popcraft MCP

At a glance

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.

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:

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

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.

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

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