PoYo MCP Server
每一个 PoYo 模型，都在你的 AI Agent 里
只需连接一次，Codex、Claude Code、Cursor 和 VS Code 就能搜索图像、视频、音频、对话与 3D 模型，读取当前 Schema 和公开价格，并通过 PoYo 执行任务。
MCP 就像一条安全连接，让 AI 助手直接使用 PoYo 模型，不需要你自己编写 API 请求。
npx -y @poyoapi/mcp适用于 VS Code 或仅支持 stdio 客户端的本地桥接，需要 Node.js 20+；快速接入请查看下方配置。
配置方法
第一次使用按三步完成连接；需要限制工具分类或指定模型时，再进入高级配置。
选择客户端并找到配置入口
选择你正在使用的应用，只查看对应的一套配置位置。
手动配置文件
~/.codex/config.toml适用范围
当前用户的所有项目
在客户端中打开 MCP 配置；如果没有可视化入口，请打开或创建上面的文件。
以 ./ 开头的路径位于当前打开的项目文件夹；如果目录或文件不存在，请先创建。
添加配置并验证
复制当前客户端的配置，保存后重新加载 MCP，再完成一次免费验证。
已有配置时请合并，不要覆盖
如果文件里已经有其他 MCP Server，只合并 poyo 服务节点并保留原有内容。直接覆盖可能导致其他连接失效。
将下面的配置添加到 ~/.codex/config.toml
[mcp_servers.poyo]
url = "https://api.poyo.ai/mcp"
bearer_token_env_var = "POYO_API_KEY"
tool_timeout_sec = 45启动客户端前，将 API Key 保存为 POYO_API_KEY 环境变量。 保存后启动一个新的 Codex 会话，让它重新读取 MCP 配置。
如何设置 POYO_API_KEY？
复制与你的系统对应的命令，把 your_api_key 替换为真实 Key，并在同一个终端会话中启动客户端。
macOS / Linux
export POYO_API_KEY="your_api_key"Windows PowerShell
$env:POYO_API_KEY="your_api_key"这些命令只对当前终端会话生效。不要把真实 Key 放入项目文件、截图或公开的命令记录。
让 Agent 帮我配置
复制一段限定权限的安全 Prompt，让 Agent 保留现有设置、不接触真实 Key，并在写入前先展示差异。
验证连接
按下面的顺序检查，不会发起付费模型任务。
- 1客户端能看到 PoYo 工具，说明配置文件已经加载。
- 2poyo_account 返回账户信息，说明 API Key 已经生效。
- 3poyo_search_models 返回模型，说明模型目录可以正常访问。
连接失败怎么办？
- 看不到工具：确认配置文件位置正确，并重新加载 MCP Server。
- 账户验证失败：确认 POYO_API_KEY 已设置，并从同一环境重新启动客户端。
- 连接失败：确认 Endpoint 为 https://api.poyo.ai/mcp，并检查网络或代理是否允许 HTTPS 访问。
工具、账户和模型目录都通过后，PoYo MCP 已完成连接。
默认开放 8 个紧凑工具
无需预选模型。Agent 会按任务搜索目录，再读取 Schema 和价格。
poyo_search_modelspoyo_get_model_schemapoyo_get_pricingpoyo_chatpoyo_run_modelpoyo_submit_jobpoyo_check_jobpoyo_account
Endpoint
https://api.poyo.ai/mcp[mcp_servers.poyo]
url = "https://api.poyo.ai/mcp"
bearer_token_env_var = "POYO_API_KEY"
tool_timeout_sec = 45配置使用环境变量或安全输入，不会把 API Key 写进 URL。
使用 PoYo MCP，Agent 能做什么？
直接用自然语言提出任务。Agent 会搜索匹配模型、读取输入要求与价格、执行生成，并在长任务完成后返回结果。
发现模型
根据自然语言任务搜索当前可用的图像、视频、音频、对话或 3D 模型
poyo_search_models读取参数
读取当前输入 Schema、示例、协议和模型能力
poyo_get_model_schema查询价格
在付费执行前查询候选模型的当前公开价格
poyo_get_pricing执行短任务
完成对话或可以在较短等待时间内返回的生成任务
poyo_chatpoyo_run_model继续长任务
提交耗时任务，保存 task_id，并在之后继续读取状态和结果
poyo_submit_jobpoyo_check_job读取账户
读取当前账户与积分信息，确认是否可以执行模型
poyo_accountMCP、CLI 与 REST API 应该怎么选？
让 Agent 自主选择和调用模型时使用 MCP；在终端或 CI 中自动化任务时使用 PoYo CLI；处理应用流量和逐 token 输出时直接使用 REST API。
AI 助手或编程 Agent
选择接口
MCP
Streamable HTTP为什么适合
让 Agent 在编辑器或对话中发现模型、读取 Schema 与价格，并直接调用工具。
终端脚本或 CI
选择接口
PoYo CLI
@poyoapi/cli为什么适合
在命令行发现模型、运行生成、等待任务，并输出 JSON、JSONL 或 CSV。
常见问题
了解 MCP 连接、API Key、工具范围、计费和长任务恢复。