你将得到什么

• 理解 MCP 端点：streamable HTTP + JSON-RPC 2.0，POST only
• 两个工具：take_screenshot（耗配额）、list_devices（免费、可无 key）
• 一份可粘贴的 MCP 客户端配置片段

课前准备

1. 已完成第一课，手头有 access key（建议单独建一把「仅给 Agent」的 key，方便吊销）。
2. 该 key 不要开启「仅接受签名请求」——MCP 调用不带 signature，否则会 signature_required（官方指南原文提醒）。
3. 仍用环境变量，勿把 key 写进 Prompt。

export CURLSHOT_KEY='你的_access_key'

一、MCP 端点长什么样

• URL：https://curlshot.com/api/mcp
• 传输：streamable HTTP（每次独立 POST，无会话流；对端 GET 会 405）
• 鉴权：Authorization: Bearer YOUR_ACCESS_KEY（take_screenshot 需要）
• 协议：JSON-RPC 2.0；支持的 protocolVersion 含 2025-06-18 等（见官方 initialize 响应）

Agent 可读总图：https://curlshot.com/llms.txt ；全量：https://curlshot.com/llms-full.txt 。

二、手搓 initialize（可不带 key）

curl -X POST "https://curlshot.com/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "kun-academy", "version": "1.0.0" }
    }
  }'

对照结果

• HTTP 200，JSON 含 "serverInfo"，名称多为 CurlShot
• instructions 里会提示用 Bearer 传 access key，并指向 https://curlshot.com/agent-md

常见方法（官方表）：

单 IP 另有约 120 次/分钟 的 MCP 入口限流（与套餐限流分开，以官方为准）。

三、调用 take_screenshot（可抄）

官方示例：

curl -X POST "https://curlshot.com/api/mcp" \
  -H "Authorization: Bearer ${CURLSHOT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "take_screenshot",
      "arguments": { "url": "https://example.com", "format": "webp" }
    }
  }'

对照结果（成功）

• result.isError 为 false
• content 通常含：
  • text：摘要（地址、像素、体积、本周期剩余次数、Download: 临时链接）
  • image：base64 图 + mimeType（模型可直接「看见」页面）
• 计 1 次截图配额

MCP 默认与 REST 不同（官方强调）：
经 MCP 时，未指定则 format 默认 jpeg，且 block_ads、block_cookie_banners 默认 true。普通 API 默认是 png，且两项拦截默认 false。

文件 超过约 6 MB 时，仍可能成功，但只回 text + Download 链接、不内嵌 base64——模型就「看」不到图了。应缩小视口、改用 jpeg/webp、或去掉 full_page。

四、list_devices（免费）

curl -X POST "https://curlshot.com/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "list_devices", "arguments": {} }
  }'

对照结果

• 不需要 key、不耗配额
• 返回设备预设列表（name 即 viewport_device 可用值，如手机/平板/笔记本）

五、接到 MCP 客户端（Cursor / Claude 等）

官方给出的通用配置形状（路径因客户端而异）：

{
  "mcpServers": {
    "screenshots": {
      "type": "http",
      "url": "https://curlshot.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_KEY"
      }
    }
  }
}

操作提示：

1. 把 YOUR_ACCESS_KEY 换成环境变量或客户端密钥槽，不要写进发给模型的用户消息。
2. 重启/重载 MCP 后，让客户端执行 tools/list，应看到 take_screenshot 与 list_devices。
3. 对 Agent 说：「打开 https://example.com 截一张 webp，不要全页」，并确认它走了 MCP 工具而非瞎编。

更细的 Claude / Cursor / VS Code 说明见官方指南中的 MCP 仓库链接；本课以官网 JSON 为准即可跑通。

六、省 token 与缓存（跟做建议）

官方给 Agent 的建议（摘要）：

• 优先 jpeg / webp，视口适中（默认约 1280×1024；扫一眼可用更小）
• 非必要不要 full_page
• 只关心一块 UI 时传 selector
• 同一页反复看："cache": true（命中免费；你刚改过页面则不要开）

示例 arguments：

{
  "url": "https://developer.mozilla.org",
  "format": "webp",
  "cache": true
}

七、失败时 Agent 该怎么做

工具失败时 HTTP 往往仍是 200，看 isError: true 与 text 里的错误码：

成功摘要末尾会带「本周期还剩多少次」，便于 Agent 提前刹车。

八、本课检查清单

• initialize 返回 CurlShot serverInfo
• take_screenshot 对 example.com 成功且 isError=false
• list_devices 无 key 可跑
• MCP 客户端配置使用 Bearer，key 未进 Prompt
• 知道 MCP 默认 jpeg + 拦广告/cookie 条

课后延伸（可选）

• 选项大全：https://curlshot.com/docs/options.md
• 登录态页面：https://curlshot.com/docs/guides/screenshot-behind-login.md
• OG 图：https://curlshot.com/docs/guides/open-graph-images.md

官方来源

1. https://curlshot.com/docs/guides/ai-agents.md
2. https://curlshot.com/llms.txt
3. https://curlshot.com/docs/getting-started.md
4. https://curlshot.com/.well-known/mcp.json
5. https://curlshot.com/openapi.json