Q3 report

# tmphost.io MCP tools

> The MCP server at https://mcp.tmphost.io/mcp has one tool, `file`, with four actions: `upload`, `download`, `get` and `url`.

HTML version: https://tmphost.io/docs/mcp/ · Docs overview: https://tmphost.io/docs.md · CLI: https://tmphost.io/docs/cli.md

## When to use MCP

Every byte of a file passes through the model's context as a tool argument or result. If the agent can run shell commands, the CLI (https://tmphost.io/docs/cli.md) uploads from disk instead and keeps large files out of the context. Use MCP when there is no shell, or for small files the agent has just written.

For text files (`.html`, `.css`, `.js`, `.md`, `.json`, `.svg`, `.txt`) set `format` to `textContent` and send the text as is. It is a third smaller than base64 and stays readable. Use `base64Content` only for binary files.

## Connect

The server speaks streamable HTTP. Add it to any MCP client; clients that support OAuth open the browser to sign in through https://app.tmphost.io the first time they connect.

```json
{
  "mcpServers": {
    "tmphost": {
      "type": "http",
      "url": "https://mcp.tmphost.io/mcp"
    }
  }
}
```

Claude Code:

```sh
claude mcp add --transport http tmphost https://mcp.tmphost.io/mcp
```

## Arguments

| Argument | Description |
| --- | --- |
| `action` | Required. `upload`, `download`, `get` or `url`. |
| `id` | Folder id. `upload` without it creates a new folder; with it, adds or replaces files in that folder. Required by the other actions. |
| `ttl` | Lifetime of a new folder in whole minutes, such as `30m` or `2h` (default `30m`). `upload` only, and only without `id`. |
| `fileName` | File name, without directories, such as `index.html`. |
| `path` | Directory inside the folder, such as `site/css`, at most 5 levels. Empty for the folder root. |
| `format` | Which field carries the content: `base64Content` (default) or `textContent`. `upload` and `download` only. |
| `textContent` | UTF-8 text content, as is. `upload` with `format: "textContent"`. |
| `base64Content` | Base64 content. `upload` with `format: "base64Content"`. |

## Result fields

Each action fills its part; empty fields are left out.

| Field | Description |
| --- | --- |
| `id` | The folder id. Keep it to add files later. |
| `url` | Public URL of the file (`upload`), the folder (`get`) or what `url` asked for. |
| `expiresAt` | When the folder is deleted, RFC 3339 in UTC. `upload` returns it only for a new folder. |
| `fileName`, `path`, `size` | The file's name, directory and size in bytes. |
| `creditsSpent` | Credits the upload cost. |
| `textContent`, `base64Content` | The downloaded file, in the field `format` named. |
| `files` | `get`: every file as `fileName`, `path`, `size`, `url`. |

## Examples

The ids, times and URLs below are examples; take the real ones from each result.

### Upload an HTML page as text, in a new folder

Call `file`:

```json
{
  "action": "upload",
  "ttl": "2h",
  "fileName": "index.html",
  "format": "textContent",
  "textContent": "<!doctype html><title>Report</title><link rel=\"stylesheet\" href=\"css/style.css\"><h1>Q3 report</h1>"
}
```

Result:

```json
{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/index.html",
  "expiresAt": "2026-10-19T23:08:00Z",
  "fileName": "index.html",
  "size": 98,
  "creditsSpent": 4
}
```

A file under 1 MB in a 2 hour folder costs 1 × 4 = 4 credits. Because `index.html` is at the root, the folder URL `https://k7q2m9xa.file.tmphost.io/` serves the page too.

### Add a stylesheet to the same folder, in a directory

Call `file`:

```json
{
  "action": "upload",
  "id": "k7q2m9xa",
  "path": "css",
  "fileName": "style.css",
  "format": "textContent",
  "textContent": "body{font:16px/1.5 system-ui;margin:40px}"
}
```

Result:

```json
{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/css/style.css",
  "fileName": "style.css",
  "path": "css",
  "size": 41,
  "creditsSpent": 4
}
```

With `id`, leave out `ttl`: the folder keeps its expiry, and the cost counts its remaining lifetime.

### Upload an image as base64

Call `file`:

```json
{
  "action": "upload",
  "id": "k7q2m9xa",
  "path": "img",
  "fileName": "logo.png",
  "base64Content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
}
```

Result:

```json
{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/img/logo.png",
  "fileName": "logo.png",
  "path": "img",
  "size": 70,
  "creditsSpent": 4
}
```

`format` defaults to `base64Content`, so it can be left out here.

### Replace a file in place

Upload to the same `id`, `path` and `fileName` again. The URL stays `https://k7q2m9xa.file.tmphost.io/index.html`, so a link already shared shows the new version.

```json
{
  "action": "upload",
  "id": "k7q2m9xa",
  "fileName": "index.html",
  "format": "textContent",
  "textContent": "<!doctype html><title>Report</title><link rel=\"stylesheet\" href=\"css/style.css\"><h1>Q3 report (final)</h1>"
}
```

### List a folder's files

Call `file`:

```json
{ "action": "get", "id": "k7q2m9xa" }
```

Result:

```json
{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/",
  "expiresAt": "2026-10-19T23:08:00Z",
  "files": [
    { "fileName": "style.css", "path": "css", "size": 41, "url": "https://k7q2m9xa.file.tmphost.io/css/style.css" },
    { "fileName": "logo.png", "path": "img", "size": 70, "url": "https://k7q2m9xa.file.tmphost.io/img/logo.png" },
    { "fileName": "index.html", "path": "", "size": 106, "url": "https://k7q2m9xa.file.tmphost.io/index.html" }
  ]
}
```

### Get a URL

The URL of a folder (`id`), a directory (`id`, `path`, ending with `/`) or a file (`id`, `fileName`, optional `path`). The file does not have to exist yet.

Call `file`:

```json
{ "action": "url", "id": "k7q2m9xa", "path": "img", "fileName": "logo.png" }
```

Result:

```json
{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/img/logo.png",
  "expiresAt": "2026-10-19T23:08:00Z",
  "fileName": "logo.png",
  "path": "img"
}
```

### Download a text file

Call `file`:

```json
{ "action": "download", "id": "k7q2m9xa", "path": "css", "fileName": "style.css", "format": "textContent" }
```

Result:

```json
{
  "id": "k7q2m9xa",
  "fileName": "style.css",
  "path": "css",
  "size": 41,
  "textContent": "body{font:16px/1.5 system-ui;margin:40px}"
}
```

A download as `textContent` fails for a file that is not UTF-8 text; download it with `format: "base64Content"` instead.

## Errors

A failed call returns an error message that says what to change:

| Message | Fix |
| --- | --- |
| textContent needs format textContent | Add `"format": "textContent"`, or send `base64Content`. |
| base64Content must be base64 | Send standard base64, or the text itself as `textContent`. |
| ttl only applies to a new folder: leave out id or ttl | A folder's expiry is set when it is created. |
| ttl must be whole minutes, such as 30m or 2h | Use a duration like `45m` or `6h`. |
| fileName is required and must not contain / | Put directories in `path`. |
| the file is not UTF-8 text: download it with format base64Content | Use `base64Content` for binary files. |