Tunc Orb

npx add-mcp 'https://mcp.tuncorb.com/mcp'

TUNC.AI / Tunc Orb docs

Connect an agent to Tunc Orb

Agents use Tunc Orb over MCP, A2A or the HTTP API: they sign in with Tunc, connect with a code, or use an API key. Your Tunc account manages agents, keys and storage; it never reads or shows what your agents store.

In Tunc Hub, Orb is built in; read how it works. Want working setups? The examples have prompts you paste to your agent.

Sign in with Tunc

MCP clients that sign in connect to https://mcp.tuncorb.com/mcp with your Tunc account: no key to copy. (The other product is at https://mcp.tuncart.com/mcp.) Your client opens Tunc; you sign in, or create a free account with your organization and the Terms, then allow it once and choose what it may do.

Client	Steps
claude.ai, Claude Desktop and Claude mobile	Customize → Connectors → Add custom connector → name Tunc Orb, URL https://mcp.tuncorb.com/mcp → Add → Connect. The Free plan allows one custom connector; on Team and Enterprise an Owner adds it under Organization settings → Connectors. This link opens the dialog with the name and URL filled in: https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Orb&connectorUrl=https%3A%2F%2Fmcp.tuncorb.com%2Fmcp
Claude Code	Add the server, then run /mcp, choose tunc-orb and Authenticate. claude mcp add --transport http tunc-orb https://mcp.tuncorb.com/mcp
ChatGPT	Settings → Apps & Connectors → Advanced → turn on Developer mode → Create → name Tunc Orb, URL https://mcp.tuncorb.com/mcp, Authentication OAuth → Create → Connect.
Cursor	Add it to ~/.cursor/mcp.json, then Settings → MCP: it shows “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 → name tunc-orb → allow the sign-in prompt.
Gemini CLI	Add it to settings.json, then run /mcp auth tunc-orb. { "mcpServers": { "tunc-orb": { "httpUrl": "https://mcp.tuncorb.com/mcp" } } }
Copilot Studio	Tools → Add a tool → New tool → Model Context Protocol → URL https://mcp.tuncorb.com/mcp → Authentication OAuth 2.0, Dynamic discovery.

A client that only takes a header uses an API key instead.

Agents without a browser

An agent on a server or in a terminal shows you a code and a link such as https://tuncorb.com/connect?code=BCDF-GHJK. Open it, sign in, check the code matches and allow it. Any OAuth library that speaks the device grant (RFC 8628) can do this:

# Once per agent: register it (no redirect needed)
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_…",…}

# Ask for a code, and show the person 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}

# Poll every interval seconds until they allow it
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"} until then, once allowed:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}

# Before the access token expires, swap the refresh token for new ones
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…

Send the access token as Authorization: Bearer to https://mcp.tuncorb.com/mcp. Each refresh returns a new refresh token: keep only the newest one, because sending a used one again disconnects the agent.

A2A

Agents that speak A2A 1.0 find Tunc Orb at https://tuncorb.com/.well-known/agent-card.json and call https://a2a.tuncorb.com. Every message carries one data part with a skill (an MCP tool name, such as data_read) and its arguments; the answer is the tool's result. Use an API key, or sign in with the resource 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":{…the tool's result…},"mediaType":"application/json"}],…}}}

Rename, change access or disconnect

Every agent and key is listed on tunchub.com → Agents & keys, with how it connected and what it may do. Rename it, use Change access to take access away (the agent asks you again for more), or Disconnect it: it stops working within a minute. All your agents share your Personal shelf.

Use an API key

Create an API key on tunchub.com with your Tunc account. Choose what it may do: read Tunc Orb (every key), save and delete in Tunc Orb, and open, upload and delete Tunc Art files. The key is shown once; keep it in your system's secret store, never in a prompt. Disconnect it any time from Agents & keys, and it stops working within a minute.

One key works on both APIs: https://api.tuncorb.com for Tunc Orb and https://api.tuncart.com for Tunc Art. Send it as Authorization: Bearer <key>.

Connect an MCP client

Tunc Orb's tools are at https://mcp.tuncorb.com/mcp and Tunc Art's at https://mcp.tuncart.com/mcp. Add the one you need with your key in the Authorization header (replace $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"
}

A key without the access a tool needs gets a tool error naming it in missing_scope; a disconnected key gets 401.

Call the API directly

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: save a record (one mutation_id per change; reuse it on retries)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
    "operation": "create", "name": "hello", "about": "first record",
    "text": "Hello from my agent", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())

# Tunc Art: list your files
print(requests.get("https://api.tuncart.com/v1/files", headers=headers).json())

Limits

• Fair use: 50,000 Tunc Orb operations a day on the free plan, 500,000 with paid storage. Reads, searches and saves count; deletes and status checks do not. The count starts again at midnight UTC.
• Per agent each second: 50 reads, 20 saves, 5 searches and 20 other calls. Short bursts are fine.
• Tunc Art: 60 uploads a minute per person, and files up to 250 MiB.
• Storage is shared with Tunc Hub, Tunc Orb and Tunc Art; your account page shows each product's share.

Errors

Code	Meaning	Storage details
507 storage_limit	Tunc Orb: your Tunc storage is full, so the save was refused, after removing your oldest Tunc Art files to make room if there were any. Reads and deletes still work.	error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceeded	Tunc Art: the upload does not fit, even after removing your oldest files to make room.	quota_bytes, active_bytes, requested_bytes, and storage with the same fields as above
429 rate_limited	Too many calls. Wait details.retry_after_secs (Orb) or the Retry-After header (both). On Orb, details.limit says which limit: daily, a class (read, write, search or control), or key_sign_in when too many keys sign in at once.	—
401 auth_required, not_connected	auth_required: the key is missing or not valid. not_connected: the key was disconnected or expired; create a new one. Tunc Art answers unauthenticated for a key it does not accept.	—
403 forbidden	The key does not have this access. missing_scope names it, for example orb.write (Orb: error.details.missing_scope). Create a key with that access.	—

Tunc Orb errors look like {"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}}; next_step says what to do. A full storage is never fixed by retrying: delete what you no longer need, or add storage in your account.

The local MCP adapter

tunc-orb-mcp gives any MCP client the data_read, data_write and data_delete tools. Add it to your client:

{
  "mcpServers": {
    "tunc-orb": { "command": "tunc-orb-mcp" }
  }
}

Run tunc-orb-mcp connect once: it shows a code such as BCDF-GHJK with a link to https://tuncorb.com/connect?code=BCDF-GHJK. Open the link, sign in, check that the code matches and allow it. The adapter keeps a refresh token locally (a private file, or the OS keychain with --keyring) and replaces it on every use; it never belongs in a prompt.

The HTTP API with a signed-in agent

An agent that signed in for https://mcp.tuncorb.com/mcp, in a browser or with a code (see Agents without a browser), trades its access token for a short-lived 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 tokens last at most five minutes. Request a new one when it expires; disconnecting the agent stops renewal.

Write, read and delete

Every request is JSON with an operation, sent with an API key or an access token. Writes and deletes carry a mutation_id (mut_ and 16 to 64 characters of 0-9 and lowercase letters except i, l, o and u) you generate once per intended change and reuse on retries, so a retry never applies twice.

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_…"}'

Omit shelf_id to use your default shelf; every result echoes the shelf it used so retries can pin it.

What the tools do

• data_read: shelves lists shelves you can use; list pages names and one-line descriptions under a prefix, and contains narrows it to names or descriptions with that text; get reads a record (optionally parts of a JSON value); log reads log entries, newest first unless you ask for oldest first; search finds text within a prefix; status reports the outcome of an earlier change.
• data_write: create a record with an about line describing it, or append entries to a log. It only adds: it never overwrites a record or a log entry.
• data_update: replace or patch a record that exists, at a known revision. This overwrites the saved value and the previous value cannot be read back, so clients ask before running it.
• data_delete: delete a record, a whole log, or selected log entries, at a known revision.
• art_read: the Tunc Orb server also opens files you saved in Tunc Art, read-only, by their artifact_id. Keep a file's artifact_id in a record and any agent can find it. It cannot upload or delete files.

Every agent connected as you can use every shelf you can access, including records written by your other agents. Disconnecting one agent leaves the others working. To keep clients apart, use one Tunc account per client: every agent connected to an account can read all of its shelves.

Shelves, retention and limits

• Records and logs are kept until you delete them. A record holds up to 16 MiB; one call sends at most 64 KiB, so grow a larger record with patches.
• A free account has one shelf; paid storage allows as many as you need. Create shelves in your account's Shelves tab.
• When storage is full, a save first removes your oldest Tunc Art files to make room (never Tunc Orb records or logs); if there is still no room the save is refused with storage_limit. Reads and deletes still work.
• Fair-use and rate limits are under Use an API key.

Encryption

Tunc Orb uses managed encryption. Record values are encrypted with a per-shelf data key before they are stored; Tunc's key service protects those keys, and the Tunc Orb service decrypts values to answer your authorized agents. Tunc may process the data to run the service. This is not end-to-end encryption. Record names and one-line descriptions are not encrypted, so keep secrets out of them.

What the website shows

Storage used, operation counts, shelf labels and lifecycle, and agent connections. It has no record browser, preview, search, editor or export, and your website sign-in is not an agent credential.