TUNC.AI / Documentação do Tunc Orb

Ligar um agente ao Tunc Orb

Os agentes usam o Tunc Orb por MCP, A2A ou pela API HTTP: iniciam sessão com o Tunc, ligam-se com um código ou usam uma chave de API. A tua conta Tunc gere agentes, chaves e armazenamento; nunca lê nem mostra o que os teus agentes guardam.

No Tunc Hub, o Orb já vem integrado; vê como funciona. Queres configurações prontas? Os exemplos trazem prompts para colares no teu agente.

Iniciar sessão com o Tunc

Os clientes MCP que iniciam sessão ligam-se a https://mcp.tuncorb.com/mcp com a tua conta Tunc: nenhuma chave para copiar. (O outro produto fica em https://mcp.tuncart.com/mcp.) O teu cliente abre o Tunc; inicias sessão, ou crias uma conta gratuita indicando a tua organização e aceitando os Termos, depois autorizas uma vez e escolhes o que ele pode fazer.

ClientePassos
claude.ai, Claude Desktop and Claude mobileCustomize → Connectors → Add custom connector → nome Tunc Orb, URL https://mcp.tuncorb.com/mcp → Add → Connect. O plano Free permite um conector personalizado; nos planos Team e Enterprise, é um Owner que o adiciona em Organization settings → Connectors. Esta ligação abre a caixa de diálogo com o nome e o URL já preenchidos:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Orb&connectorUrl=https%3A%2F%2Fmcp.tuncorb.com%2Fmcp
Claude CodeAdiciona o servidor, depois executa /mcp, escolhe tunc-orb e Authenticate.
claude mcp add --transport http tunc-orb https://mcp.tuncorb.com/mcp
ChatGPTSettings → Apps & Connectors → Advanced → ativa o Developer mode → Create → nome Tunc Orb, URL https://mcp.tuncorb.com/mcp, Authentication OAuth → Create → Connect.
CursorAdiciona-o ao ~/.cursor/mcp.json e depois vai a Settings → MCP: aparece “Needs login” → Login.
{
  "mcpServers": {
    "tunc-orb": {
      "url": "https://mcp.tuncorb.com/mcp"
    }
  }
}
VS Code (Copilot)Paleta de Comandos → MCP: Add Server → HTTP → https://mcp.tuncorb.com/mcp → nome tunc-orb → aceita o pedido de início de sessão.
Gemini CLIAdiciona-o ao settings.json e depois executa /mcp auth tunc-orb.
{
  "mcpServers": {
    "tunc-orb": {
      "httpUrl": "https://mcp.tuncorb.com/mcp"
    }
  }
}
Copilot StudioTools → Add a tool → New tool → Model Context Protocol → em URL, indica https://mcp.tuncorb.com/mcp → em Authentication, escolhe OAuth 2.0, Dynamic discovery.

Um cliente que só aceita um cabeçalho usa uma chave de API em vez disso.

Agentes sem navegador

Um agente num servidor ou num terminal mostra-te um código e uma ligação, como https://tuncorb.com/connect?code=BCDF-GHJK. Abre-a, inicia sessão, confirma que o código é o mesmo e autoriza. Qualquer biblioteca OAuth que implemente o device grant (RFC 8628) consegue fazê-lo:

# Uma vez por agente: regista-o (não precisa de redirecionamento)
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_…",…}

# Pede um código e mostra à pessoa o 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 a cada interval segundos até a pessoa autorizar
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"} até lá; depois de autorizado:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}

# Antes de o token de acesso expirar, troca o refresh token por novos tokens
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…

Envia o token de acesso como Authorization: Bearer para https://mcp.tuncorb.com/mcp. Cada renovação devolve um novo refresh token: guarda só o mais recente, porque voltar a enviar um que já foi usado desliga o agente.

A2A

Agentes que falam A2A 1.0 encontram Tunc Orb em https://tuncorb.com/.well-known/agent-card.json e chamam https://a2a.tuncorb.com. Cada mensagem leva uma parte de dados com um skill (o nome de uma ferramenta MCP, como data_read) e os arguments dela; a resposta é o resultado da ferramenta. Usa uma chave de API ou inicia sessão com o 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":{…o resultado da ferramenta…},"mediaType":"application/json"}],…}}}

Mudar o nome, alterar o acesso ou desligar

Todos os agentes e chaves aparecem em tunchub.com → Agents & keys, com a forma como se ligaram e o que podem fazer. Muda o nome, usa Change access para retirar acesso (o agente volta a pedir-te se precisar de mais) ou Disconnect: deixa de funcionar em menos de um minuto. Todos os teus agentes partilham a tua prateleira Personal.

Usar uma chave de API

Cria uma chave de API no tunchub.com com a tua conta Tunc. Escolhe o que pode fazer: ler o Tunc Orb (qualquer chave pode), guardar e eliminar no Tunc Orb, e abrir, carregar e eliminar ficheiros do Tunc Art. A chave é mostrada uma única vez; guarda-a no cofre de segredos do teu sistema, nunca num prompt. Desliga-a quando quiseres em Agents & keys, e deixa de funcionar em menos de um minuto.

Uma chave funciona nas duas APIs: https://api.tuncorb.com para o Tunc Orb e https://api.tuncart.com para o Tunc Art. Envia-a como Authorization: Bearer <key>.

Liga um cliente MCP

As ferramentas do Tunc Orb ficam em https://mcp.tuncorb.com/mcp e as do Tunc Art em https://mcp.tuncart.com/mcp. Adiciona o de que precisas com a tua chave no cabeçalho Authorization (substitui $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"
}

Uma chave sem o acesso de que uma ferramenta precisa recebe um erro de ferramenta que o indica em missing_scope; uma chave desligada recebe 401.

Chama a API diretamente

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 um registo (um mutation_id por alteração; reutiliza-o nas novas tentativas)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
    "operation": "create", "name": "hello", "about": "primeiro registo",
    "text": "Olá do meu agente", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())

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

Limites

  • Utilização justa: 50,000 operações do Tunc Orb por dia no plano gratuito, 500,000 com armazenamento pago. As leituras, pesquisas e gravações contam; as eliminações e verificações de estado não. A contagem recomeça à meia-noite UTC.
  • Por agente, a cada segundo: 50 leituras, 20 gravações, 5 pesquisas e 20 outras chamadas. Picos curtos não são problema.
  • Tunc Art: 60 carregamentos por minuto por pessoa, e ficheiros até 250 MiB.
  • O armazenamento é partilhado com o Tunc Hub, o Tunc Orb e o Tunc Art; a página da tua conta mostra a parte de cada produto.

Erros

CódigoSignificadoDetalhes do armazenamento
507 storage_limitTunc Orb: o teu armazenamento Tunc está cheio, por isso a gravação foi recusada, depois de remover os teus ficheiros mais antigos do Tunc Art para abrir espaço, se existiam. As leituras e eliminações continuam a funcionar.error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceededTunc Art: o carregamento não cabe, mesmo depois de remover os teus ficheiros mais antigos para abrir espaço.quota_bytes, active_bytes, requested_bytes, e storage com os mesmos campos acima
429 rate_limitedDemasiadas chamadas. Aguarda details.retry_after_secs (Orb) ou o cabeçalho Retry-After (ambos). No Orb, details.limit diz qual é o limite: daily, uma classe (read, write, search ou control) ou key_sign_in, quando demasiadas chaves iniciam sessão ao mesmo tempo.—
401 auth_required, not_connectedauth_required: a chave está em falta ou não é válida. not_connected: a chave foi desligada ou expirou; cria uma nova. O Tunc Art responde unauthenticated para uma chave que não aceita.—
403 forbiddenA chave não tem este acesso. missing_scope diz qual é, por exemplo orb.write (Orb: error.details.missing_scope). Cria uma chave com esse acesso.—

Os erros do Tunc Orb têm este formato: {"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}}; next_step diz o que fazer. Um armazenamento cheio nunca se resolve com novas tentativas: elimina o que já não precisas ou adiciona armazenamento na tua conta.

O adaptador MCP local

tunc-orb-mcp dá a qualquer cliente MCP as ferramentas data_read, data_write, data_update e data_delete, além de art_read. Adiciona-o ao teu cliente:

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

Executa tunc-orb-mcp connect uma vez: mostra um código como BCDF-GHJK com uma ligação para https://tuncorb.com/connect?code=BCDF-GHJK. Abre a ligação, inicia sessão, confirma que o código é o mesmo e autoriza. O adaptador guarda localmente um refresh token (num ficheiro privado, ou no porta-chaves do sistema com --keyring) e substitui-o a cada utilização; nunca deve aparecer num prompt.

A API HTTP com um agente com sessão iniciada

Um agente que iniciou sessão para https://mcp.tuncorb.com/mcp, num navegador ou com um código (vê Agentes sem navegador), troca o seu token de acesso por um token do Tunc Orb de curta duração:

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

Os tokens do Orb duram no máximo cinco minutos. Pede um novo quando expirar; desligar o agente interrompe a renovação.

Escrever, ler e eliminar

Cada pedido é um JSON com um operation, enviado com uma chave de API ou um token de acesso. As escritas e eliminações levam um mutation_id (mut_ seguido de 16 a 64 caracteres entre 0-9 e letras minúsculas, exceto i, l, o e u) que geras uma vez para cada alteração pretendida e reutilizas nas novas tentativas, para que uma nova tentativa nunca seja aplicada duas vezes.

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 a tua prateleira predefinida; cada resultado indica a prateleira usada, para que as novas tentativas a possam fixar.

O que as ferramentas fazem

  • data_read: shelves lista as prateleiras que podes usar; list pagina nomes e descrições de uma linha sob um prefixo, e contains restringe a lista aos nomes ou descrições que contêm esse texto; get lê um registo (opcionalmente, partes de um valor JSON); log lê entradas de log, das mais recentes para as mais antigas, a menos que peças o contrário; search procura texto dentro de um prefixo; query encontra as linhas que cumprem condições num log, num registo que guarda uma lista ou nos registos sob um prefixo, e pode juntá-las a uma segunda fonte por uma chave em comum, na mesma prateleira ou na de um colega de equipa; status informa o resultado de uma alteração anterior.
  • data_write: usa create para criar um registo com uma linha about que o descreve, ou append para acrescentar entradas a um log. Só acrescenta: nunca substitui um registo nem uma entrada de log.
  • data_update: usa replace ou patch num registo que já existe, numa revisão conhecida. Isto substitui o valor guardado, e o valor anterior não pode ser lido de novo, por isso os clientes pedem confirmação antes de o executar.
  • data_delete: elimina um registo (record), um log inteiro (log) ou entradas de log selecionadas (entries), numa revisão conhecida.
  • art_read: o servidor do Tunc Orb também abre, só para leitura, os ficheiros que guardaste no Tunc Art, pelo artifact_id deles. Guarda o artifact_id de um ficheiro num registo e qualquer agente consegue encontrá-lo. Não consegue carregar nem eliminar ficheiros.

Cada agente ligado em teu nome pode usar todas as prateleiras a que tens acesso, incluindo registos escritos pelos teus outros agentes. Desligar um agente não afeta os outros. Para manter clientes separados, usa uma conta Tunc por cliente: cada agente ligado a uma conta consegue ler todas as prateleiras dela.

Prateleiras, retenção e limites

  • Os registos e logs são mantidos até os eliminares. Um registo comporta até 16 MiB; uma chamada envia no máximo 64 KiB, por isso faz crescer um registo maior com patches.
  • Uma conta gratuita tem uma prateleira; o armazenamento pago permite quantas precisares. Cria prateleiras no separador Shelves da tua conta.
  • Quando o armazenamento está cheio, guardar remove primeiro os teus ficheiros mais antigos do Tunc Art para abrir espaço (nunca registos ou logs do Tunc Orb); se mesmo assim não houver espaço, a gravação é recusada com storage_limit. As leituras e eliminações continuam a funcionar.
  • Os limites de utilização justa e de frequência de pedidos estão em Usar uma chave de API.

Encriptação

O Tunc Orb usa encriptação gerida. Os valores dos registos são encriptados com uma chave de dados por prateleira antes de serem armazenados; o serviço de chaves do Tunc protege essas chaves, e o serviço do Tunc Orb desencripta os valores para responder aos teus agentes autorizados. O Tunc pode tratar os dados para operar o serviço. Isto não é encriptação ponto a ponto. Os nomes dos registos e as descrições de uma linha não são encriptados, por isso não coloques segredos neles.

O que o site mostra

Armazenamento usado, contagem de operações, etiquetas e ciclo de vida das prateleiras, e ligações de agentes. Não tem navegador de registos, pré-visualização, pesquisa, editor nem exportação, e o teu início de sessão no site não é uma credencial de agente.