PoYo MCP

Connect your AI assistant to PoYo to search the live model catalog, inspect schemas and prices, run models, and resume long-running generation tasks without leaving your editor. The hosted server uses stateless Streamable HTTP at https://api.poyo.ai/mcp. Initialization, tool discovery, and public model discovery work without authentication. Account access and model execution require a PoYo API key, which is validated on each authenticated request and is not stored by the MCP server.

Use MCP for agent-driven discovery and execution. Use the REST API for application traffic or token-by-token chat streaming.

Connect your client

Set POYO_API_KEY in the environment that starts your client, then use the matching configuration. The key is optional for public discovery, but configuring it now enables account and execution tools.

export POYO_API_KEY=... or $env:POYO_API_KEY=... applies only to the current terminal session. Apps launched from the desktop, such as Cursor, VS Code, or the Codex app, do not see it. For Skill and CLI use without MCP, npx -y @poyoapi/cli auth login avoids this; see the Quickstart.

Claude Code
Cursor
Codex
VS Code
Other clients

claude mcp add --transport http poyo \
  https://api.poyo.ai/mcp \
  --header "Authorization: Bearer $POYO_API_KEY"

The shell expands $POYO_API_KEY when you run this, so the actual key is saved in your Claude Code MCP config.See the Claude guide for Claude Desktop and native Windows setup.

Add this to your Cursor MCP configuration:

{
  "mcpServers": {
    "poyo": {
      "url": "https://api.poyo.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:POYO_API_KEY}"
      }
    }
  }
}

If authenticated remote servers are unavailable, use the Cursor stdio setup.

Add this to ~/.codex/config.toml:

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

Start a new Codex session after saving. See the Codex guide for typed tools and Agent Skill setup.

Run MCP: Open User Configuration and add:

{
  "servers": {
    "poyo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@poyoapi/mcp"],
      "env": {
        "POYO_API_KEY": "${input:poyo-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "poyo-api-key",
      "description": "PoYo API key",
      "password": true
    }
  ]
}

See the VS Code guide for verification steps.

Use Streamable HTTP with this endpoint and header:

URL: https://api.poyo.ai/mcp
Authorization: Bearer YOUR_API_KEY

If the client only supports stdio, configure the local bridge:

{
  "mcpServers": {
    "poyo": {
      "command": "npx",
      "args": ["-y", "@poyoapi/mcp"],
      "env": { "POYO_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Keep the API key out of prompts, URLs, client-side applications, and committed configuration. Prefer environment variables or secure client inputs.

Verify the connection

Ask your assistant:

Use PoYo to check my account, find an image model for a cinematic product
photo, show its input schema, and explain which execution tool
you would use. Do not run a paid request yet.

A working connection can call poyo_account, poyo_search_models, and poyo_get_model_schema.

Available tools

Discovery

Tool	What it does
`poyo_search_models`	Search models by query, service type, category, or tags
`poyo_get_model_schema`	Read current input/output schemas, examples, protocols, and capabilities

Execution

Tool	What it does
`poyo_chat`	Run chat and return one complete MCP Tool Result
`poyo_run_model`	Run generation and wait up to 30 seconds
`poyo_submit_job`	Submit long-running generation and return a `task_id`
`poyo_check_job`	Check task status and retrieve outputs

Utility

Tool	What it does
`poyo_account`	Read authenticated account and credit information

Try these requests

Generate an image

“Find a suitable image model for a cinematic product photo, then generate the image.”

The assistant searches the catalog, checks the model schema, then calls poyo_run_model.

Turn an image into video

“Find a model that accepts this image, create a five-second video, and wait for the result.”

The assistant inspects compatible models, calls poyo_submit_job, and polls the returned task_id with poyo_check_job.

Load typed model tools

The default endpoint exposes a compact discovery and execution tool set. Add explicit model IDs when you want model-specific JSON Schemas:

https://api.poyo.ai/mcp?models=flux-schnell,tripo3d-h3.1-text-to-3d

See Choose MCP tools for category filters, selection guidance, and limits.

Handle long-running tasks

Use poyo_run_model for short work and poyo_submit_job for long-running media. See Task lifecycle for polling, normalized statuses, retries, and result handling.

How it works

Your MCP client sends a tool request to PoYo, with a Bearer token when the tool requires authentication.
Public discovery reads the live Capability Catalog without account access.
Authenticated tools apply the same access, balance, and routing rules as the public API.

Troubleshooting

See Troubleshooting integrations for authentication, missing tools, streaming behavior, task recovery, error codes, and retry guidance.

Get started

MCP

Clients

Workflow tools

Connect with MCP

PoYo MCP

Connect your client

Verify the connection

Available tools

Discovery

Execution

Utility

Try these requests

Generate an image

Turn an image into video

Load typed model tools

Handle long-running tasks

How it works

Troubleshooting

​PoYo MCP

​Connect your client

​Verify the connection

​Available tools

​Discovery

​Execution

​Utility

​Try these requests

​Generate an image

​Turn an image into video

​Load typed model tools

​Handle long-running tasks

​How it works

​Troubleshooting

PoYo MCP

Connect your client

Verify the connection

Available tools

Discovery

Execution

Utility

Try these requests

Generate an image

Turn an image into video

Load typed model tools

Handle long-running tasks

How it works

Troubleshooting