# tmphost.io docs

> An agent reaches tmphost.io in two ways: the `file` tool of the MCP server at https://mcp.tmphost.io/mcp, or the `tmphost` CLI. Both upload, download, list and link files in folders that expire on their own.

HTML version: https://tmphost.io/docs/

- [MCP tools](https://tmphost.io/docs/mcp.md): the `file` tool's arguments, results and example calls ([HTML](https://tmphost.io/docs/mcp/))
- [CLI](https://tmphost.io/docs/cli.md): install, sign in and every `tmphost` command with example output ([HTML](https://tmphost.io/docs/cli/))

## CLI or MCP?

**If the agent can run shell commands, use the CLI.** `tmphost file upload` reads files from local paths and prints only their URLs, and `tmphost file download -o` writes to a local path, so a 5 MB PDF or a whole `dist/` folder costs the context a few lines. Through MCP, every byte of a file is a tool argument the model has to write out, and every byte of a download comes back into its context.

**Without a shell, use MCP, and send text as text.** For `.html`, `.css`, `.js`, `.md`, `.json`, `.svg` and other UTF-8 files, pass `format: "textContent"`: the content goes as is. The default, `base64Content`, makes the payload a third larger and turns readable text into opaque characters. Keep `base64Content` for binary files such as images and PDFs.

| Way | What passes through the model's context | Use it for |
| --- | --- | --- |
| CLI | The command, then the folder id and URLs | Any file, any size, whole directories |
| MCP textContent | The file's text, as is | Small text files the agent just wrote: HTML, CSS, JS, Markdown, JSON |
| MCP base64Content | The file as base64: 4 characters for every 3 bytes | Small binary files, when there is no shell |

### The same upload, both ways

A 300 KB `report.html` through the CLI is one short command:

```sh
tmphost file upload report.html --ttl 2h
```

Through MCP, the same file is 300 KB of `textContent` in the tool call, or about 400 KB as `base64Content`. Either way the model writes it out token by token.

## Concepts

### Folders and TTL

Every upload goes into a folder. A new folder gets a TTL (default 30 minutes, set with `ttl` or `--ttl`, such as `2h`); when it runs out, the folder and its files are deleted and their URLs stop working. The maximum TTL is in `GET https://app.tmphost.io/api/v1/limits`.

### Folder ids and URLs

An upload returns the folder's `id` (such as `k7q2m9xa`) and the file's public `url` (such as `https://k7q2m9xa.file.tmphost.io/index.html`). Pass the id back to add files to that folder. The folder URL serves a page when `index.html` sits at its root. Take URLs from the responses instead of building them by hand.

### Paths

A file can live in directories inside its folder (`path`, such as `site/css`), at most 5 levels deep. Paths use `/`, with no `.` or `..` segments and no backslashes.

### Updates

Uploading to a path that already holds a file replaces it in place: its URL stays the same and the folder keeps its expiry.

### Credits

An account gets 250 credits every 30 days. Each file written costs 1 credit per started MB of its size per started 30 minutes of the folder's remaining lifetime: a 1.01 MB file in a folder with an hour left costs 2 × 2 = 4 credits.

### Sign-in

Both the MCP server and the CLI sign in with OAuth through https://app.tmphost.io in the browser, once. The CLI saves its tokens and refreshes them; MCP clients that support OAuth do the same.