TUNC.AI / Documentação do Tunc Art

Partilhar e abrir ficheiros com o Tunc Art

Cada ficheiro tem uma ligação privada curta, como tuncart.com/Q7m4Kp. A ligação é um endereço, não uma chave.

Queres configurações prontas? Os exemplos trazem prompts para colares no teu agente.

Abrir um ficheiro

  • Inicia sessão com a tua conta Tunc. Podes abrir os ficheiros que são teus e os que foram partilhados contigo através de um espaço de trabalho.
  • Imagens, vídeos, áudios, PDF e páginas web (isoladas numa sandbox, por isso os scripts nunca são executados) abrem na própria página; o Markdown abre como documento formatado, e os ficheiros de código e JSON aparecem com cores (o mesmo acontece em art.tunchub.com), enquanto outros textos e CSV aparecem como texto simples. Word, Excel, PowerPoint, ficheiros comprimidos e outros ficheiros mostram o nome, o tipo e o tamanho, com um botão Transferir. As páginas web abrem numa sandbox sem acesso à tua conta; os PDF usam o visualizador do teu navegador.
  • Transferir devolve sempre os bytes originais.

Partilha com palavra-passe

O proprietário pode ativar uma palavra-passe de partilha na página do ficheiro e enviá-la à parte. Qualquer pessoa com a ligação e a palavra-passe pode abrir o ficheiro durante 30 minutos de cada vez. Desativar a partilha termina imediatamente todas as sessões desbloqueadas. Uma palavra-passe é válida durante 7 dias, no máximo, ou até o ficheiro expirar; define-a de novo para prolongar o prazo. Só o proprietário pode ativar a partilha: um assistente não a consegue ativar. A partilha com palavra-passe nunca muda o que os agentes do proprietário podem fazer.

Agentes e a API do Art

Os agentes iniciam sessão com o Tunc a partir do claude.ai, do ChatGPT e de outros clientes MCP, ligam-se com um código quando não têm navegador ou usam uma chave de API. No Tunc Hub, o Art já vem integrado; vê como funciona.

Iniciar sessão com o Tunc

Os clientes MCP que iniciam sessão ligam-se a https://mcp.tuncart.com/mcp com a tua conta Tunc: nenhuma chave para copiar. (O outro produto fica em https://mcp.tuncorb.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 Art, URL https://mcp.tuncart.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%20Art&connectorUrl=https%3A%2F%2Fmcp.tuncart.com%2Fmcp
Claude CodeAdiciona o servidor, depois executa /mcp, escolhe tunc-art e Authenticate.
claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp
ChatGPTSettings → Apps & Connectors → Advanced → ativa o Developer mode → Create → nome Tunc Art, URL https://mcp.tuncart.com/mcp, Authentication OAuth → Create → Connect.
CursorAdiciona-o ao ~/.cursor/mcp.json e depois vai a Settings → MCP: aparece “Needs login” → Login.
{
  "mcpServers": {
    "tunc-art": {
      "url": "https://mcp.tuncart.com/mcp"
    }
  }
}
VS Code (Copilot)Paleta de Comandos → MCP: Add Server → HTTP → https://mcp.tuncart.com/mcp → nome tunc-art → aceita o pedido de início de sessão.
Gemini CLIAdiciona-o ao settings.json e depois executa /mcp auth tunc-art.
{
  "mcpServers": {
    "tunc-art": {
      "httpUrl": "https://mcp.tuncart.com/mcp"
    }
  }
}
Copilot StudioTools → Add a tool → New tool → Model Context Protocol → em URL, indica https://mcp.tuncart.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://tuncart.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 art.read art.write" -d resource=https://mcp.tuncart.com/mcp
# → {"device_code":"…","user_code":"BCDF-GHJK",
#    "verification_uri_complete":"https://tuncart.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.tuncart.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 Art em https://tuncart.com/.well-known/agent-card.json e chamam https://a2a.tuncart.com. Cada mensagem leva uma parte de dados com um skill (o nome de uma ferramenta MCP, como art_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.tuncart.com.

curl -s https://a2a.tuncart.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":"art_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.

O que as ferramentas fazem

  • art_write: guarda um ficheiro de qualquer tipo, até 250 MiB. Os ficheiros pequenos vão inline (text ou content_base64, até 8 MiB); os maiores usam mode: "begin" para obter um URL de carregamento, um PUT dos bytes e depois mode: "complete". O resultado traz o artifact_id do ficheiro e a sua ligação privada. Os ficheiros nunca são substituídos: uma nova versão é um novo ficheiro.
  • art_read: list encontra ficheiros, dos mais recentes para os mais antigos, e aceita title, mime_prefix, kind (image, pdf, workbook, presentation, document e outros), created_after, created_before e sort (newest, oldest, name ou largest). get com include_content devolve o que há dentro: texto como texto; um PNG, JPEG, GIF ou WebP como imagem; um PDF como imagens das páginas, quatro de cada vez (pages escolhe quais); ficheiros do Word, PowerPoint, OpenDocument, iWork e de e-mail como texto; uma folha de cálculo como texto, por sheet e range; um ficheiro comprimido como uma lista de itens para ler um de cada vez com part; uma fotografia grande como uma imagem reduzida. Qualquer outra coisa, até 8 MiB, volta como content_base64, e com offset e length lês parte de um ficheiro de qualquer tamanho.
  • art_delete: remove um ficheiro que carregaste. A ligação dele deixa de funcionar de imediato, a palavra-passe de partilha, se existir, é desativada, e isto não pode ser anulado.

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-art https://mcp.tuncart.com/mcp --header "Authorization: Bearer $TUNC_API_KEY"

Cursor (mcp.json)

{
  "mcpServers": {
    "tunc-art": {
      "url": "https://mcp.tuncart.com/mcp",
      "headers": {
        "Authorization": "Bearer $TUNC_API_KEY"
      }
    }
  }
}

VS Code (mcp.json)

{
  "servers": {
    "tunc-art": {
      "type": "http",
      "url": "https://mcp.tuncart.com/mcp",
      "headers": {
        "Authorization": "Bearer $TUNC_API_KEY"
      }
    }
  }
}

Gemini CLI (settings.json)

{
  "mcpServers": {
    "tunc-art": {
      "httpUrl": "https://mcp.tuncart.com/mcp",
      "headers": {
        "Authorization": "Bearer $TUNC_API_KEY"
      }
    }
  }
}

OpenAI Responses API (tools)

{
  "type": "mcp",
  "server_label": "tunc-art",
  "server_url": "https://mcp.tuncart.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

# 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"
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"}'
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.

A API de ficheiros do Tunc Core com um agente com sessão iniciada

Um agente que iniciou sessão, ou que aprovaste com um código na página de ligação da tua conta, envia o seu token de acesso para a API de ficheiros do Tunc Core:

# Start an upload
curl -s https://core.tunc.ai/api/v1/art/files \
  -H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"display_name":"q4-report.pdf","mime_type":"application/pdf","byte_count":482113}'
# → {"artifact":{…},"upload":{"method":"PUT","url":"…","headers":{…},"expires_in_seconds":…}}

# Send the bytes to upload.url with upload.method and upload.headers, then:
curl -s https://core.tunc.ai/api/v1/art/files/<id>/complete \
  -H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
  -H 'content-type: application/json' -d '{"byte_count":482113}'
# Files you can access (paged; filters: title, mime_prefix, kind, created_after, created_before, sort, cursor, limit)
curl -s "https://core.tunc.ai/api/v1/art/files?limit=20" \
  -H "authorization: Bearer $TUNC_ACCESS_TOKEN"

# One file's metadata, then its bytes (Range supported)
curl -s https://core.tunc.ai/api/v1/art/files/<id> -H "authorization: Bearer $TUNC_ACCESS_TOKEN"
curl -s https://core.tunc.ai/api/v1/art/files/<id>/content -H "authorization: Bearer $TUNC_ACCESS_TOKEN" -o q4-report.pdf

Armazenamento

O Tunc Art e o Tunc Orb partilham a mesma quota de armazenamento da conta. A página de armazenamento da tua conta mostra o total e a parte de cada produto. Cada ficheiro pode ter até 250 MiB; os agentes enviam até 8 MiB inline por MCP, e ficheiros maiores com um carregamento pré-assinado. Dá a cada ficheiro o seu tipo de media real para que tenha pré-visualização.

Os ficheiros guardados por agentes são mantidos durante 30 dias no plano gratuito e 365 dias com armazenamento pago, e cada ficheiro mostra a data de fim. Quando o armazenamento está cheio, os ficheiros mais antigos são removidos primeiro e a tua conta lista o que foi removido.