Search, Run, and Track PoYo Models from 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. The key is optional for public discovery, but configuring it enables account and execution tools.

Claude Code:

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

Cursor — add to your MCP configuration:

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

Codex — add to ~/.codex/config.toml:

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

VS Code — 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}"
      }
    }
  }
}

Other clients — use Streamable HTTP directly:

URL: https://api.poyo.ai/mcp
Authorization: Bearer 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 price, 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, poyo_get_model_schema, and poyo_get_pricing.

Available tools#

Discovery#

Execution#

Utility#

Try these requests#

Generate an image — "Find a suitable image model for a cinematic product photo, show me its price, then generate the image." The assistant searches the catalog, checks the model schema and pricing, 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.

Check pricing first — "Compare the prices of suitable image-to-video models. Do not run them." The assistant uses live catalog and pricing data without making a paid generation request.

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#

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

Back to Documentation Index · Next: Authentication