MCP · REST API · SDK

API 文档

Base URL、密钥、账号、搜索、调用、错误码。

对外网站、文档和 Skill 地址是 agentools.uno。clawdtools.uno 只作旧版兼容：继续提供 /v1、/mcp，并把人类页面跳到 agentools.uno。

不是写代码？

接现成 Agent？去接入页，不用申请密钥。

打开接入页
Skill · SKILL.md
https://agentools.uno/SKILL.md

给终端里的 Agent：Claude Code、Codex CLI、Cursor、OpenClaw

MCP · Streamable HTTP
https://agentools.uno/mcp

给带客户端的 Agent：ChatGPT、Codex、Claude、Cursor

认证

调用工具、评分与账户相关接口需 Bearer Token（API Key）；搜索与浏览公开。请前往API 密钥页面获取。

Base URL https://agentools.uno · Authorization: Bearer uno_…

GET /v1/auth/me

当前用户、套餐、剩余积分。

shell
curl -s https://agentools.uno/v1/auth/me \
  -H "Authorization: Bearer uno_…"
json
{
  "id": "usr_…",
  "email": "you@example.com",
  "name": "You",
  "plan": "free",
  "free_credits_remaining": 500,
  "balance": 0,
  "api_keys": [{ "id": "…", "prefix": "uno_", "name": "Default", "active": true }]
}

CLI Agent（设备码流程）

shell
# 1. Request device code
curl -s -X POST https://agentools.uno/oauth/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_id":"my-agent"}'

# 2. User authorizes, then poll — access_token is a uno_… key
curl -s -X POST https://agentools.uno/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"device_code":"DEVICE_CODE","client_id":"my-agent"}'

编程接入

REST API · 快速开始

产品就两个端点：先搜再调。认证和账号接口另列在旁边。

1. 搜索工具

GET/v1/tools
shell
curl -s "https://agentools.uno/v1/tools?q=weather&limit=5&mode=hybrid" \
  -H "Authorization: Bearer uno_…"

返回含 input_schema（JSON Schema），可知具体入参。

查询参数：q（关键词）、category、server（按 server slug 过滤）、mode=keyword|semantic|hybrid（默认 hybrid）、limit（≤50）、offset。搜索为公开接口——Bearer token 可选，仅用于记录调用日志。

json
{
  "tools": [
    {
      "tool": "weather-free.get_current_weather",
      "name": "get_current_weather",
      "desc": "Get current weather for a city",
      "desc_en": "Get current weather for a city",
      "input_schema": { "type": "object", "properties": { "location": { "type": "string" } }, "required": ["location"] },
      "server": "weather-free",
      "server_name": "Weather Free",
      "category": "weather",
      "auth_required": false,
      "operation": { "type": "read", "idempotency_mode": "none", "idempotency_key_field": null },
      "stats": { "avg_ms": 234, "calls_7d": 1200, "success_rate": 0.99, "rating": 4.5 },
      "pricing": { "mode": "per_call", "cost": 1.0 }
    }
  ],
  "total": 1,
  "mode": "hybrid"
}

2. 调用工具

POST/v1/call
shell
curl -s -X POST https://agentools.uno/v1/call \
  -H "Authorization: Bearer uno_…" \
  -H "Content-Type: application/json" \
  -d '{"tool": "amap-maps.weather", "arguments": {"city": "北京"}}'
JSON

响应格式

json
{
  "data": {"temperature": "22C", "weather": "晴"},
  "error": null,
  "meta": {
    "latency_ms": 234,
    "credits_used": 1.0,
    "outcome": "executed",
    "retryable": false
  }
}

meta 说明这次调用花了多少、以及能不能重发：latency_ms、credits_used、outcome（executed / not_executed / outcome_unknown）、retryable。

重试安全

搜索结果里每个工具都带 operation：type 为 read 或 write，idempotency_mode 为 none / native / gateway / keyed。只有工具只读、明确幂等，或 meta.outcome 为 not_executed 时才可重试。写操作一旦返回 outcome_unknown 绝不能重发——网关正是为此把 retryable 置为 false。

限流

POST /v1/call 每用户每分钟 120 次，其他需鉴权端点 60 次。超限返回 rate_limit_exceeded，meta 里带 retry_after_seconds 与 limit_per_minute，按提示退避，不要硬打。

更多端点

除搜索与调用外，以下为 Agent 与 SDK 常用端点。除标注外均需 Bearer token。

GET /v1/servers列出已托管 server 及工具数，按分类聚合（公开）
GET /v1/tools/{tool_slug}单个工具详情，含完整 pricing 与 stats（公开）
POST /v1/rate为工具评分 0.0–5.0；upsert 你的评分并更新聚合值
GET /v1/auth/me当前用户信息——积分、套餐、余额
GET /v1/usage/summary今日 / 7 天 / 30 天用量汇总
GET /v1/usage/history分页调用明细，可按 tool / server / 成功与否过滤
GET /v1/auth/keys列出你的 API key
POST /v1/auth/keys创建新 API key（仅返回一次原始 key）

Python SDK

SDK 封装同样两个端点，额外提供类型化异常、本地 schema 校验、重试策略与并发控制。 pip install uno-sdk

python
from uno_sdk import Uno

uno = Uno(api_key="uno_…")

# Search first so the SDK knows whether retries are safe
tool = uno.search("weather")[0]
result = uno.call(tool.slug, {"location": "Beijing"}, timeout=30)
print(result.data, result.credits_used)

# Validate args against the tool's JSON Schema before sending
uno.call_tool(tool, {"location": "Beijing"})  # validates by default

# Retry only reads or tools explicitly marked idempotent
uno.call_tool(tool, {"location": "Beijing"}, retry=3)

账号、积分与花费

每个结果自己就知道花了多少积分，其余用 me() 和 usage() 查。

python
account = uno.me()
account["plan"], account["free_credits_remaining"], account["balance"]

spent = uno.usage()
spent["summary"]["today"]["credits"]   # credits burned today
spent["trend"]                          # last 7 days, per day

# Cost and latency of the call you just made
result.credits_used, result.latency_ms, result.outcome

# Feed the catalog back: rate a tool 0.0–5.0
uno.rate(tool.slug, 4.5, "accurate and fast")

在代码里处理错误

网关的每个错误码都对应一个类型化异常。必须处理的是 AuthRequiredError：该工具需要你的用户先授权第三方应用，auth_url 就是授权地址。

python
from uno_sdk import (
    AuthError, AuthRequiredError, QuotaError,
    RateLimitError, InvalidArgumentsError, UpstreamTimeoutError,
)

try:
    result = uno.call_tool(tool, {"location": "Beijing"})
except AuthRequiredError as exc:
    # The tool needs a third-party app. Send your user to exc.auth_url,
    # then call again — no code change needed after they authorize.
    send_to_user(exc.auth_url)
except QuotaError:
    top_up()                       # out of credits
except RateLimitError as exc:
    sleep(exc.retry_after or 60)   # 120 calls/min per user
except InvalidArgumentsError as exc:
    log(exc)                       # caught locally, no credits spent
except (AuthError, UpstreamTimeoutError) as exc:
    alert(exc.code)

异步、批量与长任务

python
from uno_sdk import AsyncUno

async with AsyncUno(api_key="uno_…") as uno:
    # Concurrent batch with concurrency cap & order preservation
    results = await uno.call_batch([
        ("tikhub-douyin.fetch_video_stats", {"aweme_id": "aaa"}),
        ("tikhub-douyin.fetch_video_stats", {"aweme_id": "bbb"}),
    ], max_concurrency=10, return_exceptions=True)

    # Submit + poll long-running jobs to completion (transcription, etc.)
    transcript = await uno.call_async(
        "qingdou-video-text.qingdou_submit",
        {"urls": "https://v.douyin.com/xxx/"},
        "qingdou-video-text.qingdou_result",
        max_wait=180,
    )

给 OpenAI / Anthropic 的 function calling 直接出 schema：

python
from uno_sdk import OpenAIAdapter

functions = uno.search("weather", adapter=OpenAIAdapter())

MCP 客户端

ChatGPT、Codex、Claude、Cursor 或任何 MCP 客户端可直接连接使用全部 Uno 工具，无需编码。

ChatGPT 逐步教程 →Codex 逐步教程 →

OAuth 登录自动在浏览器中打开。授权后工具即刻可用。

能自定义请求头的客户端可以直接发 Authorization: Bearer uno_…，跳过 OAuth。其他客户端见 接入页.

Agent 接入（uno-cli）

任意 Agent 可复制首页那句话，或直接拉取指南：

shell
curl -s https://agentools.uno/SKILL.md

按文档执行 pip install uno-cli，然后 uno search / uno call。设备码登录，无需手写 curl。

错误说明

error含义
tool_not_found工具 slug 不存在
auth_required需 OAuth — 见响应中的 auth_url
insufficient_credits积分不足 — 见 recharge_url
rate_limit_exceeded触发限流 — 见 retry_after_seconds 后重试
tool_disabled / server_disabled工具或服务已被禁用
invalid_arguments参数未通过 JSON Schema 校验（客户端）
invalid_api_key缺少 Bearer，或不是有效的 uno_… 密钥
upstream_timeout / upstream_cancelled上游超时 / 连接被取消 — 仅重试只读或明确幂等操作；写操作 outcome_unknown 时绝不自动重试

计费

  • 免费：每日 500 积分，自动重置
  • 多数工具：每次 1 积分
  • AI 生成：AI 图像生成 10–300 积分/次；AI 视频生成 10–500 积分/次；AI 语音 / 音乐 100–500 积分/次
  • per_token 计费（LLM 类）：积分 = (请求 + 响应字符数 / 4) × token_price