GPT Image 2.5 API is live. Create and edit images →
PoYoPoYo

PoYo MCP Server

Every PoYo model, inside your AI agent.

Connect once so Codex, Claude Code, Cursor, and VS Code can search image, video, audio, chat, and 3D models, inspect current schemas and public pricing, and run tasks through PoYo.

MCP is a secure connection that lets your AI assistant use PoYo models without requiring you to write API requests.

npx -y @poyoapi/mcp

Local stdio bridge for VS Code or stdio-only clients. Requires Node.js 20+; use the setup below for guided connection.

Create API KeyView setupRead MCP docs

Configuration

Connect in three steps. Open advanced configuration only when you need to limit tool categories or models.

1

Prepare your API Key

Create a PoYo API Key first. You will use it when the client connects.

Do not paste a real API Key into a shared configuration file or URL.

Create API Key
2

Choose a client and find its configuration

Select the app you are using to see one relevant configuration location.

Recommended entry point

Open Codex Settings, choose MCP servers, then Add server and select Streamable HTTP.

View official client instructions

Manual configuration file

~/.codex/config.toml

Applies to

All projects for the current user

Open MCP configuration in the client. If there is no visual entry point, open or create the file above.

Paths beginning with ./ are inside the currently open project folder. Create the folder or file if needed.

3

Add the configuration and verify

Copy the configuration for the selected client, reload MCP, and complete a free verification.

Merge existing configuration; do not overwrite it

If the file already contains other MCP servers, merge only the poyo server entry and preserve all existing content. Overwriting can disable other connections.

Add the configuration below to ~/.codex/config.toml

[mcp_servers.poyo]
url = "https://api.poyo.ai/mcp"
bearer_token_env_var = "POYO_API_KEY"
tool_timeout_sec = 45

Save your API Key as the POYO_API_KEY environment variable before starting the client. After saving, start a new Codex session so it reloads MCP configuration.

How do I set POYO_API_KEY?

Copy the command for your system, replace your_api_key with the real Key, and start the client from the same terminal session.

macOS / Linux

export POYO_API_KEY="your_api_key"

Windows PowerShell

$env:POYO_API_KEY="your_api_key"

These commands affect only the current terminal session. Do not put a real Key in project files, screenshots, or public command logs.

Read MCP docs
Let your Agent help with configuration

Copy a safety-scoped prompt that asks the Agent to preserve existing settings, keep the real Key out of files, and show the diff before writing.

Verify the connection

Check these states in order. None of them starts a paid model task.

  1. 1PoYo tools appear in the client, confirming that the configuration loaded.
  2. 2poyo_account returns account information, confirming that the API Key works.
  3. 3poyo_search_models returns models, confirming access to the catalog.
Connection not working?
  • No tools: confirm the configuration location, then reload the MCP server.
  • Account check failed: confirm POYO_API_KEY is set, then restart the client from the same environment.
  • Connection failed: confirm the endpoint is https://api.poyo.ai/mcp and that your network or proxy permits HTTPS access.

When tools, account, and catalog checks all pass, PoYo MCP is connected.

What can an agent do with PoYo MCP?

Describe a task in natural language. The agent searches for a matching model, reads its inputs and price, runs it, and returns the result when a long job finishes.

Discover models

Search current image, video, audio, chat, or 3D models from a natural-language task

poyo_search_models
Candidate models

Read inputs

Read the current input schema, examples, protocols, and capabilities

poyo_get_model_schema
Valid inputs

Check pricing

Read the current public price before running a paid request

poyo_get_pricing
Price confirmation

Run short tasks

Complete chat or generation tasks that can return after a short wait

poyo_chatpoyo_run_model
Complete result

Continue long jobs

Submit a long-running task, keep its task_id, and read status and outputs later

poyo_submit_jobpoyo_check_job
Status and output

Read account

Read current account and credit information before model execution

poyo_account
Account status

When should you use MCP, CLI, or the REST API?

Use MCP when an agent should choose and call models, the PoYo CLI for terminal or CI automation, and the REST API for application traffic or token-by-token output.

01

AI assistant or coding agent

Choose

MCP

Streamable HTTP

Why it fits

Let an agent discover models, read schemas and pricing, and call tools inside an editor or conversation.

You control

Tool scope and client permissions

Read docs
02

Terminal scripts or CI

Choose

PoYo CLI

@poyoapi/cli

Why it fits

Discover models, run generation, wait for jobs, and emit JSON, JSONL, or CSV from a shell.

You control

Command flags, input files, and output format

Read docs
03

Your application backend

Choose

REST API

HTTP + JSON / SSE

Why it fits

Handle application traffic, token streaming, polling, webhooks, and batch jobs.

You control

Request lifecycle and product experience

Read docs

Frequently asked questions

Learn about MCP connections, API keys, tool scope, billing, and long-job recovery.

Create an API key, follow the MCP documentation to add PoYo to your client, then check your account, model schema, and public pricing.

Create API KeyRead MCP docs