把一个智能体接到 Tunc Orb
智能体通过 MCP、A2A 或 HTTP API 使用 Tunc Orb:用 Tunc 登录、用代码连接,或者用 API 密钥。你的 Tunc 账号管理智能体、密钥和存储;它从不读取、也不会显示你的智能体存了什么。
用 Tunc 账号登录
支持登录的 MCP 客户端用你的 Tunc 账号连接 https://mcp.tuncorb.com/mcp:不需要复制任何密钥。 另一个产品的地址是 https://mcp.tuncart.com/mcp。 你的客户端会打开 Tunc;你登录,或者用组织与条款创建一个免费账号,然后授权一次并选择它可以使用什么。
| 客户端 | 步骤 |
|---|---|
| claude.ai, Claude Desktop and Claude mobile | Customize → Connectors → Add custom connector → 名称填 Tunc Orb,URL 填 https://mcp.tuncorb.com/mcp → Add → Connect。免费版只允许一个自定义连接器;Team 和 Enterprise 由 Owner 在 Organization settings → Connectors 里添加。这个链接会打开对话框,名称和 URL 已经填好: |
| Claude Code | 先添加服务器,然后运行 /mcp,选择 tunc-orb,再 Authenticate。 |
| ChatGPT | Settings → Apps & Connectors → Advanced → 打开 Developer mode → Create → 名称填 Tunc Orb,URL 填 https://mcp.tuncorb.com/mcp,Authentication 选 OAuth → Create → Connect。 |
| Cursor | 加到 ~/.cursor/mcp.json,然后 Settings → MCP:会显示“Needs login” → Login。 |
| VS Code (Copilot) | 命令面板 → MCP: Add Server → HTTP → https://mcp.tuncorb.com/mcp → 名称 tunc-orb → 允许登录提示。 |
| Gemini CLI | 加到 settings.json,然后运行 /mcp auth tunc-orb。 |
| Copilot Studio | Tools → Add a tool → New tool → Model Context Protocol → URL 填 https://mcp.tuncorb.com/mcp → Authentication 选 OAuth 2.0,Dynamic discovery。 |
只接受请求头的客户端改用 API 密钥。
没有浏览器的智能体
运行在服务器或终端里的智能体会给你一个代码和一个链接,例如 https://tuncorb.com/connect?code=BCDF-GHJK。打开它,登录,确认代码一致后授权。任何支持设备授权(RFC 8628)的 OAuth 库都可以做:
# 每个智能体只需注册一次(不需要重定向地址)
curl -s https://core.tunc.ai/oauth/register -H 'content-type: application/json' \
-d '{"client_name":"report-writer","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"]}'
# → {"client_id":"dcr_…",…}
# 申请一个代码,把 verification_uri_complete 给对方看
curl -s https://core.tunc.ai/oauth/device_authorization -d client_id=dcr_… -d scope="orb.read orb.write"
# → {"device_code":"…","user_code":"BCDF-GHJK",
# "verification_uri_complete":"https://tuncorb.com/connect?code=BCDF-GHJK","interval":5,"expires_in":600}
# 每隔 interval 秒轮询一次,直到对方允许
curl -s https://core.tunc.ai/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d device_code=… -d client_id=dcr_…
# → 在此之前是 {"error":"authorization_pending"};允许之后:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}
# 在 access token 过期之前,用 refresh token 换一组新的
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…把 access token 作为 Authorization: Bearer 发送到 https://mcp.tuncorb.com/mcp。每次刷新都会返回新的 refresh token:只保留最新的那个,重复使用旧的会把智能体断开。
A2A
支持 A2A 1.0 的智能体可以在 https://tuncorb.com/.well-known/agent-card.json 找到 Tunc Orb,并调用 https://a2a.tuncorb.com。每条消息带一个数据部分,里面有 skill(一个 MCP 工具名,例如 data_read)和它的 arguments;返回值就是那个工具的结果。使用 API 密钥,或者用资源 https://a2a.tuncorb.com 登录。
curl -s https://a2a.tuncorb.com -H "Authorization: Bearer $TUNC_API_KEY" -H 'A2A-Version: 1.0' \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{
"messageId":"m-1","role":"ROLE_USER",
"parts":[{"data":{"skill":"data_read","arguments":{"operation":"list"}},"mediaType":"application/json"}]}}}'
# → {"jsonrpc":"2.0","id":1,"result":{"message":{"role":"ROLE_AGENT",
# "parts":[{"data":{…工具返回的结果…},"mediaType":"application/json"}],…}}}改名、更改权限或断开
每个智能体和密钥都列在 tunchub.com → 智能体与密钥,连同它的连接方式和它能做什么。可以改名,用“更改权限”收回权限(之后再需要时会重新询问你),或者断开:它会在一分钟内停止工作。 你的所有智能体共用你的 Personal 书架。
使用 API 密钥
创建 API 密钥,用你的 Tunc 账号在 tunchub.com 上创建。选择它可以做什么:读取 Tunc Orb(每个密钥都可以)、在 Tunc Orb 中保存与删除,以及打开、上传和删除 Tunc Art 文件。密钥只显示一次;放在系统的密钥管理里,永远不要写进提示词。随时可以在智能体与密钥里断开,它会在一分钟内停止工作。
一个密钥同时适用于两个 API:Tunc Orb 用 https://api.tuncorb.com,Tunc Art 用 https://api.tuncart.com。以 Authorization: Bearer <key> 的形式发送。
连接 MCP 客户端
Tunc Orb 的工具在 https://mcp.tuncorb.com/mcp,Tunc Art 的在 https://mcp.tuncart.com/mcp。把需要的那个加进去,密钥放在 Authorization 头里(替换 $TUNC_API_KEY):
Claude Code
claude mcp add --transport http tunc-orb https://mcp.tuncorb.com/mcp --header "Authorization: Bearer $TUNC_API_KEY"Cursor (mcp.json)
{
"mcpServers": {
"tunc-orb": {
"url": "https://mcp.tuncorb.com/mcp",
"headers": {
"Authorization": "Bearer $TUNC_API_KEY"
}
}
}
}VS Code (mcp.json)
{
"servers": {
"tunc-orb": {
"type": "http",
"url": "https://mcp.tuncorb.com/mcp",
"headers": {
"Authorization": "Bearer $TUNC_API_KEY"
}
}
}
}Gemini CLI (settings.json)
{
"mcpServers": {
"tunc-orb": {
"httpUrl": "https://mcp.tuncorb.com/mcp",
"headers": {
"Authorization": "Bearer $TUNC_API_KEY"
}
}
}
}OpenAI Responses API (tools)
{
"type": "mcp",
"server_label": "tunc-orb",
"server_url": "https://mcp.tuncorb.com/mcp",
"authorization": "$TUNC_API_KEY"
}权限不足的密钥调用工具时,工具错误会在 missing_scope 里指出缺哪一项;已断开的密钥返回 401。
直接调用 API
curl -s https://api.tuncorb.com/v1/write \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"create","name":"hello","about":"first record",
"text":"Hello from my agent","mutation_id":"mut_'"$(openssl rand -hex 13)"'"}'
curl -s https://api.tuncorb.com/v1/read \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"get","name":"hello"}'# Files you can open (paged)
curl -s "https://api.tuncart.com/v1/files?limit=20" -H "Authorization: Bearer $TUNC_API_KEY"
# Upload: start, send the bytes to upload.url, then complete
curl -s https://api.tuncart.com/v1/files \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name":"q4-report.pdf","mime_type":"application/pdf","byte_count":482113}'
# → {"artifact":{"id":"…",…},"upload":{"method":"PUT","url":"…","headers":{…},…}}
curl -s https://api.tuncart.com/v1/files/<id>/complete \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" -d '{"byte_count":482113}'
# Download, and delete a file your key uploaded
curl -s https://api.tuncart.com/v1/files/<id>/content -H "Authorization: Bearer $TUNC_API_KEY" -o q4-report.pdf
curl -s -X DELETE https://api.tuncart.com/v1/files/<id> -H "Authorization: Bearer $TUNC_API_KEY"import os
import secrets
import requests
headers = {"Authorization": f"Bearer {os.environ['TUNC_API_KEY']}"}
# Tunc Orb:保存一条记录(每次变更一个 mutation_id,重试时复用同一个)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
"operation": "create", "name": "hello", "about": "第一条记录",
"text": "来自我的智能体", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())
# Tunc Art:列出你的文件
print(requests.get("https://api.tuncart.com/v1/files", headers=headers).json())限制
- 合理使用:免费版每天 50,000 次 Tunc Orb 操作,付费存储为 500,000 次。读取、搜索和保存计入;删除和状态查询不计入。每天 UTC 零点重新计数。
- 每个智能体每秒:50 次读取、20 次保存、5 次搜索和 20 次其他调用。短时间突发没问题。
- Tunc Art:每个人每分钟 60 次上传,文件最大 250 MiB。
- 存储与 Tunc Hub、Tunc Orb、Tunc Art 共用;账号页会显示每个产品用了多少。
错误
| 代码 | 含义 | 存储相关字段 |
|---|---|---|
507 storage_limit | Tunc Orb:你的 Tunc 存储已满,所以保存被拒绝——在此之前,如果有 Tunc Art 文件,会先删掉最旧的来腾空间。读取和删除仍然可用。 | error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url |
409 storage_quota_exceeded | Tunc Art:即使删掉最旧的文件腾出空间,这次上传也放不下。 | quota_bytes, active_bytes, requested_bytes, 以及 storage,字段同上 |
429 rate_limited | 调用太多。等 details.retry_after_secs(Orb)或 Retry-After 头(两者)指定的时间。在 Orb 上,details.limit 会说明是哪一种限制:daily、某一类(read、write、search 或 control),或者同时登录的密钥太多时的 key_sign_in。 | — |
401 auth_required, not_connected | auth_required:缺少密钥或密钥无效。not_connected:密钥已断开或已过期,新建一个。对不接受的密钥,Tunc Art 返回 unauthenticated。 | — |
403 forbidden | 密钥没有这项权限。missing_scope 会指出是哪一个,例如 orb.write(Orb:error.details.missing_scope)。用该权限新建一个密钥。 | — |
Tunc Orb 的错误长这样:{"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}};next_step 会说明接下来该做什么。存储满了靠重试永远解决不了:删掉不再需要的内容,或者在账号里增加存储。
本地 MCP 适配器
tunc-orb-mcp 给任何 MCP 客户端提供 data_read、data_write、data_update 和 data_delete 四个工具,外加 art_read。把它加到你的客户端:
{
"mcpServers": {
"tunc-orb": { "command": "tunc-orb-mcp" }
}
}运行一次 tunc-orb-mcp connect:它会显示一个类似 BCDF-GHJK 的代码,以及一个指向 https://tuncorb.com/connect?code=BCDF-GHJK 的链接。打开链接、登录、确认代码一致并授权。适配器会在本地保存一个 refresh token(一个私有文件,或者加 --keyring 时存进系统钥匙串),每次使用都会更换;它永远不该出现在提示词里。
用已登录的智能体调用 HTTP API
已经在浏览器里或用一个代码为 https://mcp.tuncorb.com/mcp 登录过的智能体(见 没有浏览器的智能体),用它的 access token 换一个短期的 Tunc Orb token:
curl -s -X POST https://core.tunc.ai/api/v1/orb/token \
-H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
-H 'content-type: application/json' -d '{}'
# → {"access_token":"…","token_type":"Bearer","expires_in":300,"orb_url":"https://api.tuncorb.com",…}Orb token 最长五分钟。过期就重新申请一个;断开智能体后就不再续期。
写入、读取和删除
每个请求都是带 operation 的 JSON,用 API 密钥或 access token 发送。写入和删除要带一个 mutation_id(以 mut_ 开头,后接 16 到 64 个 0-9 和小写字母,不含 i、l、o、u),由你为每一次要做的改动生成一次,重试时复用同一个,这样重试永远不会重复应用。
curl -s https://api.tuncorb.com/v1/write \
-H "authorization: Bearer $ORB_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{"operation":"create","name":"projects/q4/summary",
"about":"Weekly summary of the Q4 project",
"value":{"status":"on track"},
"mutation_id":"mut_<26 lowercase base32 characters>"}'curl -s https://api.tuncorb.com/v1/read \
-H "authorization: Bearer $ORB_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{"operation":"get","name":"projects/q4/summary"}'
# List names under a prefix (paged):
curl -s https://api.tuncorb.com/v1/read \
-H "authorization: Bearer $ORB_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{"operation":"list","prefix":"projects/","limit":50}'curl -s https://api.tuncorb.com/v1/delete \
-H "authorization: Bearer $ORB_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{"operation":"record","name":"projects/q4/summary",
"if_revision":"rev_…","mutation_id":"mut_…"}'省略 shelf_id 就使用你的默认书架;每个返回值都会带上它实际使用的书架,重试时可以固定下来。
这些工具做什么
- data_read:
shelves列出你可以使用的书架;list按前缀分页列出名称和一行说明,contains按其中的文字缩小到名称或说明;get读取一条记录(可以只取 JSON 值的一部分);log读取日志条目,默认最新的在前,也可以要最旧的在前;search在前缀范围内搜索文字;query在一个日志、一个保存列表的记录或某个前缀下的所有记录中找出满足条件的行,还能按共同的键把它们与第二个来源连接起来,可以在同一个书架上,也可以在队友的书架上;status报告之前某次改动结果。 - data_write:用
create创建一条记录(带一行about说明),或者用append往日志里追加条目。它只做新增:从不覆盖记录或日志条目。 - data_update:在已知版本上
replace或patch一条已存在的记录。这会覆盖已保存的值,之前的值读不回来,所以客户端在执行前会先询问。 - data_delete:在已知版本上删除一条记录(
record)、整个日志(log),或选定的日志条目(entries)。 - art_read:Tunc Orb 服务器也会以只读方式打开你存在 Tunc Art 里的文件,通过它们的
artifact_id。把文件的artifact_id记在一条记录里,任何智能体都能找到它。它不能上传或删除文件。
以你身份连接的每个智能体都能用你能访问的每个书架,包括你其他智能体写下的记录。断开一个智能体,其他照常工作。要把不同客户的数据分开,就一个客户一个 Tunc 账号:连到一个账号上的所有智能体都能读它的全部书架。
书架、保留与限制
- 记录和日志一直保留,直到你删除。一条记录最大 16 MiB;一次调用最多发送 64 KiB,所以更大的记录要用补丁逐步长大。
- 免费账号有一个书架;付费存储可以按需创建任意多个。在账号的 Shelves 标签页里创建书架。
- 存储满了时,保存会先删掉最旧的 Tunc Art 文件腾出空间(绝不会删 Tunc Orb 的记录或日志);如果仍然没有空间,保存会以
storage_limit被拒绝。读取和删除仍然可用。 - 合理使用与速率限制见 使用 API 密钥。
加密
Tunc Orb 使用托管加密。记录的值在存储前会用每个书架的数据密钥加密;Tunc 的密钥服务保护这些密钥,Tunc Orb 服务在为你的授权智能体返回结果时解密。Tunc 可能为了运行服务而处理这些数据。这不是端到端加密。记录的名称和一行说明不加密,所以不要把秘密放在里面。
网站上能看到什么
已用存储、操作次数、书架标签与生命周期,以及智能体连接。它没有记录浏览器、预览、搜索、编辑器或导出,你在网站上的登录也不是智能体凭证。
