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.
| Cliente | Passos |
|---|---|
| claude.ai, Claude Desktop and Claude mobile | Customize → 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: |
| Claude Code | Adiciona o servidor, depois executa /mcp, escolhe tunc-orb e Authenticate. |
| ChatGPT | Settings → Apps & Connectors → Advanced → ativa o Developer mode → Create → nome Tunc Orb, URL https://mcp.tuncorb.com/mcp, Authentication OAuth → Create → Connect. |
| Cursor | Adiciona-o ao ~/.cursor/mcp.json e depois vai a Settings → MCP: aparece “Needs login” → Login. |
| 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 CLI | Adiciona-o ao settings.json e depois executa /mcp auth tunc-orb. |
| Copilot Studio | Tools → 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ódigo | Significado | Detalhes do armazenamento |
|---|---|---|
507 storage_limit | Tunc 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_exceeded | Tunc 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_limited | Demasiadas 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_connected | auth_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 forbidden | A 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:
shelveslista as prateleiras que podes usar;listpagina nomes e descrições de uma linha sob um prefixo, econtainsrestringe a lista aos nomes ou descrições que contêm esse texto;getlê um registo (opcionalmente, partes de um valor JSON);loglê entradas de log, das mais recentes para as mais antigas, a menos que peças o contrário;searchprocura texto dentro de um prefixo;queryencontra 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;statusinforma o resultado de uma alteração anterior. - data_write: usa
createpara criar um registo com uma linhaaboutque o descreve, ouappendpara acrescentar entradas a um log. Só acrescenta: nunca substitui um registo nem uma entrada de log. - data_update: usa
replaceoupatchnum 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_iddeles. Guarda oartifact_idde 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.
