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)都可以调用它。
- 文件夹的密钥只在自己的文件夹内。为 Agent 文件夹(在驾驶舱中)创建的密钥,只能查看和管理该文件夹的密钥和调用记录。它的余额和用量仍是整个账户的。
HTTP 返回
每个工具都返回 200,即使它拒绝了请求(见拒绝)。其他状态码都出现在工具运行之前:
| 状态码 | error | 何时出现 |
|---|---|---|
401 | unauthorized | 没有发送密钥 |
401 | invalid_token | 密钥错误或已撤销 |
403 | 该密钥所属的 Agent 文件夹已暂停。请在它的驾驶舱中恢复 | |
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 次上传。
create_video
发起一个视频,与 POST /videos 相同。任何密钥都可以使用,前提是该 Agent 有额度。它会立即返回任务;用 get_video 读取。
| 输入 | 类型 | 含义 |
|---|---|---|
model | string,必填 | GET /videos/models 中的模型 |
prompt | string,必填 | 视频中发生什么,最多 2,000 个字符 |
duration | integer,必填 | 秒数,必须是模型列出的值 |
resolution | string,必填 | 模型列出的值,例如 720p |
aspect_ratio | string,必填 | 模型列出的值,例如 16:9 |
generate_audio | boolean | 声音,在模型支持时 |
seed | integer | 同样的种子和设置会生成相似的视频 |
first_frame_url | string | 视频开始时的图片 |
last_frame_url | string | 视频结束时的图片,在模型支持时 |
reference_urls | string[] | 最多 3 张要保留的人物、物品或风格的图片 |
previous_video_id | string | 要继续延长的、此 Agent 已完成的视频 |
idempotency_key | string | 8 到 64 个字符:同一个键不会生成第二个视频 |
它返回任务:id、status、estimated_cost(最高花费),以及 POST /videos 返回的其他字段。
get_video
按 id 读取视频:先是 pending 或 in_progress,然后是 completed 或 failed。已完成的视频带有 download_url,一个有效期一小时的文件链接。失败的视频带有 error.code,从不扣费。每隔约 10 秒读取一次。
list_routes
这个密钥能调用的 bRoute:先是密钥主人自己的,然后是任何人都能调用的预设 bRoute。没有输入。
{
"routes": [
{
"model": "broute/coding",
"name": "Coding",
"starter": true,
"version": 1,
"compare_model": "anthropic/claude-sonnet-5.5",
"lanes": [
{
"lane": 1,
"description": "Hard coding work: designing a system or API, changes across many files",
"models": ["anthropic/claude-sonnet-5.5", "openai/gpt-6.1-sol"]
},
{ "lane": 3, "description": "Anything else", "models": ["openai/gpt-6-luna"] }
]
}
]
}model是调用它时用的名字,适用于 API 的任何格式。models先是通道的模型,然后是它的备用模型。最后一个通道是“其他”。
get_route_usage
密钥主人自己的一个 bRoute 在最近 7 天或 30 天内的情况:完成结算的调用、它们的扣费,以及与对比模型相比节省了多少。
| 输入 | 类型 | 说明 |
|---|---|---|
model | string | bRoute 的模型名,例如 broute/my-coder |
days | integer | 7(默认)或 30 |
{
"model": "broute/my-coder",
"days": 7,
"calls": 1520,
"spent_usd": "4.21",
"saved_usd": "11.36",
"baseline_usd": "15.57",
"lanes": [
{ "lane": 1, "calls": 210, "spent_usd": "3.9", "saved_usd": "0" },
{ "lane": 2, "calls": 1310, "spent_usd": "0.31", "saved_usd": "11.36" }
]
}baseline_usd是同样的调用用对比模型要花的钱;saved_usd是它减去实际扣费。某个通道花得更多时,它会低于零。- 不是密钥主人自己的 bRoute(包括预设 bRoute)会被拒绝:
list_routes会列出一个密钥能调用的 bRoute。