TUNC.AI / Tunc Orb 文档

把一个智能体接到 Tunc Orb

智能体通过 MCP、A2A 或 HTTP API 使用 Tunc Orb:用 Tunc 登录、用代码连接,或者用 API 密钥。你的 Tunc 账号管理智能体、密钥和存储;它从不读取、也不会显示你的智能体存了什么。

在 Tunc Hub 里,Orb 是内置的;看看它是怎么工作的。想要能直接用的搭法?示例里有可以贴给智能体的提示词。

用 Tunc 账号登录

支持登录的 MCP 客户端用你的 Tunc 账号连接 https://mcp.tuncorb.com/mcp:不需要复制任何密钥。 另一个产品的地址是 https://mcp.tuncart.com/mcp。 你的客户端会打开 Tunc;你登录,或者用组织与条款创建一个免费账号,然后授权一次并选择它可以使用什么。

客户端步骤
claude.ai, Claude Desktop and Claude mobileCustomize → Connectors → Add custom connector → 名称填 Tunc Orb,URL 填 https://mcp.tuncorb.com/mcp → Add → Connect。免费版只允许一个自定义连接器;Team 和 Enterprise 由 Owner 在 Organization settings → Connectors 里添加。这个链接会打开对话框,名称和 URL 已经填好:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Orb&connectorUrl=https%3A%2F%2Fmcp.tuncorb.com%2Fmcp
Claude Code先添加服务器,然后运行 /mcp,选择 tunc-orb,再 Authenticate。
claude mcp add --transport http tunc-orb https://mcp.tuncorb.com/mcp
ChatGPTSettings → 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。
{
  "mcpServers": {
    "tunc-orb": {
      "url": "https://mcp.tuncorb.com/mcp"
    }
  }
}
VS Code (Copilot)命令面板 → MCP: Add Server → HTTP → https://mcp.tuncorb.com/mcp → 名称 tunc-orb → 允许登录提示。
Gemini CLI加到 settings.json,然后运行 /mcp auth tunc-orb。
{
  "mcpServers": {
    "tunc-orb": {
      "httpUrl": "https://mcp.tuncorb.com/mcp"
    }
  }
}
Copilot StudioTools → 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_limitTunc Orb:你的 Tunc 存储已满,所以保存被拒绝——在此之前,如果有 Tunc Art 文件,会先删掉最旧的来腾空间。读取和删除仍然可用。error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceededTunc 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_connectedauth_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 可能为了运行服务而处理这些数据。这不是端到端加密。记录的名称和一行说明不加密,所以不要把秘密放在里面。

网站上能看到什么

已用存储、操作次数、书架标签与生命周期,以及智能体连接。它没有记录浏览器、预览、搜索、编辑器或导出,你在网站上的登录也不是智能体凭证。