Hostsmith

Name: Hostsmith
Author: hostsmith

@hostsmith

Repository

About Hostsmith

Deploy static sites on Hostsmith - give it a file, get a live HTTPS URL. EU/US residency.

#hostsmith #mcp #hosting #deploy #static-site #publish

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "hostsmith": {
      "command": "npx",
      "args": [
        "-y",
        "@hostsmith/mcp-server"
      ]
    }
  }
}

Tools

List Hostsmith sites in the user's account. Returns each site's `siteId`, `subdomain`, `domain`, and current status - feed `siteId` into `get_site`, `deploy_files`, `deploy_create_upload`, or `delete_site`. This is the source of truth for "does the user already have a site at FQDN X" - call it before any create/deploy/delete to resolve the user's site reference. By default queries all data partitions and merges the results; pass `partition: "us"` or `"eu"` to limit the query.

List domains the user can host sites under. Returns shared hosting domains (e.g. `hostsmith.link`, available to everyone) and custom domains owned by the user's organization. Use this to pick a `domain` value before calling `create_site`. By default queries all partitions and merges; pass `partition` or `shared` to narrow.

Get the user's account: organization details (`orgId`, `orgName`), the calling user's home partition under `user.homePartition`, current subscription plan with its limits (max sites, max domains, storage, bandwidth), and current usage counts. Use to check how much headroom the user has before creating new sites or to confirm plan-tier features. Usage is summed across all partitions.

Get full details of a specific Hostsmith site by ID, including its public URL (`https://<subdomain>.<domain>`), current deployment status, and configuration. Use after `list_sites` to inspect a single site, or after `deploy_files` / `deploy_finalize` to confirm the site is live and grab the URL to share with the user. Defaults to the user's home partition; pass `partition` explicitly when the site lives in a different one (visible in `list_sites` output).

Create a new Hostsmith site and return its `siteId`, full URL, and configuration. Use when the user wants to publish or host new content and no suitable site already exists. After creation, deploy content with `deploy_files` (small inline text) or `deploy_create_upload` + `deploy_finalize` (binaries / files > ~1 MB, uploaded directly to S3). The site-resolution and confirmation flow is described in the global server instructions; the rules below are specific to this tool's parameters. `domain` MUST be one of the domains returned by `list_domains` for this user - never invent or assume one. The selected domain must be in `active` status; if it isn't, surface the problem to the user instead of attempting creation. `partition` passed to this tool MUST match the partition of the selected domain. Subdomain selection must respect the domain's capabilities from `list_domains`. To serve the bare apex, pass `subdomain: "www"` - only valid when the domain has `enableApexDomain: true` (typically custom domains the user owns). For any other subdomain, the domain must have `enableSubdomains: true`; shared hosting domains (e.g. `*.hostsmith.link`) and most custom domains have `enableApexDomain: false`, so a non-apex subdomain is required there. If the chosen domain doesn't support the kind of site the user asked for (apex vs subdomain), surface the conflict rather than silently picking something else.

Permanently delete a Hostsmith site and all of its deployed files. **Destructive - only call after explicit user confirmation.** The site URL becomes unreachable immediately and the content cannot be recovered. The user must pass `confirm: true` for the deletion to proceed; otherwise the call returns an error explaining the safeguard.

Publish in-memory file contents to a Hostsmith site without writing to disk. Use when you have just generated content (an HTML page, a report, JSON data) and the user wants it live. Returns the deployment version and status; call `get_site` afterwards if you need the public URL to share. The site must already exist - call `create_site` first if you do not have a `siteId`. Deploying to a site that already has content overwrites it - confirm overwrite with the user first.

Start a direct-to-S3 upload for binary or large files. Use this instead of `deploy_files` for binaries (PDF, image, video, zip) or any file > ~1 MB. The MCP server has no access to the user's filesystem and `deploy_files` ships content inline through Lambda (capped at ~6 MB JSON-RPC payloads); this tool returns presigned S3 PUT URLs so the file bytes flow directly from your environment to S3, never through the MCP server. **Bundle into a zip first when:** the upload contains more than 3 files OR any file is larger than ~1 MB. The fileWorker auto-extracts a single-zip upload after promotion, so subdirectories are preserved end-to-end and you avoid one PUT round-trip per file. Skip zipping only for the trivial single-small-file case (e.g. one HTML). Bash bundle-and-deploy template (the agent should adapt fileNames and the cleanup prompt): TMP=$(mktemp -d) zip -r "$TMP/site.zip" index.html styles.css img/ # add every file/dir to deploy SIZE=$(stat -c%s "$TMP/site.zip" 2>/dev/null || stat -f%z "$TMP/site.zip") # 1. call deploy_create_upload with { siteId, files: [{ fileName: "site.zip", fileSize: $SIZE }] } # 2. PUT $TMP/site.zip to the returned URL(s) per the protocol below, capturing ETag # 3. call deploy_finalize with { siteId, versionId, completions: [...] } # 4. ASK THE USER: "Deploy succeeded. Remove temp folder $TMP? [y/N]" # Only run `rm -rf "$TMP"` after explicit confirmation; otherwise leave it for them to inspect. Three-step protocol: 1. Call this tool with `{ siteId, files: [{ fileName, fileSize }] }`. Receive `{ versionId, files: { [fileName]: { uploadId, key, partUploadUrls: [{ part, url }], partSize, expiresAt } } }`. 2. For each file, slice the bytes into chunks of `partSize` and PUT each chunk to its `partUploadUrls[i].url`. **Capture the `ETag` response header from every PUT** - you will need it for finalize. Single-part (small file, one URL): `curl -D - -X PUT --data-binary @file.pdf "$URL"`, then grep the response headers for `ETag`. Multi-part with `dd` (no temp files; reads each chunk in place): count=$(jq ".files[\"large.zip\"].partUploadUrls | length" envelope.json) for i in $(seq 0 $((count-1))); do url=$(jq -r ".files[\"large.zip\"].partUploadUrls[$i].url" envelope.json) etag=$(dd if=large.zip bs=5M skip=$i count=1 status=none \ | curl -sS -D - -X PUT --data-binary @- "$url" \ | awk -F': ' 'tolower($1)=="etag"{print $2}' | tr -d '\r') echo "{ \"PartNumber\": $((i+1)), \"ETag\": $etag }" >> parts.json done Multi-part in Python - **prefer this over dd for files > ~50 MB** (parallel PUTs, no temp files, cleaner error handling): import json, requests from concurrent.futures import ThreadPoolExecutor env = json.load(open("envelope.json")) info = env["files"]["large.zip"] part_size = info["partSize"] def upload_part(p): with open("large.zip", "rb") as f: # own handle per thread f.seek((p["part"] - 1) * part_size) r = requests.put(p["url"], data=f.read(part_size)) r.raise_for_status() return {"PartNumber": p["part"], "ETag": r.headers["ETag"]} with ThreadPoolExecutor(max_workers=5) as ex: # cap concurrency at 5 parts = list(ex.map(upload_part, info["partUploadUrls"])) 3. Call `deploy_finalize` with `{ siteId, versionId, completions: [{ uploadId, key, parts: [{ ETag, PartNumber }] }] }` for every multi-part file. Single-part uploads (`uploadId` is empty in the start response) need no completion entry. The site must already exist - call `create_site` first if you do not have a `siteId`. Deploying overwrites existing content; confirm overwrite with the user first. If your host environment provides no HTTP-PUT capability (no bash/curl, no Python `requests`, no `fetch`), present the presigned URL(s) to the user with instructions to upload the file manually (curl or browser), then call `deploy_finalize` after the user confirms.

Commit a deploy started with `deploy_create_upload`. Pass the `versionId` from the start response and a `completions` array containing the agent-collected ETags for each multi-part file (single-part uploads - those whose start response had an empty `uploadId` - do not need a completion entry). Returns the live site URL on success. The site must belong to the authenticated user; bearer-token auth is re-validated server-side, so holding presigned URLs alone does not let an unrelated caller finalize.

Overview

What is Hostsmith?

Hostsmith is an official Model Context Protocol (MCP) server for the Hostsmith hosting platform. It enables agents to deploy file contents to a publicly accessible HTTPS URL within seconds, without requiring a repository or build step. It is designed for developers building agentic workflows that need instant static hosting.

How to use Hostsmith?

Configure the server in your MCP client using either a remote URL (https://mcp.hostsmith.net/mcp) or by running the stdio command npx -y @hostsmith/mcp-server. Authentication occurs via OAuth 2.0—no static tokens are supported. The first tool call triggers a browser-based OAuth flow to authorize the connection against your Hostsmith account. Environment variables such as HOSTSMITH_URL, HOSTSMITH_API_DOMAIN, and PORT can be used to customize the server.

Key features of Hostsmith

Deploy files to a live URL in seconds
No repository or build configuration required
Supports custom domains and private sites
Choose EU or US data residency
MCP-native with OAuth 2.0 authentication
Provides tools for site and domain management

Use cases of Hostsmith

Claude Code shipping an HTML report as a live URL
Cursor previewing a generated demo instantly
Claude Desktop publishing a one-pager
Uploading large binary files via direct-to-S3 upload
Deploying static sites without a CI pipeline

FAQ from Hostsmith

How does Hostsmith authenticate?

Authentication uses OAuth 2.0 exclusively. Static access tokens are not supported. The server triggers a browser-based OAuth flow on the first tool call.

Where does my data reside?

You can choose EU or US data residency. The partition argument in tool calls lets you control the region; if omitted, the partition is inferred from your access token.

What transport does Hostsmith use?

It supports Streamable HTTP (remote URL) and stdio (local command). The remote URL is https://mcp.hostsmith.net/mcp and the stdio command is npx -y @hostsmith/mcp-server.

What should I do if I get a 401 error?

A 401 response means the OAuth session has expired. Reconnect from your MCP client to re-authorize.

Can I customize the API endpoint?

Yes. Use the HOSTSMITH_API_DOMAIN environment variable to override the upstream API domain, or HOSTSMITH_BASE_URL to set a single fixed API base URL.