MCP server

tralha serves MCP over streamable HTTP at /mcp on the private port. Clients authenticate with an API key in the Authorization: Bearer header, and each tool only does what the key's scopes allow.

Connecting

Claude Code:

claude mcp add --transport http --scope user tralha https://api.example.com/mcp \
  --header "Authorization: Bearer trh_…"

Give the agent its own key with only the buckets it needs, for example write and share in pr-assets and scratch plus read everywhere. A key with --expires limits the damage if it leaks from a config file.

ChatGPT connectors require OAuth, which tralha does not support yet.

Tools

Tool	What it does	Scope
list_buckets	Buckets the key can read, with object counts and bytes used	read
list_objects	Objects under a prefix, grouped by folder unless recursive is set	read
put_text	Stores text such as markdown, JSON, logs or CSV, with optional metadata and expiry	write
create_upload	Returns a single-use upload URL and a ready curl command	write
get_object	Returns text as text, images as a downscaled image the model can see, and metadata for anything else	read
share	Creates a public link and returns url and markdown ready to paste into a PR	share
revoke_share	Revokes a link by its token	share
delete_object	Deletes an object and all its links	delete
search_docs	Full-text search over text documents, with highlighted snippets	read
create_bucket	Creates a bucket, optionally with a cleanup rule	admin

The server also sends instructions that tell the model how to use these tools together, so most requests in plain language work without further prompting.

Why binary files use upload URLs

An image passed as a tool argument would travel as base64 inside the conversation. A 1 MB screenshot becomes about 1.3 MB of text that the model has to read and write, which is slow and expensive.

Instead, the agent calls create_upload, gets a URL valid for 10 minutes and one request, and runs:

curl -sfT ./screenshots/login.png https://api.example.com/upload/<token>

The file goes straight from disk to tralha. The agent then calls share and pastes the returned markdown into the PR. This needs an agent that can run shell commands, as Claude Code can.

Text is different: put_text takes the content directly, since notes and logs are text the model already has.

Images the model can see

get_object on an image returns a PNG preview whose longer side is at most 1568 pixels, which is enough to inspect a screenshot without spending tokens on resolution the model cannot use. The preview is generated in the sandboxed image worker described in Security model.

Text objects come back as text, cut at 200,000 characters.

Errors

Tool errors carry a short message such as missing 'write' permission on bucket 'docs'. Unexpected exceptions are masked, so internal details never reach the client.