Skip to main content

Hostsmith

Docs FAQ

FAQ

Why OAuth-only - can I just use an API key?

The MCP server is designed for human-in-the-loop agent workflows, where the user explicitly approves what the agent can do. OAuth gives per-user consent, short-lived tokens, and revocability without rotating shared secrets. If you need non-interactive automation, use the REST API directly with OAuth-issued tokens.

How do I rotate tokens?

You don't need to. Access tokens last 1 hour and your MCP client refreshes them silently. Refresh tokens rotate on every refresh - the old one is invalidated automatically.

To force a fresh token, revoke access and reconnect.

Where are my MCP credentials stored?

In your client's local credential store, not in your MCP config file. Exact paths vary by client; common locations:

  • Claude Desktop: macOS Keychain / Windows Credential Manager / Linux Secret Service.
  • stdio clients (Claude Code, Cursor, etc.): ~/.config/<client>/<server>/oauth.json or similar.

The MCP server itself is stateless - it does not store credentials.

Where do I find logs to troubleshoot?

  • Claude Desktop: the connector view shows recent MCP traffic; system logs are in the macOS Console app or the equivalent on Windows / Linux.
  • stdio clients: most clients write MCP server stderr to a log file (e.g. Claude Code: ~/.claude/logs/). Check your client's docs.
  • Self-hosted (npx @hostsmith/mcp-server http): logs go to the terminal where you started the process. Set DEBUG=* for verbose output.
  • Inspect interactively: npx @modelcontextprotocol/inspector npx -y @hostsmith/mcp-server http opens a UI for tool calls.

EU vs US - which partition should I use?

Both partitions offer the same product. Pick based on where you need the user's data to live:

  • EU partition for GDPR-sensitive workloads or any user request that says "EU residency".
  • US partition for everything else, including users with no specific residency requirement.

Your home partition is set when you sign up. Per-call, pass partition: "us" or partition: "eu" to override. See Data partition selection.

My custom domain isn't active - what now?

Custom domains require DNS validation: you add records at your registrar, and Hostsmith provisions an ACM certificate and CDN routing. Until that completes, list_domains shows the domain as validating or provisioning and create_site will refuse it.

Status flow: VALIDATING → PROVISIONING → ACTIVE | FAILED. Track progress in the Hostsmith app. Only call create_site against domains in ACTIVE status.

Can I use the MCP server in CI?

Technically yes, but only after a one-time interactive OAuth in the same environment. CI is a poor fit for OAuth-with-browser-redirect; use the REST API directly with a stored OAuth token instead.

How do I disconnect / reconnect?

  • Claude Desktop: Settings → Connectors → remove and re-add the connector.
  • stdio clients: delete the cached OAuth credentials and remove the hostsmith entry from your MCP config; the next first call re-authorizes.
  • Globally: sign in to hostsmith.net, revoke the OAuth client from account settings - this kills tokens for that client across every machine.

Does the MCP server have access to my filesystem?

No. The MCP server is a process that talks to your client over stdio (or HTTP) and to the Hostsmith API over HTTPS. Your agent reads local files and passes their contents to deploy_files (inline) or to deploy_create_upload + direct S3 PUT (out of band). The MCP server never touches your disk.

Do MCP deploys overwrite existing content?

Yes. A successful deploy_files or deploy_create_upload + deploy_finalize replaces the previous version of the site. Confirm overwrite with the user before deploying anything you don't want to lose.

What about access controls (passwords, allowlists)?

Configure them once in the Hostsmith app. They persist across deploys. The MCP server does not currently expose access-control tools.

Where do I report issues?

Previous Limits and errorsNextDevelopers