Conecte um agente ao Tunc Orb
Os agentes usam o Tunc Orb por MCP, A2A ou pela API HTTP: eles entram com o Tunc, se conectam com um código ou usam uma chave de API. Sua conta Tunc gerencia agentes, chaves e armazenamento; ela nunca lê nem mostra o que seus agentes guardam.
No Tunc Hub, o Orb já vem integrado; veja como funciona. Quer configurações prontas? Os exemplos trazem prompts para você colar no seu agente.
Entrar com o Tunc
Clientes MCP que fazem login se conectam a https://mcp.tuncorb.com/mcp com a sua conta Tunc: nenhuma chave para copiar. (O outro produto fica em https://mcp.tuncart.com/mcp.) Seu cliente abre o Tunc; você entra na conta, ou cria uma conta gratuita informando sua organização e aceitando os Termos, depois autoriza uma vez e escolhe 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 o adiciona em Organization settings → Connectors. Este link abre a caixa de diálogo com o nome e a URL já preenchidos: |
| Claude Code | Adicione o servidor, depois execute /mcp, escolha tunc-orb e Authenticate. |
| ChatGPT | Settings → Apps & Connectors → Advanced → ative o Developer mode → Create → nome Tunc Orb, URL https://mcp.tuncorb.com/mcp, Authentication OAuth → Create → Connect. |
| Cursor | Adicione-o ao ~/.cursor/mcp.json e depois vá em Settings → MCP: aparece “Needs login” → Login. |
| VS Code (Copilot) | Paleta de Comandos → MCP: Add Server → HTTP → https://mcp.tuncorb.com/mcp → nome tunc-orb → permita o pedido de login. |
| Gemini CLI | Adicione-o ao settings.json e depois execute /mcp auth tunc-orb. |
| Copilot Studio | Tools → Add a tool → New tool → Model Context Protocol → em URL, informe https://mcp.tuncorb.com/mcp → em Authentication, escolha 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 em um servidor ou em um terminal mostra a você um código e um link, como https://tuncorb.com/connect?code=BCDF-GHJK. Abra-o, entre na conta, confira se o código é o mesmo e autorize. Qualquer biblioteca OAuth que implemente o device grant (RFC 8628) consegue fazer isso:
# Uma vez por agente: registre-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_…",…}
# Peça um código e mostre à 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}
# Consulte 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, troque 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_…Envie o token de acesso como Authorization: Bearer para https://mcp.tuncorb.com/mcp. Cada renovação devolve um novo refresh token: guarde só o mais recente, porque enviar de novo um que já foi usado desconecta 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. Toda 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. Use uma chave de API ou entre 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"}],…}}}Renomear, mudar o acesso ou desconectar
Todos os agentes e chaves aparecem em tunchub.com → Agents & keys, com a forma como se conectaram e o que podem fazer. Renomeie, use Change access para retirar acesso (o agente pede de novo a você se precisar de mais) ou Disconnect: ele para de funcionar em até um minuto. Todos os seus agentes compartilham a sua prateleira Personal.
Usar uma chave de API
Crie uma chave de API no tunchub.com com sua conta Tunc. Escolha o que ela pode fazer: ler o Tunc Orb (toda chave pode), salvar e excluir no Tunc Orb, e abrir, enviar e excluir arquivos do Tunc Art. A chave aparece uma única vez; guarde-a no cofre de segredos do seu sistema, nunca em um prompt. Desconecte-a quando quiser em Agents & keys, e ela para de funcionar em até 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. Envie-a como Authorization: Bearer <key>.
Conecte 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. Adicione a que você precisa com sua chave no cabeçalho Authorization (substitua $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 desconectada recebe 401.
Chame 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: salvar um registro (um mutation_id por alteração; reutilize-o nas novas tentativas)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
"operation": "create", "name": "hello", "about": "primeiro registro",
"text": "Olá do meu agente", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())
# Tunc Art: listar seus arquivos
print(requests.get("https://api.tuncart.com/v1/files", headers=headers).json())Limites
- Uso justo: 50,000 operações do Tunc Orb por dia no plano gratuito, 500,000 com armazenamento pago. Leituras, buscas e salvamentos contam; exclusões e verificações de status não. A contagem recomeça à meia-noite UTC.
- Por agente, a cada segundo: 50 leituras, 20 salvamentos, 5 buscas e 20 outras chamadas. Picos curtos não são problema.
- Tunc Art: 60 uploads por minuto por pessoa, e arquivos de até 250 MiB.
- O armazenamento é compartilhado com o Tunc Hub, o Tunc Orb e o Tunc Art; a página da sua conta mostra a parte de cada produto.
Erros
| Código | Significado | Detalhes do armazenamento |
|---|---|---|
507 storage_limit | Tunc Orb: seu armazenamento Tunc está cheio, então o salvamento foi recusado, depois de remover seus arquivos mais antigos do Tunc Art para abrir espaço, se havia algum. Leituras e exclusões continuam funcionando. | error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url |
409 storage_quota_exceeded | Tunc Art: o upload não cabe, mesmo depois de remover seus arquivos mais antigos para abrir espaço. | quota_bytes, active_bytes, requested_bytes, e storage com os mesmos campos acima |
429 rate_limited | Chamadas demais. Aguarde 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 chaves demais entram ao mesmo tempo. | — |
401 auth_required, not_connected | auth_required: a chave está faltando ou não é válida. not_connected: a chave foi desconectada ou expirou; crie uma nova. O Tunc Art responde unauthenticated para uma chave que ele não aceita. | — |
403 forbidden | A chave não tem esse acesso. missing_scope diz qual é, por exemplo orb.write (Orb: error.details.missing_scope). Crie 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: exclua o que você não precisa mais ou adicione armazenamento na sua 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. Adicione-o ao seu cliente:
{
"mcpServers": {
"tunc-orb": { "command": "tunc-orb-mcp" }
}
}Execute tunc-orb-mcp connect uma vez: ele mostra um código como BCDF-GHJK com um link para https://tuncorb.com/connect?code=BCDF-GHJK. Abra o link, entre na conta, confira se o código é o mesmo e autorize. O adaptador guarda um refresh token localmente (em um arquivo privado, ou no chaveiro do sistema com --keyring) e o substitui a cada uso; ele nunca deve aparecer em um prompt.
A API HTTP com um agente conectado
Um agente que entrou para https://mcp.tuncorb.com/mcp, em um navegador ou com um código (veja Agentes sem navegador), troca o próprio 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. Peça um novo quando ele expirar; desconectar o agente interrompe a renovação.
Gravar, ler e excluir
Toda requisição é um JSON com um operation, enviado com uma chave de API ou um token de acesso. Gravações e exclusõ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 você gera uma vez para cada alteração pretendida e reutiliza 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_…"}'Omita shelf_id para usar sua prateleira padrão; todo resultado informa a prateleira usada, para que as novas tentativas possam fixá-la.
O que as ferramentas fazem
- data_read:
shelveslista as prateleiras que você pode 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 registro (opcionalmente, partes de um valor JSON);loglê entradas de log, das mais recentes para as mais antigas, a menos que você peça o contrário;searchprocura texto dentro de um prefixo;queryencontra as linhas que atendem a condições em um log, em um registro que guarda uma lista ou nos registros 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 equipe;statusinforma o resultado de uma alteração anterior. - data_write: use
createpara criar um registro com uma linhaaboutque o descreve, ouappendpara acrescentar entradas a um log. Ela só acrescenta: nunca sobrescreve um registro nem uma entrada de log. - data_update: use
replaceoupatchem um registro que já existe, em uma revisão conhecida. Isso sobrescreve o valor salvo, e o valor anterior não pode ser lido de volta, então os clientes pedem confirmação antes de executar. - data_delete: exclui um registro (
record), um log inteiro (log) ou entradas de log selecionadas (entries), em uma revisão conhecida. - art_read: o servidor do Tunc Orb também abre, somente para leitura, os arquivos que você salvou no Tunc Art, pelo
artifact_iddeles. Guarde oartifact_idde um arquivo em um registro e qualquer agente consegue encontrá-lo. Ele não consegue enviar nem excluir arquivos.
Todo agente conectado como você pode usar todas as prateleiras às quais você tem acesso, incluindo registros gravados pelos seus outros agentes. Desconectar um agente não afeta os outros. Para manter clientes separados, use uma conta Tunc por cliente: todo agente conectado a uma conta consegue ler todas as prateleiras dela.
Prateleiras, retenção e limites
- Registros e logs são mantidos até você excluí-los. Um registro comporta até 16 MiB; uma chamada envia no máximo 64 KiB, então faça um registro maior crescer com patches.
- Uma conta gratuita tem uma prateleira; o armazenamento pago permite quantas você precisar. Crie prateleiras na aba Shelves da sua conta.
- Quando o armazenamento está cheio, um salvamento primeiro remove seus arquivos mais antigos do Tunc Art para abrir espaço (nunca registros ou logs do Tunc Orb); se mesmo assim não houver espaço, o salvamento é recusado com
storage_limit. Leituras e exclusões continuam funcionando. - Os limites de uso justo e de taxa estão em Usar uma chave de API.
Criptografia
O Tunc Orb usa criptografia gerenciada. Os valores dos registros são criptografados 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 descriptografa os valores para responder aos seus agentes autorizados. O Tunc pode processar os dados para operar o serviço. Isso não é criptografia de ponta a ponta. Os nomes dos registros e as descrições de uma linha não são criptografados, então não coloque segredos neles.
O que o site mostra
Armazenamento usado, contagem de operações, rótulos e ciclo de vida das prateleiras, e conexões de agentes. Ele não tem navegador de registros, pré-visualização, busca, editor nem exportação, e o seu login no site não é uma credencial de agente.
