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

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-..."

1. 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.

| `