TUNC.AI / Документація Tunc Orb

Підключіть агента до Tunc Orb

Агенти працюють із Tunc Orb через MCP, A2A або HTTP API: вони входять через Tunc, підключаються за кодом або використовують API-ключ. Ваш акаунт Tunc керує агентами, ключами й сховищем; він ніколи не читає й не показує, що зберігають ваші агенти.

У Tunc Hub Orb уже вбудований; дізнайтеся, як це працює. Потрібні готові налаштування? Приклади містять підказки, які ви вставляєте своєму агентові.

Вхід через Tunc

MCP-клієнти, що підтримують вхід, підключаються до https://mcp.tuncorb.com/mcp через ваш акаунт Tunc: копіювати ключ не потрібно. (Інший продукт доступний на 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)Command Palette → 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. Відкрийте його, увійдіть, переконайтеся, що код збігається, і дозвольте доступ. Це вміє будь-яка бібліотека OAuth, що підтримує device grant (RFC 8628):

# Один раз для кожного агента: зареєструйте його (переспрямування не потрібне)
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":"…"}

# Перш ніж токен доступу спливе, обміняйте токен оновлення на нові
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…

Надсилайте токен доступу як Authorization: Bearer до https://mcp.tuncorb.com/mcp. Кожне оновлення повертає новий токен оновлення: зберігайте лише найновіший, бо повторне надсилання вже використаного відключає агента.

A2A

Агенти, що підтримують A2A 1.0, знаходять Tunc Orb за адресою https://tuncorb.com/.well-known/agent-card.json і викликають https://a2a.tuncorb.com. Кожне повідомлення містить одну частину data з 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 → Agents & keys, разом із тим, як він підключився і що йому дозволено. Перейменуйте його, скористайтеся Change access, щоб забрати доступ (за більшим агент знову звернеться до вас), або Disconnect: він перестане працювати протягом хвилини. Усі ваші агенти користуються вашою полицею Personal.

Використання API-ключа

Створіть API-ключ на tunchub.com через свій акаунт Tunc. Виберіть, що йому дозволено: читати Tunc Orb (кожен ключ), зберігати й видаляти в Tunc Orb, а також відкривати, завантажувати й видаляти файли Tunc Art. Ключ показується один раз; зберігайте його в сховищі секретів своєї системи, ніколи в підказці. Відключити його можна будь-коли в розділі Agents & keys, і він перестане працювати протягом хвилини.

Один ключ працює з обома API: https://api.tuncorb.com для Tunc Orb і https://api.tuncart.com для Tunc Art. Надсилайте його як 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. Відкрийте посилання, увійдіть, переконайтеся, що код збігається, і дозвольте доступ. Адаптер зберігає токен оновлення локально (у приватному файлі або, з --keyring, у сховищі ключів ОС) і замінює його під час кожного використання; йому ніколи не місце в підказці.

HTTP API з агентом, який увійшов

Агент, який увійшов до https://mcp.tuncorb.com/mcp у браузері або за кодом (див. Агенти без браузера), обмінює свій токен доступу на короткочасний токен Tunc Orb:

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 діють щонайбільше пʼять хвилин. Коли токен спливе, запитайте новий; відключення агента зупиняє оновлення.

Запис, читання й видалення

Кожен запит — це JSON із полем operation, що надсилається з API-ключем або токеном доступу. Записи й видалення містять 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 МіБ; один виклик надсилає щонайбільше 64 КіБ, тож більший запис нарощуйте патчами.
  • Безкоштовний акаунт має одну полицю; платне сховище дає стільки полиць, скільки потрібно. Полиці створюються на вкладці Shelves вашого акаунта.
  • Коли сховище заповнене, збереження спершу видаляє ваші найстаріші файли Tunc Art, щоб звільнити місце (ніколи не записи чи журнали Tunc Orb); якщо місця все одно немає, збереження відхиляється з storage_limit. Читання й видалення працюють і далі.
  • Добросовісне використання й обмеження частоти описано в розділі Використання API-ключа.

Шифрування

Tunc Orb використовує кероване шифрування. Значення записів шифруються ключем даних окремої полиці перед збереженням; служба ключів Tunc захищає ці ключі, а служба Tunc Orb розшифровує значення, щоб відповідати вашим авторизованим агентам. Tunc може обробляти дані для роботи сервісу. Це не наскрізне шифрування. Назви записів і однорядкові описи не шифруються, тож не зберігайте в них секретів.

Що показує вебсайт

Використане сховище, кількість операцій, назви полиць і їхній життєвий цикл, а також підключення агентів. У ньому немає перегляду записів, попереднього перегляду, пошуку, редактора чи експорту, а вхід на вебсайт не є обліковими даними агента.