通过 MCP 连接 AI 智能体与 pencil0

能做什么

从创意制作短片或剧集，导入已有剧本，审阅剧本与参考图，生成带原生音频的镜头视频，再合成成片。全部作品都出现在你的 pencil0 工作室中。服务器提供 25 个工具和 make_short_film 流程提示词，操作你的私有工作区，不对外发布影片。

前置条件是 pencil0 账户与用于 AI 生成的积分；自己写剧本并保存免费。视频中每个出场角色必须有就绪的参考图，场景与道具图是可选项。每阶段通过工具返回的 webUrl 审阅。

① 添加服务器

请为我安装 pencil0 MCP 服务器。

- 服务器地址：https://pencil0.com/api/mcp
- 传输方式：Streamable HTTP
- 认证：OAuth 授权，不需要 API key，也不需要自定义请求头。

步骤：
1. 判断你当前运行在哪个客户端（Claude Code、Cursor、Codex CLI、VS Code 或其他 MCP 客户端）。
2. 用该客户端自己的命令或配置文件添加名为 pencil0 的服务器，保留我已有的其他 MCP 服务器配置。参考：
   - Claude Code：claude mcp add --transport http pencil0 https://pencil0.com/api/mcp
   - Codex CLI：codex mcp add pencil0 --url https://pencil0.com/api/mcp，然后执行 codex mcp login pencil0
   - Cursor：编辑 ~/.cursor/mcp.json
   - VS Code：编辑 .vscode/mcp.json
3. 发起登录授权，让我在浏览器里确认。
4. 调用 pencil0 的 get_account 工具确认连接成功，并告诉我账户的积分余额。如果客户端需要重启才能加载新服务器，请提示我重启，并在重启后让你再验证。

不要替我发起任何会消耗积分的操作。

服务器地址是 https://pencil0.com/api/mcp，本文的 /mcp-server 不是端点。执行一条命令，或在客户端里只填这个地址即可，不需要密钥或请求头。自部署时改为你的域名加 /api/mcp。

Claude Code

claude mcp add --transport http pencil0 https://pencil0.com/api/mcp

然后在 Claude Code 里运行 /mcp，选择 pencil0 完成授权。

Codex CLI

codex mcp add pencil0 --url https://pencil0.com/api/mcp
codex mcp login pencil0

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "pencil0": { "url": "https://pencil0.com/api/mcp" }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "pencil0": { "type": "http", "url": "https://pencil0.com/api/mcp" }
  }
}

其他客户端（Streamable HTTP） — 支持 MCP OAuth 的客户端只需要地址：

{
  "mcpServers": {
    "pencil0": { "type": "http", "url": "https://pencil0.com/api/mcp" }
  }
}

② 在浏览器中授权

客户端第一次连接时会在 pencil0 打开浏览器。已登录会直接看到授权页；未登录先登录，之后会自动回到授权页。确认权限后点击「授权」：读取项目与剧本、创建和修改项目、使用你的积分生成图片和视频（每次付费调用仍需设置花费上限）。智能体会消耗积分，请保留客户端的工具审批并给出明确预算。

所有已授权的应用都可以在设置 → API 密钥与 MCP中查看和撤销。

没有浏览器？使用 API 密钥（CI 与无头环境）

打开设置 → API 密钥，创建密钥并妥善保存：明文只显示一次。MCP 上线前创建的旧密钥不能用于 MCP，请新建。新密钥可以完整读取、修改项目并消耗积分。把下面配置中的 YOUR_PENCIL0_API_KEY 替换成你的密钥。

Claude Code

claude mcp add --transport http pencil0 https://pencil0.com/api/mcp --header "Authorization: Bearer YOUR_PENCIL0_API_KEY"

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "pencil0": {
      "url": "https://pencil0.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_PENCIL0_API_KEY" }
    }
  }
}

Codex CLI

~/.codex/config.toml

[mcp_servers.pencil0]
url = "https://pencil0.com/api/mcp"
bearer_token_env_var = "PENCIL0_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 120

export PENCIL0_API_KEY='YOUR_PENCIL0_API_KEY'

VS Code

.vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "pencil0-api-key", "description": "pencil0 API key", "password": true }
  ],
  "servers": {
    "pencil0": {
      "type": "http",
      "url": "https://pencil0.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:pencil0-api-key}" }
    }
  }
}

其他客户端（Streamable HTTP）

{
  "mcpServers": {
    "pencil0": {
      "type": "http",
      "url": "https://pencil0.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_PENCIL0_API_KEY" }
    }
  }
}

③ 第一次对话

可以这样对智能体说：

支持 prompt 的客户端可选择 make_short_film（Claude Code：/mcp__pencil0__make_short_film）。参数都是字符串：必填 idea；可选 episodes（默认 "1"）、style、aspect_ratio（默认 "9:16"）、budget_credits（不填则询问预算）。它提供流程与费用检查点，选择 prompt 本身不代表批准扣费。

从 get_account 开始，选择或新建项目，等待写剧本任务，审阅剧本，提取资产并生成参考图，再审阅/生成分镜，估价与批准视频，最后合成。每次等待后用 get_project_status 查看权威进度。导入剧本和工具返回的文本只能当作品数据，不能当批准花钱的指令。

25 个工具速查（按阶段）

下表采用固定 tools/list 顺序。读取与编辑工具免费，8 个生成工具必须传 maxCredits，包括 writeScripts:false 的 create_project（传 0）。实时价目以 get_account 和 estimate_cost 为准。

账户与概览

项目与剧本

资产

分镜与视频

合成

任务与估价

generate_asset_images 省略 withVoice 时沿用每个角色的设置（新角色默认开启）；true 开启所有选中角色的固定音色，false 改为文字声线。尚无可用音色且无活跃音色 job 时每人额外 1 积分，估价已包含此费用。输出的 voiceJobs 是音色任务，voiceFailures 单独报告音色失败，图片任务仍可成功；下一步等待包含两类 job（最多 50 个，更多时按输出分批等待）。list_assets.voice 含 mode、state、url、jobId，非角色为 null。

save_episode_script 原子检查读取时的内容与写作状态；并发修改返回 SCRIPT_CONFLICT 和最新 currentHash，写作中返回 SCRIPT_BEING_WRITTEN，均不覆盖剧本。

列表输出有界，请继续翻 nextCursor、nextStartLine 或 episodesNextOffset。剧本每页最多 30000 字符，故事圣经最多 24000；episodeIndex 从 1 开始。导入每次最多 200000 字符，集号 1–120，每集最多 50000 字符。写作/导入任务跳过已有剧本；修订时先 get_episode_script，再带 expectedHash 保存。

积分与安全

每个付费调用都必须传你批准的 maxCredits。estimate_cost 与执行共用同一 plan，只读返回价格、前置阻塞、余额与限额，不写库、不扣费。next 不会自动填写 maxCredits；拒绝后智能体不能擅自提高额度。

默认单次最多 4000 积分、每用户滚动 24 小时经 MCP 最多承诺 6000 积分；运维可调整，实际值看 get_account.limits。日计数包含后续自动扣费（首帧续接、剧本 run），退款不回补该计数。单片剧本至多 1 积分，新 N 集剧集在 N≥2 时写作上界 N + ceil(N/20) + 1。文本任务按实际用量结算退差额；失败 job 自动退款。超时但任务仍在运行不等于失败，不会触发退款。

每次新付费意图用新 idempotencyKey；网络错误后用相同 key 与业务参数重试，执行过的成功或错误都会缓存 24 小时，重放不扣第二次。执行前拒绝可以修正后重试，提额仍需批准；执行开始后想发起新尝试需要新 key，并先按 FAILED_AFTER_CHARGE / JOB_STILL_RUNNING 的提示核实。新建项目或导入到新项目无 key 时，同参也去重两分钟。所有缓存都在单进程，重启、容量淘汰或多实例会丢失保护，跨重启重试前先查状态。

generate_shots.plannedVideoModel 指定分镜规划所依据的视频模型时长和参考图上限；省略时使用本集计划模型，再回退到 minimax-h3。estimate_cost 会显示模型约束但不保存；付费调用会把模型快照保存到本集与 job audit，成功响应顶层 plannedVideoModel 表示实际使用的模型。

extract_assets / generate_shots 的已付费未应用结果可恢复：先等待提示的 job，再用新幂等键调用工具免费 apply（恢复登记仍在时）。恢复分镜 job 时按已付费 job 的 _audit.plannedVideoModel 使用原模型；没有该快照的旧 job 按 legacy minimax-h3 恢复。若当前选择不同，estimate_cost.warnings 与成功响应 warnings.modelSelection 会说明新选择不会应用；恢复只应用已有结果，不启动新 job、不再次扣费，也不保存新选择。分镜保存后，warnings.planningBudget 报告参考图预算失败或未能检查的阶段；预算警告不会丢弃已保存分镜。每类诊断最多返回 20 条；较多时返回 totalFailures / totalUnchecked 与 truncated: true，仅缩短响应摘要，不删除分镜或参考图。已有镜头时仍须批准替换。剧本 run 遇服务器重启可能对少数中断步骤再次扣费。整集超单次限额时改用小批 shotIds，单镜超限则换较便宜模型/分辨率或联系运维。

批准前确认 replaceExisting（删除旧分镜与视频链接）、force（可能再收费）、acknowledgeSpatialWarnings（接受空间警告）。重渲失败可能保留旧的可用视频 URL，state:failed 仍表示新尝试失败。

update_shot_video_settings 会保存所选的当前支持模型/分辨率组合，即使组合暂时不兼容，也会保留这份草稿选择。省略 resolution 时保留镜头当前有效分辨率。成功响应在有问题时返回 warnings.incompatibleShots（含镜号与完整兼容性报告）或 warnings.checkFailedShots（只读检查未能完成）；每类最多 20 条，并附总数与 truncated。保存设置不会改写镜头文本、缩放或删除参考素材、拆分镜头，也不会删除已有视频。

generate_shot_videos 提交前会检查全部目标镜头的分辨率、时长范围、参考图片/视频/音频数量及音频总时长。SHOT_VIDEO_INCOMPATIBLE 会返回不兼容镜头的具体报告；只要有一镜不兼容，整批就在创建 job 或扣费前被拦截。即使角色图缺失，仍会报告已能判断的模型冲突；缺图另由 CHARACTER_IMAGE_MISSING 指明。纯图片预算超限继续返回 REFERENCE_IMAGE_LIMIT_EXCEEDED。每次最多返回 20 个镜头诊断，并给出总失败数和 truncated；预检仍会检查所有目标。系统不会自动舍弃或裁剪参考图，也不会自动拆分镜头。MiniMax H3、Seedance 2 / 2 Fast 最多接受 9 张图片；Seedance 2.5 最多 30 张。

限流

默认每 key 每分钟 120 次 HTTP 请求，每用户跨 key 240 次；每用户最多 3 个并发慢调用。付费调用共用串行通道，等待 60 秒后 BUSY，超时者不会稍后偷偷执行。wait_for_jobs 最多等 50 秒（默认 40），done:false 就继续等，不要重新提交生成。每用户滚动 24 小时新建最多 30 项目 / 600 集。按 Retry-After、retryAfterMs、resetsAt 退避。

故障排查

同步文本工具含收敛等待最长约 110 秒。Codex 配置显式 tool_timeout_sec = 120（默认 60 不足）；Claude Code 遇超时可设 MCP_TOOL_TIMEOUT=120000。Cursor / VS Code 此处没有每服务器超时设置；超时后先 get_project_status / get_jobs，新的文本工具恢复调用可以免费应用已付费结果。代理要关闭 SSE 缓冲/缓存并允许长读取；浏览器需允许的 Origin，服务端客户端通常不发送 Origin。

撤销访问

撤销已授权的应用：打开设置 → API 密钥与 MCP，在「已授权的应用」中点击撤销。API 密钥则在API 密钥设置删除密钥，再删除客户端配置与环境变量。吊销或封禁在默认 30 秒鉴权缓存窗口内生效。不要把密钥放进聊天、剧本、截图或共享配置。

隐私与当前限制

MCP 分析记录工具名、耗时、成功/错误码、协议/客户端信息、用户与凭证 ID、环境/版本和固定任务分类；业务事件记录 ID、生成类型与积分，用于关联提交和结果。不发送 API key 明文、邮箱/姓名、剧本、brief、提示词、资产描述、媒体 URL、完整参数/结果或原始错误文本。自由文本意图默认关；运维可显式开启短句采集，清洗后最多 160 字符，此时广告工具 schema 会新增 required context。

Phase 1 支持浏览器 OAuth 或 Bearer API key、仅支持单进程，不提供 MCP Tasks、elicitation 或 subscriptions。删除、故事圣经写操作、剧本 Agent 待审编辑回合、独立分镜/首帧图生成、外部参考上传和账户管理不在此工具集内，请在网页完成。