Tunc Art

npx add-mcp 'https://mcp.tuncart.com/mcp'

TUNC.AI / Tunc Art docs

Sharing and opening files with Tunc Art

Every file has a short private link such as tuncart.com/Q7m4Kp. The link is an address, not a key.

Want working setups? The examples have prompts you paste to your agent.

Opening a file

• Sign in with your Tunc account. You can open files you own and files shared with you through a workspace.
• Images, video, audio, PDFs and web pages (sandboxed, so scripts never run) open in the page; text, Markdown, JSON, CSV and code show as plain text. Word, Excel, PowerPoint, archives and other files show their name, type and size with a Download button.Web pages open in a sandbox with no access to your account; PDFs use your browser's viewer.
• Download always returns the original bytes.

Password sharing

The owner can turn on a sharing password from the file's page and send it separately. Anyone with the link and the password can open the file for 30 minutes at a time. Turning sharing off ends every unlocked session immediately. A password works for at most 7 days or until the file expires; set it again to extend it. Only the owner can turn sharing on: an assistant cannot turn sharing on. Password sharing never changes what the owner's agents can do.

Agents and the Art API

Agents sign in with Tunc from claude.ai, ChatGPT and other MCP clients, connect with a code when they have no browser, or use an API key. In Tunc Hub, Art is built in; read how it works.

Sign in with Tunc

MCP clients that sign in connect to https://mcp.tuncart.com/mcp with your Tunc account: no key to copy. (The other product is at https://mcp.tuncorb.com/mcp.) Your client opens Tunc; you sign in, or create a free account with your organization and the Terms, then allow it once and choose what it may do.

Client	Steps
claude.ai, Claude Desktop and Claude mobile	Customize → Connectors → Add custom connector → name Tunc Art, URL https://mcp.tuncart.com/mcp → Add → Connect. The Free plan allows one custom connector; on Team and Enterprise an Owner adds it under Organization settings → Connectors. This link opens the dialog with the name and URL filled in: https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Art&connectorUrl=https%3A%2F%2Fmcp.tuncart.com%2Fmcp
Claude Code	Add the server, then run /mcp, choose tunc-art and Authenticate. claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp
ChatGPT	Settings → Apps & Connectors → Advanced → turn on Developer mode → Create → name Tunc Art, URL https://mcp.tuncart.com/mcp, Authentication OAuth → Create → Connect.
Cursor	Add it to ~/.cursor/mcp.json, then Settings → MCP: it shows “Needs login” → Login. { "mcpServers": { "tunc-art": { "url": "https://mcp.tuncart.com/mcp" } } }
VS Code (Copilot)	Command Palette → MCP: Add Server → HTTP → https://mcp.tuncart.com/mcp → name tunc-art → allow the sign-in prompt.
Gemini CLI	Add it to settings.json, then run /mcp auth tunc-art. { "mcpServers": { "tunc-art": { "httpUrl": "https://mcp.tuncart.com/mcp" } } }
Copilot Studio	Tools → Add a tool → New tool → Model Context Protocol → URL https://mcp.tuncart.com/mcp → Authentication OAuth 2.0, Dynamic discovery.

A client that only takes a header uses an API key instead.

Agents without a browser

An agent on a server or in a terminal shows you a code and a link such as https://tuncart.com/connect?code=BCDF-GHJK. Open it, sign in, check the code matches and allow it. Any OAuth library that speaks the device grant (RFC 8628) can do this:

# Once per agent: register it (no redirect needed)
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_…",…}

# Ask for a code, and show the person 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}

# Poll every interval seconds until they allow it
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"} until then, once allowed:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}

# Before the access token expires, swap the refresh token for new ones
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…

Send the access token as Authorization: Bearer to https://mcp.tuncart.com/mcp. Each refresh returns a new refresh token: keep only the newest one, because sending a used one again disconnects the agent.

A2A

Agents that speak A2A 1.0 find Tunc Art at https://tuncart.com/.well-known/agent-card.json and call https://a2a.tuncart.com. Every message carries one data part with a skill (an MCP tool name, such as art_read) and its arguments; the answer is the tool's result. Use an API key, or sign in with the resource 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":{…the tool's result…},"mediaType":"application/json"}],…}}}

Rename, change access or disconnect

Every agent and key is listed on tunchub.com → Agents & keys, with how it connected and what it may do. Rename it, use Change access to take access away (the agent asks you again for more), or Disconnect it: it stops working within a minute. All your agents share your Personal shelf.

What the tools do

• art_write: save a file of any type, up to 250 MiB. Small files go inline (text or content_base64, up to 8 MiB); larger ones use mode: "begin" for an upload URL, a PUT of the bytes, then mode: "complete". The result carries the file's artifact_id and its private link. Files are never overwritten: a new version is a new file.
• art_read: list finds files, newest first, and takes title, mime_prefix, kind (image, pdf, workbook, presentation, document and others), created_after, created_before and sort (newest, oldest, name, largest). get with include_content returns what is inside: text as text; a PNG, JPEG, GIF or WebP as a picture; a PDF as pictures of its pages, four at a time (pages picks which); Word, PowerPoint, OpenDocument, iWork and email files as text; a spreadsheet as text by sheet and range; an archive as a list of members to read one at a time with part; a large photo as a reduced picture. Anything else, up to 8 MiB, comes back as content_base64, and offset and length read part of a file of any size.
• art_delete: remove a file you uploaded. Its link stops working at once, any sharing password is turned off, and it cannot be undone.

Use an API key

Create an API key on tunchub.com with your Tunc account. Choose what it may do: read Tunc Orb (every key), save and delete in Tunc Orb, and open, upload and delete Tunc Art files. The key is shown once; keep it in your system's secret store, never in a prompt. Disconnect it any time from Agents & keys, and it stops working within a minute.

One key works on both APIs: https://api.tuncorb.com for Tunc Orb and https://api.tuncart.com for Tunc Art. Send it as Authorization: Bearer <key>.

Connect an MCP client

Tunc Orb's tools are at https://mcp.tuncorb.com/mcp and Tunc Art's at https://mcp.tuncart.com/mcp. Add the one you need with your key in the Authorization header (replace $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"
}

A key without the access a tool needs gets a tool error naming it in missing_scope; a disconnected key gets 401.

Call the API directly

# 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: save a record (one mutation_id per change; reuse it on retries)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
    "operation": "create", "name": "hello", "about": "first record",
    "text": "Hello from my agent", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())

# Tunc Art: list your files
print(requests.get("https://api.tuncart.com/v1/files", headers=headers).json())

Limits

• Fair use: 50,000 Tunc Orb operations a day on the free plan, 500,000 with paid storage. Reads, searches and saves count; deletes and status checks do not. The count starts again at midnight UTC.
• Per agent each second: 50 reads, 20 saves, 5 searches and 20 other calls. Short bursts are fine.
• Tunc Art: 60 uploads a minute per person, and files up to 250 MiB.
• Storage is shared with Tunc Hub, Tunc Orb and Tunc Art; your account page shows each product's share.

Errors

Code	Meaning	Storage details
507 storage_limit	Tunc Orb: your Tunc storage is full, so the save was refused, after removing your oldest Tunc Art files to make room if there were any. Reads and deletes still work.	error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceeded	Tunc Art: the upload does not fit, even after removing your oldest files to make room.	quota_bytes, active_bytes, requested_bytes, and storage with the same fields as above
429 rate_limited	Too many calls. Wait details.retry_after_secs (Orb) or the Retry-After header (both). On Orb, details.limit says which limit: daily, a class (read, write, search or control), or key_sign_in when too many keys sign in at once.	—
401 auth_required, not_connected	auth_required: the key is missing or not valid. not_connected: the key was disconnected or expired; create a new one. Tunc Art answers unauthenticated for a key it does not accept.	—
403 forbidden	The key does not have this access. missing_scope names it, for example orb.write (Orb: error.details.missing_scope). Create a key with that access.	—

Tunc Orb errors look like {"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}}; next_step says what to do. A full storage is never fixed by retrying: delete what you no longer need, or add storage in your account.

Tunc Core's files API with a signed-in agent

An agent that signed in, or that you approved with a code at your account's connect page, sends its access token to Tunc Core's files API:

# 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

Storage

Tunc Art and Tunc Orb share one account storage allowance. Your account's storage page shows the total and each product's share. Each file can be up to 250 MiB; agents send up to 8 MiB inline over MCP and larger files with a presigned upload. Give each file its real media type so it previews.

Files saved by agents are kept 30 days on the free plan and 365 days with paid storage, and each file shows its end date. When storage is full, the oldest files are removed first and your account lists what was removed.