TUNC.AI / Documentación de Tunc Orb

Conecta un agente a Tunc Orb

Los agentes usan Tunc Orb por MCP, A2A o la HTTP API: inician sesión con Tunc, se conectan con un código o usan una clave de API. Tu cuenta de Tunc administra agentes, claves y almacenamiento; nunca lee ni muestra lo que guardan tus agentes.

En Tunc Hub, Orb viene integrado; lee cómo funciona. ¿Quieres configuraciones que ya funcionan? Los ejemplos tienen prompts que pegas en tu agente.

Iniciar sesión con Tunc

Los clientes MCP que inician sesión se conectan a https://mcp.tuncorb.com/mcp con tu cuenta de Tunc: no hay que copiar ninguna clave. (El otro producto está en https://mcp.tuncart.com/mcp.) Tu cliente abre Tunc; inicias sesión, o creas una cuenta gratuita con tu organización y aceptas los Términos, luego lo autorizas una vez y eliges lo que puede hacer.

ClientePasos
claude.ai, Claude Desktop and Claude mobileCustomize → Connectors → Add custom connector → nombre Tunc Orb, URL https://mcp.tuncorb.com/mcp → Add → Connect. El plan Free permite un conector personalizado; en Team y Enterprise, un Owner lo agrega en Organization settings → Connectors. Este enlace abre el diálogo con el nombre y la URL ya completados:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Orb&connectorUrl=https%3A%2F%2Fmcp.tuncorb.com%2Fmcp
Claude CodeAgrega el servidor, luego ejecuta /mcp, elige tunc-orb y Authenticate.
claude mcp add --transport http tunc-orb https://mcp.tuncorb.com/mcp
ChatGPTSettings → Apps & Connectors → Advanced → activa Developer mode → Create → nombre Tunc Orb, URL https://mcp.tuncorb.com/mcp, Authentication OAuth → Create → Connect.
CursorAgrégalo a ~/.cursor/mcp.json y luego ve a Settings → MCP: muestra “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 → nombre tunc-orb → permite la solicitud de inicio de sesión.
Gemini CLIAgrégalo a settings.json y luego ejecuta /mcp auth tunc-orb.
{
  "mcpServers": {
    "tunc-orb": {
      "httpUrl": "https://mcp.tuncorb.com/mcp"
    }
  }
}
Copilot StudioTools → Add a tool → New tool → Model Context Protocol → en URL escribe https://mcp.tuncorb.com/mcp → en Authentication elige OAuth 2.0, Dynamic discovery.

Un cliente que solo acepta un encabezado usa en su lugar una clave de API.

Agentes sin navegador

Un agente en un servidor o en una terminal te muestra un código y un enlace como https://tuncorb.com/connect?code=BCDF-GHJK. Ábrelo, inicia sesión, comprueba que el código coincida y autorízalo. Cualquier biblioteca de OAuth que admita el device grant (RFC 8628) puede hacerlo:

# Una vez por agente: regístralo (no necesita redirección)
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_…",…}

# Pide un código y muéstrale a la persona 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}

# Consulta cada interval segundos hasta que lo autorice
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"} hasta entonces; una vez autorizado:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}

# Antes de que venza el token de acceso, cambia el token de actualización por otros nuevos
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…

Envía el token de acceso como Authorization: Bearer a https://mcp.tuncorb.com/mcp. Cada renovación devuelve un nuevo token de actualización: conserva solo el más reciente, porque volver a enviar uno ya usado desconecta al agente.

A2A

Los agentes que hablan A2A 1.0 encuentran Tunc Orb en https://tuncorb.com/.well-known/agent-card.json e invocan https://a2a.tuncorb.com. Cada mensaje lleva una parte de datos con un skill (el nombre de una herramienta MCP, como data_read) y sus arguments; la respuesta es el resultado de la herramienta. Usa una clave de API, o inicia sesión con el recurso 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":{…el resultado de la herramienta…},"mediaType":"application/json"}],…}}}

Cambiar el nombre, cambiar el acceso o desconectar

Cada agente y cada clave aparecen en tunchub.com → Agents & keys, con la forma en que se conectó y lo que puede hacer. Cámbiale el nombre, usa Change access para quitarle acceso (el agente te pedirá más si lo necesita) o desconéctalo con Disconnect: deja de funcionar en menos de un minuto. Todos tus agentes comparten tu estante Personal.

Usar una clave de API

Crea una clave de API en tunchub.com con tu cuenta de Tunc. Elige lo que puede hacer: leer Tunc Orb (todas las claves), guardar y eliminar en Tunc Orb, y abrir, subir y eliminar archivos de Tunc Art. La clave se muestra una sola vez; guárdala en el almacén de secretos de tu sistema, nunca en un prompt. Desconéctala cuando quieras desde Agents & keys, y deja de funcionar en menos de un minuto.

Una misma clave funciona en ambas API: https://api.tuncorb.com para Tunc Orb y https://api.tuncart.com para Tunc Art. Envíala como Authorization: Bearer <key>.

Conecta un cliente MCP

Las herramientas de Tunc Orb están en https://mcp.tuncorb.com/mcp y las de Tunc Art en https://mcp.tuncart.com/mcp. Agrega la que necesites con tu clave en el encabezado Authorization (reemplaza $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"
}

Una clave sin el acceso que necesita una herramienta recibe un error de herramienta que lo nombra en missing_scope; una clave desconectada recibe 401.

Llama a la API directamente

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: guardar un registro (un mutation_id por cambio; reutilízalo en los reintentos)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
    "operation": "create", "name": "hello", "about": "primer registro",
    "text": "Hola desde mi agente", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())

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

Límites

  • Uso razonable: 50,000 operaciones de Tunc Orb al día en el plan gratuito, 500,000 con almacenamiento de pago. Las lecturas, búsquedas y guardados cuentan; las eliminaciones y las consultas de estado no. El conteo se reinicia a la medianoche UTC.
  • Por agente, cada segundo: 50 lecturas, 20 guardados, 5 búsquedas y 20 llamadas de otro tipo. Las ráfagas cortas no son problema.
  • Tunc Art: 60 cargas por minuto por persona, y archivos de hasta 250 MiB.
  • El almacenamiento se comparte con Tunc Hub, Tunc Orb y Tunc Art; la página de tu cuenta muestra la parte de cada producto.

Errores

CódigoSignificadoDetalles del almacenamiento
507 storage_limitTunc Orb: tu almacenamiento de Tunc está lleno, así que el guardado se rechazó, después de eliminar tus archivos más antiguos de Tunc Art para hacer espacio, si había alguno. Las lecturas y eliminaciones siguen funcionando.error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceededTunc Art: la carga no cabe, ni siquiera después de eliminar tus archivos más antiguos para hacer espacio.quota_bytes, active_bytes, requested_bytes, y storage con los mismos campos que arriba
429 rate_limitedDemasiadas llamadas. Espera details.retry_after_secs (Orb) o el encabezado Retry-After (ambos). En Orb, details.limit indica qué límite: daily, una clase (read, write, search o control), o key_sign_in cuando demasiadas claves inician sesión a la vez.—
401 auth_required, not_connectedauth_required: falta la clave o no es válida. not_connected: la clave se desconectó o venció; crea una nueva. Tunc Art responde unauthenticated a una clave que no acepta.—
403 forbiddenLa clave no tiene este acceso. missing_scope lo nombra, por ejemplo orb.write (Orb: error.details.missing_scope). Crea una clave con ese acceso.—

Los errores de Tunc Orb tienen esta forma: {"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}}; next_step indica qué hacer. Un almacenamiento lleno nunca se arregla reintentando: elimina lo que ya no necesites o agrega almacenamiento en tu cuenta.

El adaptador MCP local

tunc-orb-mcp le da a cualquier cliente MCP las herramientas data_read, data_write, data_update y data_delete, además de art_read. Agrégalo a tu cliente:

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

Ejecuta tunc-orb-mcp connect una vez: muestra un código como BCDF-GHJK con un enlace a https://tuncorb.com/connect?code=BCDF-GHJK. Abre el enlace, inicia sesión, comprueba que el código coincida y autorízalo. El adaptador guarda un token de actualización localmente (en un archivo privado, o en el llavero del sistema operativo con --keyring) y lo reemplaza en cada uso; nunca debe ir en un prompt.

La HTTP API con un agente que inició sesión

Un agente que inició sesión para https://mcp.tuncorb.com/mcp, en un navegador o con un código (consulta Agentes sin navegador), cambia su token de acceso por un token de Tunc Orb de corta duración:

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",…}

Los tokens de Orb duran como máximo cinco minutos. Pide uno nuevo cuando venza; al desconectar el agente se detiene la renovación.

Escribir, leer y eliminar

Cada solicitud es un JSON con un campo operation, enviado con una clave de API o un token de acceso. Las escrituras y eliminaciones llevan un mutation_id (mut_ seguido de 16 a 64 caracteres entre 0-9 y letras minúsculas, excepto i, l, o y u) que generas una vez por cada cambio previsto y reutilizas en los reintentos, así un reintento nunca se aplica dos veces.

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

Omite shelf_id para usar tu estante predeterminado; cada resultado indica el estante que usó, para que los reintentos puedan fijarlo.

Qué hacen las herramientas

  • data_read: shelves lista los estantes que puedes usar; list pagina los nombres y las descripciones de una línea bajo un prefijo, y contains lo reduce a los nombres o descripciones que contienen ese texto; get lee un registro (opcionalmente, partes de un valor JSON); log lee entradas de bitácora, las más recientes primero, a menos que pidas las más antiguas primero; search busca texto dentro de un prefijo; query encuentra las filas que cumplen condiciones en una bitácora, en un registro que guarda una lista o en los registros bajo un prefijo, y puede unirlas con una segunda fuente por una clave común, en el mismo estante o en el de un compañero de equipo; status informa el resultado de un cambio anterior.
  • data_write: create crea un registro con una línea about que lo describe, o append agrega entradas a una bitácora. Solo agrega: nunca sobrescribe un registro ni una entrada de bitácora.
  • data_update: replace o patch modifican un registro existente, en una revisión conocida. Esto sobrescribe el valor guardado y el valor anterior ya no se puede leer, así que los clientes preguntan antes de ejecutarlo.
  • data_delete: elimina un registro (record), una bitácora completa (log) o entradas seleccionadas de una bitácora (entries), en una revisión conocida.
  • art_read: el servidor de Tunc Orb también abre, en modo de solo lectura, los archivos que guardaste en Tunc Art, por su artifact_id. Guarda el artifact_id de un archivo en un registro y cualquier agente podrá encontrarlo. No puede subir ni eliminar archivos.

Cada agente conectado en tu nombre puede usar todos los estantes a los que tienes acceso, incluidos los registros que escribieron tus otros agentes. Desconectar un agente no afecta a los demás. Para mantener separados a tus clientes, usa una cuenta de Tunc por cliente: cada agente conectado a una cuenta puede leer todos sus estantes.

Estantes, conservación y límites

  • Los registros y las bitácoras se conservan hasta que los eliminas. Un registro admite hasta 16 MiB; una llamada envía como máximo 64 KiB, así que haz crecer un registro más grande con parches.
  • Una cuenta gratuita tiene un estante; el almacenamiento de pago permite todos los que necesites. Crea estantes en la pestaña Shelves de tu cuenta.
  • Cuando el almacenamiento está lleno, un guardado primero elimina tus archivos más antiguos de Tunc Art para hacer espacio (nunca registros ni bitácoras de Tunc Orb); si aun así no hay espacio, el guardado se rechaza con storage_limit. Las lecturas y eliminaciones siguen funcionando.
  • El uso razonable y los límites de frecuencia se explican en Usar una clave de API.

Cifrado

Tunc Orb usa cifrado administrado. Los valores de los registros se cifran con una clave de datos propia de cada estante antes de almacenarse; el servicio de claves de Tunc protege esas claves, y el servicio de Tunc Orb descifra los valores para responder a tus agentes autorizados. Tunc puede procesar los datos para operar el servicio. Esto no es cifrado de extremo a extremo. Los nombres de los registros y las descripciones de una línea no se cifran, así que no pongas secretos en ellos.

Qué muestra el sitio web

El almacenamiento usado, el número de operaciones, las etiquetas y el ciclo de vida de los estantes, y las conexiones de agentes. No tiene explorador de registros, vista previa, búsqueda, editor ni exportación, y tu inicio de sesión en el sitio web no es una credencial de agente.