MCP 工具

MCP 服务器的九个工具：各自接受什么、返回什么，以及何时会拒绝。

MCP 服务器的地址是 https://binference.io/api/mcp。连接客户端的方法见 MCP 服务器。

请求

Streamable HTTP，不使用会话。它支持 MCP 的 2026-07-28 版本和所有 2025 年的版本。每个请求都是独立的，所以每条消息都是一个 POST。GET 和 DELETE 返回 405。
每个请求都要带上密钥，格式为 Authorization: Bearer binf_... 或 x-api-key。
请求体要小。超过 64 KB 的请求返回 413。
每个密钥每分钟 60 个请求，暂停一段时间后最多可以一次发 20 个。超过这个速度返回 429。
工具列表固定。连接期间工具不会变化，所以服务器不发送变更通知，也不打开监听流。
可以从任何地方调用。和 API 的其他部分一样，任何来源（origin）都可以调用它。

HTTP 返回

每个工具都返回 200，即使它拒绝了请求（见拒绝）。其他状态码都出现在工具运行之前：

状态码	`error`	何时出现
`401`	`unauthorized`	没有发送密钥
`401`	`invalid_token`	密钥错误或已撤销
`405`		`GET` 或 `DELETE` 请求
`413`		请求体超过 64 KB
`429`		该密钥每分钟超过 60 个请求。在 `retry-after` 之后重试
`503`	`temporarily_unavailable`	无法验证密钥。在 `retry-after`（2 秒）之后重试

401 带有 WWW-Authenticate: Bearer realm="binference"。没有 OAuth 登录：密钥是唯一的访问方式。

429 会带上以秒为单位的 retry-after 和精确的 retry-after-ms，以及一个说明等待时间的 JSON-RPC 错误：

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "This key is making MCP requests faster than 60 a minute. Retry in 2 seconds."
  }
}

结果

每个工具都会返回两份结果：一份是 structuredContent，符合该工具的输出 schema；另一份是放在文本块中的相同 JSON，供只读取文本的客户端使用。

金额以美元计，用精确的十进制字符串表示，比如 "0.0012"。不要把它转成浮点数再转回来。
时间为 UTC 的 ISO 8601 格式。日期是 UTC 日期，比如 "2026-09-30"。
读取类工具标记为只读，所以客户端可以不经询问直接运行。revoke_key 标记为破坏性操作，所以客户端知道要先询问。

拒绝

工具无法完成请求时，会返回 isError: true 和一句说明原因的话。请把它展示给用户，或者据此处理：

{
  "content": [
    {
      "type": "text",
      "text": "This key has a spending limit, so it can only read. Use a key without a limit to create, change or revoke keys, or manage them at https://binference.io/account/keys."
    }
  ],
  "isError": true
}

消息开头	原因
This key has a spending limit	只有不设消费上限的密钥才能创建、修改或撤销密钥
No key 12 belongs to this agent	该密钥 ID 属于其他 Agent，或者不存在
This agent already has 10 active keys	先撤销一个
This agent made 20 keys over MCP	在任意 24 小时内最多创建 20 个。稍后再试，或者在 API 密钥页面创建
This agent is not active	已暂停的 Agent 无法获得新密钥
`label:` 或 `spending_limit.usd:`	该输入有误。这句话的其余部分会说明原因
Input validation error	某个输入缺失、类型错误或超出范围
bInference could not finish this right now	你这边没有问题。稍后重试

get_balance

密钥能花多少。没有输入。它的返回体与查询余额相同。

{
  "object": "balance",
  "agent": {
    "id": 42,
    "name": "Nova",
    "token": "0x9f3c7e2b8a41d05c6e1f9a8b7c2d3e4f50617777",
    "status": "active"
  },
  "spendable_usd": "18.40211",
  "balance_usd": "18.42211",
  "reserved_usd": "0.02",
  "running_calls": 1,
  "expiring": [
    { "at": "2026-10-02T00:00:00.000Z", "usd": "2.1084" },
    { "at": "2026-10-03T00:00:00.000Z", "usd": "4.92" }
  ],
  "key_limit": null
}

spendable_usd 是新调用现在可以预留的金额：余额减去运行中的调用占用的部分。
expiring 是每天的额度还剩多少、何时过期，最早过期的排在前面。额度有效期 7 天。
key_limit 是这个密钥的消费上限，没有则为 null。它的字段与下文的 spending_limit 相同。
账户的 agent.token 为 null。

get_limits

这个密钥及其 Agent 的限制。没有输入。

{
  "key": {
    "id": 12,
    "label": "prod-server",
    "prefix": "binf_7Hq2xYv9aB",
    "can_manage_keys": false,
    "spending_limit": {
      "limit_usd": "5",
      "reset": "daily",
      "spent_usd": "1.2",
      "reserved_usd": "0.02",
      "remaining_usd": "3.78",
      "resets_at": "2026-10-01T00:00:00.000Z"
    }
  },
  "agent": {
    "calls_per_minute": 600,
    "burst": 60,
    "max_running_calls": 8,
    "running_calls": 1,
    "max_active_keys": 10,
    "active_keys": 3
  },
  "request": { "max_body_mb": 4, "max_stream_minutes": 30, "max_call_minutes": 13 },
  "mcp": { "requests_per_minute": 60, "burst": 20, "keys_per_day": 20 },
  "images": {
    "uploads_per_day": 200,
    "max_upload_mb": 20,
    "upload_link_hours": 24,
    "result_link_days": 7,
    "max_results_gb": 5
  }
}

密钥没有消费上限时，can_manage_keys 为 true。
spending_limit.remaining_usd 是该密钥在本周期内还可以发起的金额：上限减去已花费的金额和运行中的调用占用的金额。
agent 中的限制由该 Agent 的所有密钥共享。参见速率限制。
mcp 是这个服务器自己的限制：每个密钥的请求数，以及 Agent 在 24 小时内可以在这里创建的密钥数。
images 是图像存储允许该 Agent 使用的量。

get_usage

Agent 按天和按模型统计的花费。它统计该 Agent 的所有密钥。

输入	类型	默认值	含义
`days`	integer	`7`	往回统计多少个 UTC 日，包括今天：`1` 到 `90`。`1` 表示只看今天

{
  "from": "2026-09-24",
  "to": "2026-09-30",
  "total": { "usd": "3.4102", "calls": 212, "tokens": 1840210 },
  "days": [
    { "day": "2026-09-29", "usd": "1.9", "calls": 130, "tokens": 1102400 },
    { "day": "2026-09-30", "usd": "1.5102", "calls": 82, "tokens": 737810 }
  ],
  "models": [
    {
      "model": "anthropic/claude-sonnet-5.5",
      "name": "Claude Sonnet 5.5",
      "usd": "3.1",
      "calls": 120,
      "tokens": 1400000
    },
    {
      "model": "google/gemini-3.8-flash",
      "name": "Gemini 3.8 Flash",
      "usd": "0.3102",
      "calls": 92,
      "tokens": 440210
    }
  ]
}

没有调用的日子不会列出。模型按花费从高到低排列。调用的费用确定后才会计入，通常在一分钟内。

list_calls

Agent 的调用，最新的在前。

输入	类型	默认值	含义
`key_id`	integer		只看这个密钥的调用
`limit`	integer	`20`	每页的调用数，`1` 到 `50`
`before`	string		上一页的 `next` 值，用于获取更早的调用

{
  "calls": [
    {
      "id": 88412,
      "started_at": "2026-09-30T11:02:41.118Z",
      "duration_ms": 2840,
      "key": { "id": 12, "label": "prod-server", "prefix": "binf_7Hq2xYv9aB" },
      "model": "anthropic/claude-sonnet-5.5",
      "model_name": "Claude Sonnet 5.5",
      "endpoint": "messages",
      "stream": true,
      "outcome": "ok",
      "http_status": 200,
      "error_code": null,
      "tokens": {
        "prompt": 8120,
        "completion": 412,
        "reasoning": null,
        "cached": 6400
      },
      "reserved_usd": "0.1",
      "charge_usd": "0.0142"
    }
  ],
  "next": "88412"
}

outcome 为 running、pending（已结束，费用尚未确定）、ok、stopped（你这边断开了连接）或 failed。失败的调用带有 http_status 和 error_code，它们的含义见错误。
reserved_usd 是调用开始时预留的金额。charge_usd 是它的实际费用，计价完成前为 0。
最后一页的 next 为 null。

list_keys

Agent 的有效密钥，最早创建的在前。没有输入。密钥的完整内容永远不会显示。

{
  "keys": [
    {
      "id": 12,
      "label": "prod-server",
      "prefix": "binf_7Hq2xYv9aB",
      "created_at": "2026-09-20T09:12:03.000Z",
      "last_used_at": "2026-09-30T11:02:41.000Z",
      "month_usd": "24.8",
      "spending_limit": null,
      "this_key": true,
      "created_by_key_id": null
    }
  ],
  "max_active": 10
}

对于当前连接使用的密钥，this_key 为 true。
created_by_key_id 是通过 MCP 创建它的密钥；在 API 密钥页面创建的密钥则为 null。
month_usd 是该密钥在本自然月（UTC）的花费。
spending_limit 的字段与 get_limits 中的相同，没有则为 null。

create_key

为 Agent 创建一个新密钥。需要使用没有消费上限的密钥。

输入	类型	含义
`label`	string，必填	用来辨认它的名称，一行，最多 60 个字符
`spending_limit`	object	不传则创建没有上限的密钥
`spending_limit.usd`	string 或 number	每个周期最多可以花费的金额，范围 `0.01` 到 `1000000`，比如 `"5"`
`spending_limit.reset`	string	`daily`、`weekly` 或 `monthly`。周期从 UTC 时间 00:00 开始，每周从周一开始

{
  "key": "binf_...",
  "id": 15,
  "label": "worker-2",
  "prefix": "binf_Qp4mZt81Rw",
  "created_at": "2026-09-30T12:00:00.000Z",
  "spending_limit": {
    "limit_usd": "5",
    "reset": "daily",
    "spent_usd": "0",
    "reserved_usd": "0",
    "remaining_usd": "5",
    "resets_at": "2026-10-01T00:00:00.000Z"
  }
}

key 只显示这一次，之后不会再显示。在做其他任何事情之前，先把它保存好。一个 Agent 最多可以有 10 个有效密钥，并且在任意 24 小时内最多通过 MCP 创建 20 个。新密钥会记录为由你当前连接使用的密钥创建。

update_key

重命名 Agent 的某个密钥，或者设置、修改或移除它的消费上限。需要使用没有消费上限的密钥。

输入	类型	含义
`key_id`	integer，必填	密钥的 `id`，来自 `list_keys`
`label`	string	新名称
`spending_limit`	object 或 `null`	新上限，格式同 `create_key`；传 `null` 则移除上限

传入 label、spending_limit 或两者都传。它返回的密钥与 list_keys 中显示的格式相同。在周期中途设置上限时，会计入该密钥在本周期内已经花掉的金额。

revoke_key

撤销 Agent 的某个密钥。需要使用没有消费上限的密钥。

输入	类型	含义
`key_id`	integer，必填	密钥的 `id`，来自 `list_keys`

{ "key_id": 15, "revoked": true, "this_key": false }

密钥在下一次调用时就会停止工作；已经在运行的调用会继续完成。对同一个密钥撤销两次，返回的结果相同。如果 this_key 为 true，你正在使用的连接也会停止工作。

create_upload

获取一个上传单张图像的链接，让模型可以通过链接读取较大或本地的图像。任何密钥都可以使用，前提是该 Agent 有额度。

输入	类型	含义
`content_type`	string，必填	`image/png`、`image/jpeg`、`image/webp` 或 `image/gif`
`size`	integer，必填	图像的精确大小，以字节计，最大 20 MB（20,971,520）

它返回的内容与 POST /uploads 相同：

{
  "object": "upload",
  "id": "upl_BTSNzIeW9d7D_ShZQ8fJEQ",
  "upload_url": "https://...r2.cloudflarestorage.com/binference-images/uploads/42/BTSNzIeW9d7D_ShZQ8fJEQ.png?X-Amz-...",
  "upload_method": "PUT",
  "upload_headers": { "Content-Type": "image/png" },
  "upload_expires_at": "2026-10-01T12:10:00.000Z",
  "url": "https://...r2.cloudflarestorage.com/binference-images/uploads/42/BTSNzIeW9d7D_ShZQ8fJEQ.png?X-Amz-...",
  "expires_at": "2026-10-02T12:00:00.000Z",
  "content_type": "image/png",
  "size": 3400000
}

在 upload_expires_at 之前，用 PUT 把图像的字节连同 upload_headers 发送到 upload_url，然后在 expires_at 之前，在任意模型调用中把 url 作为图像发送。PUT 必须正好携带 size 个字节，且类型一致，否则存储会拒绝。一个 Agent 在任意 24 小时内最多可以发起 200 次上传。

请求复制标题链接

HTTP 返回复制标题链接

结果复制标题链接

拒绝复制标题链接

get_balance复制标题链接

get_limits复制标题链接

get_usage复制标题链接

list_calls复制标题链接

list_keys复制标题链接

create_key复制标题链接

update_key复制标题链接

revoke_key复制标题链接

create_upload复制标题链接

本页目录

请求