Authentication

The Hostsmith MCP server authenticates exclusively via OAuth 2.0. There are no static API tokens, and you never paste a secret into your client config.

Why OAuth-only

• Per-user consent. The user explicitly approves the scopes the agent gets - no shared admin keys.
• Short-lived credentials. Access tokens last 1 hour; the client refreshes silently.
• Revocable. You can disconnect from your Hostsmith account at any time without rotating any other credential.
• No leakage in logs. Bearer tokens never appear in MCP config files, repo history, or terminal output.

If you need a non-interactive integration (CI, backend service), use the REST API directly with OAuth-issued tokens. The MCP server is designed for agent + human-in-the-loop flows.

What happens on first use

1. Your MCP client connects to the Hostsmith server (stdio, remote URL, or local HTTP).
2. On the first tool call, the server redirects your browser to Hostsmith.
3. You sign in, review the requested scopes, and approve.
4. The server stores a short-lived access token plus a refresh token in your client's local credential store.
5. Subsequent tool calls use the cached token. The client refreshes silently when it expires.

The OAuth flow itself is the same Authorization Code + PKCE flow used by the REST API - the Developers › Authentication page documents it in detail.

Scopes

The MCP server requests the scopes it needs to expose its full tool surface:

You see and approve these on the consent screen. Approval is per-user, not per-machine - if you authorize once, the same Hostsmith account is reachable from every client where you connect the MCP server.

Data partition selection

Hostsmith stores user data in regional data partitions (us, eu). Every MCP tool that touches partition-scoped data accepts an optional partition argument:

• Omit it and the server uses your access token's home partition (set when you first signed up).
• Pass partition: "us" or partition: "eu" to target a specific one.
• A few tools (list_sites, list_domains, get_account) query both partitions in parallel and merge the results when you omit partition.

get_account returns your home partition under user.homePartition, so an agent can confirm where new sites land by default.

Revoking access

• Claude Desktop: Settings → Connectors → remove the Hostsmith connector.
• Stdio clients: delete the cached credentials at the path your client reports (typically ~/.config/<client>/<server>/oauth.json) and remove the hostsmith entry from the MCP config.
• From your Hostsmith account: sign in to hostsmith.net and revoke the OAuth client from your account settings. This invalidates every token issued to that client across every machine.

After revocation the next tool call returns 401 and your client opens the consent flow again.

Token rotation and TTLs

• Access tokens expire after 1 hour.
• Refresh tokens are valid for 90 days from the original authorization. After 90 days of inactivity, you re-authorize through the consent flow.
• Refresh tokens rotate: each refresh issues a new refresh token and invalidates the old one. Your MCP client handles this automatically.

Common issues

• "Tool calls return 401." The session expired. Reconnect or re-add the server in your client to re-authorize.
• "My agent created a site in the wrong partition." Pass partition explicitly or call get_account first to confirm homePartition before creating.
• "I want to switch the home partition." Home partition is set at sign-up and is not user-changeable today. Pass partition per-call instead.