# Hostingsurge

> Hostingsurge is a hosting platform (similar to Vercel) for web apps, static sites, Docker images, WordPress sites, managed databases and email. AI agents can deploy, migrate and operate projects through an MCP server, a CLI and a REST API, authenticated with OAuth 2.1 sign-in (MCP clients) or a Bearer token.

Authentication: MCP clients that support OAuth (claude.ai and Claude Desktop custom connectors, ChatGPT developer mode, Claude Code, Cursor, VS Code) just add the MCP URL and the user signs in with Hostingsurge and approves the access. Otherwise create an API token in the Hostingsurge dashboard (Settings → Tokens; a token covers the whole team or selected projects) and send `Authorization: Bearer <token>`. Never ask the user to paste a token into a chat; put it in the client configuration or in the `HOSTINGSURGE_TOKEN` environment variable.

## MCP server (recommended for AI clients)

- Endpoint: `https://hostingsurge.com/mcp` — MCP Streamable HTTP, stateless: JSON-RPC 2.0 over POST, JSON responses, no session id. Header: `Authorization: Bearer <token or OAuth access token>`.
- claude.ai / Claude Desktop: Customize → Connectors → Add custom connector → URL `https://hostingsurge.com/mcp` → Connect → sign in to Hostingsurge → Allow access.
- ChatGPT (developer mode): create an app for `https://hostingsurge.com/mcp` with OAuth authentication → sign in to Hostingsurge → Allow access.
- Claude Code: `claude mcp add --transport http hostingsurge https://hostingsurge.com/mcp` then `/mcp` → Authenticate (or add `--header "Authorization: Bearer <token>"`).
- Cursor / Windsurf / generic clients: `{"mcpServers": {"hostingsurge": {"type": "http", "url": "https://hostingsurge.com/mcp", "headers": {"Authorization": "Bearer <token>"}}}}` (Windsurf uses `serverUrl` instead of `url`; Cursor and VS Code sign in with OAuth when `headers` is left out).
- OpenAI Codex CLI: `codex mcp add hostingsurge --url https://hostingsurge.com/mcp --bearer-token-env-var HOSTINGSURGE_TOKEN`
- OAuth 2.1: discovery from the 401 (`WWW-Authenticate: Bearer resource_metadata=…`), RFC 9728 → RFC 8414 metadata at `https://hostingsurge.com/.well-known/oauth-authorization-server`, dynamic client registration or Client ID Metadata Documents, authorization code with PKCE S256, resource indicator `https://hostingsurge.com/mcp`, rotating refresh tokens.
- Tools (`tools/list` returns the full input schemas):
  - Account: whoami
  - Projects: list_projects, get_project, list_templates, create_project, update_project, project_action, delete_project
  - Deployments and logs: deploy_project, deploy_files, list_deployments, get_deployment, get_build_logs, get_runtime_logs, cancel_deployment, rollback_deployment
  - Environment variables: list_env, set_env, delete_env
  - Domains: list_domains, add_domain, verify_domain, remove_domain
  - Databases: list_databases, create_database, get_database, update_database_public_access, get_database_backup_schedule, upsert_database_backup_schedule, delete_database_backup_schedule, run_database_backup_now, list_database_backup_executions, restore_database
  - WordPress: get_wordpress_status, update_wordpress, get_wordpress_auto_update, update_wordpress_auto_update, get_wordpress_hardening, update_wordpress_hardening, get_wordpress_health, reset_wordpress_admin_password, list_wordpress_backups, create_wordpress_backup, restore_wordpress_backup, get_wordpress_backup_schedule, update_wordpress_backup_schedule
  - Automation (cron jobs, one-off commands, deploy hooks, push-to-deploy): list_cron_jobs, create_cron_job, update_cron_job, delete_cron_job, run_cron_job_now, run_command, list_deploy_hooks, create_deploy_hook, delete_deploy_hook, project_webhook_status, rotate_project_webhook, delete_project_webhook
  - Preview deployments (branch previews): list_previews, deploy_preview, delete_preview
  - Import / migrate an existing site, app or database: migration_start, migration_status, migration_cutover
  - Email (mailboxes and transactional sending): email_domain_add, email_domain_status, email_mailbox_create, email_mailbox_list, email_alias_create, email_sending_request, email_send
  - AI builder (build a site or app from a prompt): builder_start, builder_message, builder_status, builder_publish
  - Notifications and uptime monitoring: list_notifications, get_uptime, list_incidents
- Projects can be referenced by id, slug or exact name. `deploy_files` deploys generated code without Git (send the complete file set; up to 1000 files / 8 MiB). `delete_project` requires `confirm` equal to the exact project name. Secret values are write-only. Sending email is off for a team until a platform operator approves `email_sending_request`.

## CLI (for terminals, CI and coding agents)

- Run: `npx -y --package=https://hostingsurge.com/cli/hostingsurge.tgz hostingsurge <command>` (bins `hostingsurge` and `hs`; the package is not on npm yet, so it installs from this tarball — once published, `npx hostingsurge <command>` works directly). Install once instead of using npx every time: `npm i -g https://hostingsurge.com/cli/hostingsurge.tgz`. Authenticate with `HOSTINGSURGE_TOKEN=<token>` or `hostingsurge login --api https://hostingsurge.com/api/v1`.
- Deploy a directory: `hostingsurge deploy [dir] --name <project> --json` (creates or reuses the project, uploads the files, waits for the build, prints the URL; exit code 1 if the deployment fails).
- Import an existing site: `hostingsurge import git|vercel|netlify|wordpress|db|snapshot|cpanel|sftp <source>`, then `import status <id> --follow` and `import cutover <id> <hostname>` (see `hostingsurge help import`).
- Email: `hostingsurge email domains|mailboxes|sending|send` (see `hostingsurge help email`). WordPress, databases, cron jobs, deploy hooks and push-to-deploy: `hostingsurge wordpress|databases|cron|hooks|webhook` (see `hostingsurge help <command>`). Notifications and uptime: `hostingsurge notifications ls|webhooks`, `hostingsurge uptime status|history|incidents` (see `hostingsurge help notifications` / `help uptime`).
- Other commands: `projects`, `link`, `logs [--build <id|latest>] [--follow]`, `env ls|add <KEY> [value|-]|rm <KEY>|pull [file]`, `domains ls|add <host>|verify <host>|rm <host>`, `open`, `whoami`. Add `--json` for machine-readable output and `--yes` to confirm destructive actions without a TTY.
- Never uploaded: node_modules/, .git/, .next/, dist/, .env* and anything in .gitignore or .hostingsurgeignore.

## REST API

- Base URL: `https://hostingsurge.com/api/v1`
- OpenAPI: [openapi.json](https://hostingsurge.com/api/v1/openapi.json): projects, deployments, build and runtime logs, environment variables, domains, databases, automation (cron jobs, deploy hooks, push-to-deploy webhooks), migrations, email, templates, usage.
- Errors: `{"error": {"code": "...", "message": "..."}}`; `not_configured` means a platform administrator must finish the setup (retrying will not help).

## Typical workflows

- Deploy a Git repository: create_project {name, sourceType: "git", repoUrl, branch} → get_deployment {deploymentId, waitSeconds: 20}.
- Deploy generated code: deploy_files {name, files: [{path, content}]} → get_deployment.
- Custom domain: add_domain {project, hostname} → give the user the returned DNS records → verify_domain.
- Debug a failed build: get_deployment {project} → get_build_logs {project, tail: 200} → fix code, settings (update_project) or env (set_env) → deploy_project.
- Roll back: list_deployments {project} → rollback_deployment {deploymentId}.
- Move a site to Hostingsurge: migration_start {source} → migration_status until it is live on its preview URL → migration_cutover {hostname} → give the user the DNS records to change (mail records stay untouched).
- Mailboxes for a domain: email_domain_add {domain} → give the user the DNS records → email_domain_status → email_mailbox_create.
- Build from a prompt: builder_start {prompt} → builder_message {sessionId, message} for changes → builder_status → builder_publish.

## Optional

- [MCP endpoint](https://hostingsurge.com/mcp): POST only; GET returns 405.
- [OAuth protected resource metadata](https://hostingsurge.com/.well-known/oauth-protected-resource/mcp): the MCP resource, its authorization server and scopes.
- [OAuth authorization server metadata](https://hostingsurge.com/.well-known/oauth-authorization-server): authorize, token, register and revoke endpoints.