Hostsmith MCP Server

Overview Schema Source Related Servers Discussions Admin

create_site

Destructive

Create a new Hostsmith site and return its siteId, full URL, and configuration so users can publish or host new content when no suitable site exists.

Instructions

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.

Pass kind: "redirect" to create a redirect host instead of a site: it serves only redirect rules, set afterwards with set_redirects or add_redirect, and takes no deploys. Its domain must be a custom domain the organization owns (shared: false in list_domains). On a domain with enableApexDomain: true, a redirect host at subdomain: "www" also forwards the bare apex, which first redirects to www and then follows the host's rules.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "domain": "<domain>"
    },
    "name": "create_site"
  }
}

Input Schema

Name	Required	Description
`kind`	No	Omit, or pass "site", for a site that serves deployed files. Pass "redirect" for a redirect host: it serves only redirect rules, needs a custom domain the organization owns, and doesn't count toward the plan's site limit (up to 50 per organization). Fixed at creation.
`domain`	Yes	Parent domain for the site, MUST be one returned by `list_domains` for this user. Examples: "us.hostsmith.link", "eu.hostsmith.link", or a custom domain the user owns. Do not invent domains.
`partition`	No	Data partition for the new site. Must match the partition of the selected domain.
`subdomain`	No	Subdomain prefix; auto-generated if omitted. Lowercase alphanumeric with hyphens only - no dots, uppercase, or underscores. Pass `subdomain: "www"` only when the chosen `domain` has `enableApexDomain: true` in `list_domains` (creates the canonical site at `www.<apex>` with the bare apex redirecting to it). For any other subdomain the chosen `domain` must have `enableSubdomains: true`.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.8.0Nov 12, 2026

addedInput schema / properties / kind

Added value: +{
+  "description": "Omit, or pass \"site\", for a site that serves deployed files. Pass \"redirect\" for a redirect host: it serves only redirect rules, needs a custom domain the organization owns, and doesn't count toward the plan's site limit (up to 50 per organization). Fixed at creation.",
+  "enum": [
+    "site",
+    "redirect"
+  ],
+  "type": "string"
+}

First observedv1.5.2Jun 23, 2026

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare destructiveHint=true, so the description usefully adds preconditions the annotation cannot convey: the domain must come from `list_domains`, must be `active`, the partition must match, and capability flags (`enableApexDomain`/`enableSubdomains`) gate subdomain choice. It also discloses that redirect hosts take no deploys and do not count toward the site limit. However, it says nothing about failure modes beyond domain status (e.g. name collisions, quota exceeded on regular sites) or whether a partially created site is rolled back.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: purpose, trigger, follow-up tools, then a parameter-rules block. It is long and repeats several schema descriptions nearly verbatim (the `www`/`enableApexDomain` rule appears in both prose and schema), which is the main trimming opportunity, but no sentence is entirely wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with no output schema, the description still names the return payload (`siteId`, URL, configuration) and covers every parameter plus the apex/shared-domain edge cases. An agent has enough to choose a valid domain/subdomain combination or correctly refuse and surface the conflict to the user.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already carries a description, so the baseline would be 3; the prose earns above that by explaining cross-parameter dependencies (partition must match domain, subdomain must respect the domain's capability flags) and the `www`/apex special case that the schema only states tersely. It loses a point because it largely restates schema text rather than adding new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+return contract: "Create a new Hostsmith site and return its `siteId`, full URL, and configuration." It also disambiguates the alternate mode (`kind: "redirect"` creates a redirect host, not a site), so an agent can distinguish the two behaviors this one tool performs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the trigger condition explicitly ("Use when the user wants to publish or host new content and no suitable site already exists") and routes post-creation work to named siblings: `deploy_files` for small inline text, `deploy_create_upload` + `deploy_finalize` for binaries/large files, and `set_redirects`/`add_redirect` for redirect hosts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server