Tools

The Hostsmith MCP server exposes nine tools across four areas: account, sites, domains, and deploys. All tools accept an optional partition argument; omit it to use your home partition.

Account

get_account

Get the user's organization (orgId, orgName), the calling user's home partition under user.homePartition, the current subscription plan with its limits (max sites, max domains, storage, bandwidth), and current usage counts. Usage is summed across all partitions.

Inputs: none.

Output: account object including orgId, orgName, user.homePartition, plan (with limits), and usage.

Example prompt:

Show my Hostsmith plan and how many sites I have left.

Sites

list_sites

List sites in the user's account. Returns each site's siteId, subdomain, domain, and current status. The result 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; pass partition to limit.

Inputs:

Output: array of site summaries.

Example prompt:

Do I already have a site for demo.hostsmith.link?

get_site

Get full details of one 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 a deploy to grab the URL.

Inputs:

Output: site object with URL, status, and config.

Example prompt:

What's the public URL of the site I just created?

create_site

Create a new site under one of the domains returned by list_domains. Returns the new siteId, full URL, and configuration. After creation, deploy content with deploy_files (small inline text) or deploy_create_upload + deploy_finalize (binaries or files > ~1 MB).

Constraints:

• domain MUST be a domain returned by list_domains for this user. Never invent one.
• The selected domain must be in active status.
• partition passed here MUST match the partition of the selected domain.
• To serve the bare apex, pass subdomain: "www" - only valid when the domain has enableApexDomain: true.
• For any other subdomain, the domain must have enableSubdomains: true.

Inputs:

Output: site object with siteId and URL.

Example prompt:

Create a site under us.hostsmith.link and call it weekly-report.

delete_site

Permanently delete a site and all of its deployed files. Destructive - the URL becomes unreachable immediately and content cannot be recovered. The agent must pass confirm: true after explicit user confirmation.

Inputs:

Output: confirmation message including the URL that was retired.

Example prompt:

Delete the site weekly-report-old. Yes, I'm sure.

Domains

list_domains

List the domains the user can host sites under: shared hosting domains (e.g. us.hostsmith.link, eu.hostsmith.link, available to everyone) and custom domains owned by the user's organization. Use to pick a domain value before calling create_site. Each entry includes enableApexDomain and enableSubdomains flags - check them before constructing a subdomain.

Inputs:

Output: array of domain summaries with enableApexDomain, enableSubdomains, partition, and status.

Example prompt:

Which custom domains can I deploy to in the EU partition?

Deploys

deploy_files

Publish in-memory file contents to a site without writing to disk. Use when the agent has just generated content (HTML page, JSON, short text). 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 overwrites existing content; confirm with the user first.

When to use: small text artifacts, total payload up to ~1 MB. For binaries or larger payloads, use deploy_create_upload instead.

Inputs:

Output: Deployed N file(s). Version: <id>, Status: <status>.

Example prompt:

Deploy this HTML to my site as index.html.

deploy_create_upload

Start a direct-to-S3 upload for binary or large files. Returns versionId plus presigned S3 PUT URLs per part. Use this instead of deploy_files for binaries (PDF, image, video, zip) or any file larger than ~1 MB.

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, preserving subdirectories end-to-end and avoiding one PUT round-trip per file.

Three-step protocol:

1. Call deploy_create_upload with { siteId, files: [{ fileName, fileSize }] }. Receive { versionId, files: { [fileName]: { uploadId, key, partUploadUrls, partSize, expiresAt } } }.
2. For each file, slice bytes into partSize chunks and PUT each chunk to its partUploadUrls[i].url. Capture the ETag response header from every PUT - you need it for finalize.
3. Call deploy_finalize with the collected ETags.

Inputs:

Output: envelope with versionId and per-file uploadId, key, partUploadUrls, partSize, expiresAt.

Example prompt:

Upload this 12 MB PDF to my report site at report.pdf.

deploy_finalize

Commit a deploy started with deploy_create_upload. Pass the versionId from the start response and a completions array with 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.

Inputs:

Output: live site URL.

Example prompt:

The uploads are done - finalize the deploy.

For the canonical Zod schemas and runtime descriptions, read src/index.ts in the mcp-server repo. The descriptions there are what your agent sees at tool-discovery time.