TUNC.AI / Documentação do Tunc Art

Compartilhar e abrir arquivos com o Tunc Art

Cada arquivo tem um link privado curto, como tuncart.com/Q7m4Kp. O link é um endereço, não uma chave.

Quer configurações prontas? Os exemplos trazem prompts para você colar no seu agente.

Abrir um arquivo

  • Entre com sua conta Tunc. Você pode abrir os arquivos que são seus e os que foram compartilhados com você por meio de um espaço de trabalho.
  • Imagens, vídeos, áudios, PDFs e páginas da web (isoladas em sandbox, então scripts nunca rodam) abrem na própria página; Markdown abre como documento formatado, e arquivos de código e JSON aparecem com cores (o mesmo vale em art.tunchub.com), enquanto outros textos e CSV aparecem como texto simples. Word, Excel, PowerPoint, arquivos compactados e outros arquivos mostram nome, tipo e tamanho, com um botão Baixar. Páginas da web abrem em uma sandbox sem acesso à sua conta; PDFs usam o visualizador do seu navegador.
  • Baixar sempre devolve os bytes originais.

Compartilhamento com senha

O dono pode ativar uma senha de compartilhamento na página do arquivo e enviá-la separadamente. Qualquer pessoa com o link e a senha pode abrir o arquivo por 30 minutos de cada vez. Desativar o compartilhamento encerra imediatamente todas as sessões desbloqueadas. Uma senha vale por no máximo 7 dias ou até o arquivo expirar; defina-a de novo para estender o prazo. Só o dono pode ativar o compartilhamento: um assistente não consegue ativá-lo. O compartilhamento com senha nunca muda o que os agentes do dono podem fazer.

Agentes e a API do Art

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

Entrar com o Tunc

Clientes MCP que fazem login se conectam a https://mcp.tuncart.com/mcp com a sua conta Tunc: nenhuma chave para copiar. (O outro produto fica em https://mcp.tuncorb.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.

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 o adiciona em Organization settings → Connectors. Este link abre a caixa de diálogo com o nome e a URL já preenchidos:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Art&connectorUrl=https%3A%2F%2Fmcp.tuncart.com%2Fmcp
Claude CodeAdicione o servidor, depois execute /mcp, escolha tunc-art e Authenticate.
claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp
ChatGPTSettings → Apps & Connectors → Advanced → ative o Developer mode → Create → nome Tunc Art, URL https://mcp.tuncart.com/mcp, Authentication OAuth → Create → Connect.
CursorAdicione-o ao ~/.cursor/mcp.json e depois vá em 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 → permita o pedido de login.
Gemini CLIAdicione-o ao settings.json e depois execute /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, informe https://mcp.tuncart.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://tuncart.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 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}

# 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.tuncart.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 Art em https://tuncart.com/.well-known/agent-card.json e chamam https://a2a.tuncart.com. Toda 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. Use uma chave de API ou entre 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"}],…}}}

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.

O que as ferramentas fazem

  • art_write: salva um arquivo de qualquer tipo, de até 250 MiB. Arquivos pequenos vão inline (text ou content_base64, até 8 MiB); os maiores usam mode: "begin" para obter uma URL de upload, um PUT dos bytes e depois mode: "complete". O resultado traz o artifact_id do arquivo e o link privado dele. Os arquivos nunca são sobrescritos: uma nova versão é um novo arquivo.
  • art_read: list encontra arquivos, 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); arquivos do Word, PowerPoint, OpenDocument, iWork e de e-mail como texto; uma planilha como texto, por sheet e range; um arquivo compactado como uma lista de itens para ler um de cada vez com part; uma foto grande como uma imagem reduzida. Qualquer outra coisa, de até 8 MiB, volta como content_base64, e com offset e length você lê parte de um arquivo de qualquer tamanho.
  • art_delete: remove um arquivo que você enviou. O link dele para de funcionar na hora, a senha de compartilhamento, se houver, é desativada, e isso não pode ser desfeito.

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-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 desconectada recebe 401.

Chame 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: 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ódigoSignificadoDetalhes do armazenamento
507 storage_limitTunc 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_exceededTunc 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_limitedChamadas 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_connectedauth_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 forbiddenA 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.

A API de arquivos do Tunc Core com um agente conectado

Um agente que entrou na conta, ou que você aprovou com um código na página de conexão da sua conta, envia o próprio token de acesso para a API de arquivos 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 compartilham a mesma cota de armazenamento da conta. A página de armazenamento da sua conta mostra o total e a parte de cada produto. Cada arquivo pode ter até 250 MiB; os agentes enviam até 8 MiB inline por MCP, e arquivos maiores com um upload pré-assinado. Dê a cada arquivo o tipo de mídia real para que ele tenha pré-visualização.

Arquivos salvos por agentes são mantidos por 30 dias no plano gratuito e por 365 dias com armazenamento pago, e cada arquivo mostra a data de término. Quando o armazenamento está cheio, os arquivos mais antigos são removidos primeiro e sua conta lista o que foi removido.