MCP tool

The MCP server at https://mcp.permahost.io/mcp has one tool, file. Its action argument picks what it does: upload, download, get, url or list. Folders are passed as id.

LLM-friendly version (Markdown): https://permahost.io/docs/mcp.md

Connect

The server speaks streamable HTTP and is stateless. Add it to any MCP client; clients that support OAuth open the browser to sign in through app.permahost.io (Google or GitHub) the first time they connect. Every call needs that sign-in: without a token the server answers 401 and points to its OAuth metadata.

Its manifest, the MCP Registry server.json named io.github.tmphost/permahost, is at https://permahost.io/.well-known/mcp.json.

{
  "mcpServers": {
    "permahost": {
      "type": "http",
      "url": "https://mcp.permahost.io/mcp"
    }
  }
}

$ claude mcp add --transport http permahost https://mcp.permahost.io/mcp

The plugins for Claude Code, Codex, Cursor and Gemini CLI add the same server plus instructions on when and how to use it.

Arguments

Each action reads only the arguments it needs and fills only its own result fields; empty fields are left out.

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

upload

Stores one file and returns its public URL. Without id it creates a new folder; with id, the file goes into that folder, and a file already at the same path is replaced in place (an update: its URL stays the same).

Publish an HTML page as text, in a new folder

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

{
  "id": "k7q2m9xa3bd",
  "url": "https://k7q2m9xa3bd.file.permahost.io/index.html",
  "fileName": "index.html",
  "size": 98,
  "creditsSpent": 1000
}

The new folder costs 500 credits, and this was the account's first file this month, so it started a 25 MB storage block for another 500. Because index.html is at the root, the folder URL https://k7q2m9xa3bd.file.permahost.io/ serves the page too.

Add a stylesheet to the same folder, in a directory

{
  "action": "upload",
  "id": "k7q2m9xa3bd",
  "path": "css",
  "fileName": "style.css",
  "format": "textContent",
  "textContent": "body { font-family: system-ui; margin: 2rem; }"
}

{
  "id": "k7q2m9xa3bd",
  "url": "https://k7q2m9xa3bd.file.permahost.io/css/style.css",
  "fileName": "style.css",
  "path": "css",
  "size": 47
}

No creditsSpent: the folder is paid for and the account's storage stays inside a block already paid for this month.

Upload an image as base64

{
  "action": "upload",
  "id": "k7q2m9xa3bd",
  "path": "img",
  "fileName": "chart.png",
  "base64Content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
}

download

Reads a file back from one of your folders. Free of credits. Pass format: "textContent" to get UTF-8 text as is; a file that isn't UTF-8 text then fails, so read it as base64Content instead.

{
  "action": "download",
  "id": "k7q2m9xa3bd",
  "path": "css",
  "fileName": "style.css",
  "format": "textContent"
}

{
  "id": "k7q2m9xa3bd",
  "fileName": "style.css",
  "path": "css",
  "size": 47,
  "textContent": "body { font-family: system-ui; margin: 2rem; }"
}

get

Lists a folder's files with their URLs. Free.

{ "action": "get", "id": "k7q2m9xa3bd" }

{
  "id": "k7q2m9xa3bd",
  "url": "https://k7q2m9xa3bd.file.permahost.io/",
  "files": [
    { "fileName": "index.html", "path": "", "size": 98, "url": "https://k7q2m9xa3bd.file.permahost.io/index.html" },
    { "fileName": "style.css", "path": "css", "size": 47, "url": "https://k7q2m9xa3bd.file.permahost.io/css/style.css" }
  ]
}

url

Builds the public URL of a folder (id), a directory (id, path) or a file (id, fileName, optional path) without uploading anything. Free.

{ "action": "url", "id": "k7q2m9xa3bd", "path": "css", "fileName": "style.css" }

{
  "id": "k7q2m9xa3bd",
  "url": "https://k7q2m9xa3bd.file.permahost.io/css/style.css",
  "fileName": "style.css",
  "path": "css"
}

list

Lists your folders, newest first. Free. Use it to find the id of a folder published earlier before adding to it or updating it. title is the folder's title, else the name of its only file. No folders field means there are none.

{ "action": "list" }

{
  "folders": [
    {
      "id": "k7q2m9xa3bd",
      "title": "Q3 report",
      "url": "https://k7q2m9xa3bd.file.permahost.io/",
      "sizeBytes": 145,
      "createdAt": "2026-11-02T08:14:00Z"
    }
  ]
}

Credits

Credits are monthly and charged upfront when a cost starts. Only upload spends them; the other actions are free.

• A new folder costs 500 credits a month. Only upload without id creates one.
• Uploading with id into an existing folder never costs folder credits again, however many files it adds or replaces.
• Storage costs 500 credits a month per started 25 MB the whole account stores. An upload pays only when it pushes the total into a block not paid for this month, so most uploads cost 0; replacing a file counts only the size difference.

So to publish a site: upload the first file without id, keep the id it returns, and pass it for every other file. Never upload without id just to add files. See credits for renewals and custom domains.

Errors

A failed call returns a tool error with a message the agent can act on: