Clients

The Hostsmith MCP server is published as @hostsmith/mcp-server on npm and hosted at https://mcp.hostsmith.net/mcp. Every supported client uses one of four transports.

Claude Desktop

1. Open Settings → Connectors → Add custom connector.
2. Paste the URL:

   https://mcp.hostsmith.net/mcp
   

3. Save. Claude Desktop runs the OAuth flow in your browser to authorize the connector against your Hostsmith account.

To revoke, remove the connector from Claude Desktop. To force a re-auth, remove and re-add it.

Stdio (Claude Code, Cursor, Cline, Windsurf, Zed)

Add this entry to your client's MCP config:

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

Config file locations:

The first tool call triggers an OAuth flow in your browser to authorize the server against your Hostsmith account. The token is cached locally; subsequent calls reuse it.

Remote URL (other Streamable-HTTP clients)

Any MCP client that supports remote Streamable HTTP transport can point directly at the hosted server:

{
  "mcpServers": {
    "hostsmith": {
      "url": "https://mcp.hostsmith.net/mcp"
    }
  }
}

The client handles the OAuth flow automatically - you'll be redirected to Hostsmith to authorize access.

Local HTTP (self-hosted)

Run the server in HTTP mode locally and have your MCP client perform OAuth against it:

npx @hostsmith/mcp-server http

{
  "mcpServers": {
    "hostsmith": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

Useful when you want to inspect MCP traffic locally or pin to a specific server version. Set MCP_BASE_URL to override the public URL the server advertises in OAuth metadata. See the README for the full env var list.

Troubleshooting

• Tool calls return 401. The OAuth session expired. Reconnect from your client to re-authorize.
• OAuth redirect loops (self-hosted only). Confirm MCP_BASE_URL matches the URL your MCP client uses to reach the server.
• Wrong partition. Tool calls accept an explicit partition argument; if you omit it, the partition is inferred from your access token. See Authentication.
• Inspect tools interactively. Run npx @modelcontextprotocol/inspector npx -y @hostsmith/mcp-server http to browse the tool surface in a local UI.
• Stale npm cache. If you keep getting an old version, run npx clear-npx-cache or npm cache clean --force and try again.