MCP

Foca MCP 让 AI 客户端查询积分余额、通过 HTTPS 图片地址创建放大任务，并获取处理结果。MCP 使用高级放大引擎 physics，与网站共用帐号积分和套餐权限，每次创建任务处理一张图片。默认输出为 2K，每张图片消耗 15 积分。

连接客户端

创建 MCP 任务和新 API 密钥需要有效付费订阅，或历史成功购买过积分包。成功购买过积分包后，即使积分包余额归零，仍保留资格。注册赠送积分不提供资格。仅购买积分包的账户可创建 2K 任务，更高档位需要对应的有效订阅。

1. 登录后进入 API 密钥设置，创建密钥。
2. 创建时立即保存密钥，完整密钥只展示一次。
3. 选择下方客户端。端点使用 Streamable HTTP，请求需要携带 Authorization: Bearer YOUR_API_KEY。

{
  "mcpServers": {
    "foca": {
      "url": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

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

claude mcp add --transport http foca https://focaupscaler.com/api/mcp   --header 'Authorization: Bearer YOUR_API_KEY'

[mcp_servers.foca]
url = "https://focaupscaler.com/api/mcp"
bearer_token_env_var = "FOCA_API_KEY"

export FOCA_API_KEY='YOUR_API_KEY'

{
  "mcpServers": {
    "foca": {
      "serverUrl": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "foca": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.15.1",
        "https://focaupscaler.com/api/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${FOCA_AUTH_HEADER}"
      ],
      "env": {
        "FOCA_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

API 密钥代表你的账户操作，并可消耗账户积分。请保存在客户端的秘密配置中，在 API 密钥设置 撤销不再使用的密钥。不要将密钥放进 URL、提示词或代码仓库。任务与积分均归属创建密钥的账户。

“在 ChatGPT 中阅读”和“在 Claude 中阅读”只会打开阅读本公开文档的提示词，不会连接 MCP 或授权访问账户。

积分与套餐权限

提交前请调用 get_upscale_info。各档位的 available 表示当前套餐是否有权使用，balance 还需足以支付本次任务费用。MCP 与网站共用积分余额，可在 套餐与积分页面 调整套餐或补充积分。

图片输入要求

• 使用无需额外鉴权即可下载的公网 HTTPS 地址，端口仅允许 443；URL 中不能包含用户名或密码。私网和本地地址会被拒绝。
• 图片必须是有效的 JPEG、PNG 或 WebP，最大 20 MB，即 20 MiB 或 20,971,520 字节。
• 输入图片最多 6400 万像素，即 64 MP。
• 可以使用临时签名 URL，但有效期需覆盖下载过程。下载总时限为 20 秒，最多允许三次重定向。

输入图片下载或校验失败时，不会创建任务或扣除任务积分。

JSON-RPC 请求示例

MCP 客户端通常会自动完成初始化和工具发现。如需直接查看请求，可在同一个终端会话中依次执行以下示例，将 API 密钥和示例图片地址替换为自己的值。

所有请求均使用 POST 和下方请求头。端点返回 JSON，采用无状态模式，不签发会话 ID，也不提供独立的 GET SSE 连接。示例使用协议版本 2025-11-25；客户端应在后续请求中使用 initialize 协商得到的版本。

export FOCA_API_KEY='YOUR_API_KEY'

foca_mcp() {
  curl --silent --show-error 'https://focaupscaler.com/api/mcp' \
    --header "Authorization: Bearer $FOCA_API_KEY" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json, text/event-stream' \
    --header 'MCP-Protocol-Version: 2025-11-25' \
    --data-binary @-
}

初始化与工具发现

先发送 initialize，初始化成功后再发送 notifications/initialized 通知。初始化结果会标识服务器名称 foca-upscaler，并声明工具能力。

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "foca-example-client",
      "version": "1.0.0"
    }
  }
}
JSON

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
JSON

通过 tools/list 获取工具及参数定义：

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
JSON

响应中的 result.tools 包含 get_upscale_info、upscale_image 和 get_upscale_task。请遵守各工具的 inputSchema，额外参数会被拒绝。

1. 通过 get_upscale_info 查询帐号

参数为空对象 {}。查询本身不消耗任务积分。

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_upscale_info",
    "arguments": {}
  }
}
JSON

以下是拥有全部档位权限的帐号的 result.structuredContent 示例：

{
  "engine": "physics",
  "balance": 200,
  "can_create_tasks": true,
  "tiers": [
    { "resolution_tier": 2, "credits": 15, "available": true },
    { "resolution_tier": 4, "credits": 30, "available": true },
    { "resolution_tier": 8, "credits": 60, "available": true },
    { "resolution_tier": 16, "credits": 120, "available": true }
  ],
  "max_file_size_bytes": 20971520,
  "formats": ["image/jpeg", "image/png", "image/webp"]
}

balance 为当前积分余额，tiers 列出各档位费用与套餐可用性。max_file_size_bytes 和 formats 表示支持的文件大小和格式。工具响应还包含一个 content 文本项，内容为同一数据的 JSON 字符串；示例仅展示解码后的 structuredContent。

can_create_tasks 表示账户当前是否具备 MCP 付费使用资格。订阅到期后，有效且未撤销的 API 密钥仍可调用 get_upscale_info 和 get_upscale_task；若没有成功购买积分包的记录，can_create_tasks 将变为 false，无法创建新任务。该字段不代表积分充足，也不代表有权使用所有档位。

2. 通过 upscale_image 创建任务

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "upscale_image",
    "arguments": {
      "image_url": "https://images.example.com/source.png",
      "resolution_tier": 2,
      "idempotency_key": "source-001-2k"
    }
  }
}
JSON

新建任务会在处理结束前返回 result.structuredContent，例如：

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "pending",
  "credits_charged": 15,
  "credits_remaining": 185,
  "resolution_tier": 2
}

后续查询使用 task_id 中的 UUID。任务异步执行，收到创建响应时，status 也可能已经推进到后续状态。credits_charged 记录该任务的积分费用，当前余额请重新调用 get_upscale_info 查询。

创建和查询任务都会返回 credits_remaining，表示响应时账户的当前积分余额。幂等重放会返回当前余额，可能与首次扣费后的余额不同。

3. 通过 get_upscale_task 获取结果

唯一参数为必填的 task_id，使用创建任务返回的 UUID。只能查询 API 密钥所属帐号的任务。请将下方示例 UUID 替换为你的任务 ID。

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_upscale_task",
    "arguments": {
      "task_id": "00000000-0000-4000-8000-000000000001"
    }
  }
}
JSON

成功任务的 result.structuredContent 如下。下载地址和时间仅作示例：

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "succeeded",
  "credits_charged": 15,
  "credits_remaining": 185,
  "resolution_tier": 2,
  "download_url": "https://downloads.example.com/result.png?signature=EXAMPLE",
  "expires_at": "2026-10-17T13:00:00.000Z"
}

任务状态与结果有效期

请为 get_upscale_task 查询设置间隔，遇到限流时逐步延长等待时间。状态变为 succeeded 或 failed 后停止查询。任务会在服务端持续推进，无需在处理期间一直保持 MCP 连接。

下载链接临时有效，expires_at 为 ISO 8601 时间戳，请以实际返回的时间为准。链接默认有效一小时，但可能因服务配置而变化。若仅下载链接过期，可在结果保留期内重新查询任务，取得新的签名链接。

任务结果自创建时间起保留 24 小时。超出保留期后会返回 status: "failed" 和 error_code: "RESULT_EXPIRED"；若记录已被清理，则返回 TASK_NOT_FOUND。请在保留期内下载并自行保存图片。

重试与幂等

创建请求超时或响应丢失后，重试必须保持 idempotency_key、image_url 和 resolution_tier 三者一致。重复请求会返回原任务，不会重复扣除任务积分。幂等键按帐号生效，同一帐号的不同 API 密钥也共用该范围。

不同图片地址或档位应使用新的幂等键。同一键搭配不同参数会返回 IDEMPOTENCY_CONFLICT。不要因为未收到响应就换新键，原任务可能已经创建。临时签名 URL 的查询参数发生变化，也属于请求参数变化。

幂等记录至少保留 30 天，超过 30 天后由每日清理删除。记录清理后再次使用旧键可能创建新任务并扣费，请勿在该期限之后重试旧的创建请求；任务结果仍按独立的 24 小时规则保留。

错误与限流

业务工具执行失败时，result.isError 为 true，result.structuredContent.error.code 给出错误码，并附带 message。请按错误码处理，不要依赖消息文案匹配。无效 JSON-RPC 或不符合 schema 的参数会被协议层拒绝。

所有客户端语言收到的错误消息均为英文。积分不足时，result.structuredContent 包含下方错误详情。使用 required_credits 和 credits_remaining 展示积分差额，使用 upgrade_url 打开定价页面。

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to create this task.",
    "required_credits": 15,
    "credits_remaining": 5,
    "upgrade_url": "https://focaupscaler.com/pricing"
  }
}

每个帐号每分钟最多 60 次 MCP 请求，其中每分钟最多 5 次新建任务尝试。HTTP 层可能返回 401 UNAUTHORIZED，表示密钥缺失、无效或已撤销；403 INVALID_ORIGIN 表示 Origin 请求头被拒绝；429 RATE_LIMITED 附带 Retry-After: 60；503 MCP_UNAVAILABLE 表示服务暂不可用。请使用能携带所需鉴权请求头的远程 MCP 客户端。

在 API 密钥设置中，无付费资格的账户调用 POST /api/mcp/keys 会收到 HTTP 403 PAID_ACCESS_REQUIRED，暂时无法创建密钥时会收到 HTTP 503 MCP_UNAVAILABLE。已有密钥仍可查看和撤销。无效 MCP Bearer 密钥始终返回 HTTP 401，不会伪装成成功的工具响应。

测试接入

连接后，可以向客户端发送以下提示词：

请调用 Foca 的 get_upscale_info，显示我的剩余积分和可用输出档位。不要创建图片任务。

成功返回说明客户端可以发现工具并完成鉴权。这项只读检查不消耗任务积分。之后若要验证图片处理，请提供自己的公网 HTTPS 图片地址并明确指定输出档位；创建任务会按上述费用扣除积分。

隐私与条款

提交图片前请阅读隐私政策和服务条款，仅提交你有权处理的图片。