Windsurf + xCloud

Install one-click apps with Windsurf on xCloud

Installing one-click apps with Windsurf means asking the Devin Local agent in your editor to find an app in the xCloud catalogue, check that a server can run it, install it after your confirmation and give you the address, while your project stays open beside it.

Skill: xcloud:deploy
Toolsets: oneclick-apps, catalog, servers
Free with every xCloud account

Set up Windsurf All Windsurf guides

YouInstall Uptime Kuma on the Frankfurt server, staging hostname.

oneclickApps_compatibilityread-only

AgentFrankfurt meets the stack and runtime requirements and is running. The resource check was inconclusive: no monitoring data yet. Install Uptime Kuma on a free staging hostname?

YouDo it.

oneclickApps_installneeds approval

AgentThe install finished all four phases. Uptime Kuma is up on your staging hostname.

Last updated: October 2026. Keep a human in the loop: xCloud stops and asks before anything that creates, deploys, updates, reboots, deletes or buys.

Setup

How Do You Set Up Windsurf to Install one-click apps on xCloud?

Connect Windsurf once; every job on this account uses the same connection. Then ask in plain words.

1
Add xCloud to the Devin Local agent
New tabs in Devin Desktop use the Devin Local agent, which reads MCP servers from the Devin CLI config files. Run this in a terminal: the URL is treated as Streamable HTTP, and the second command opens the browser for the xCloud sign-in (the agent also prompts on first use). By default the entry lands in .devin/mcp_config.local.json for the current project; add -s user to the first command to share it across projects in ~/.config/devin/mcp_config.json, where the entry reads url plus transport http.
Shell
```
devin mcp add xcloud https://app.xcloud.host/mcp
devin mcp login xcloud
```
2
Or edit the legacy Cascade config
If your tab runs the legacy Cascade agent, click the three-dot menu in the Cascade panel, then the Open MCP config file icon in the MCPs section, and add this under mcpServers. Cascade allows 100 tools in total and the full xCloud server offers 188 operations plus two search tools, so point serverUrl at the compact profile, five tools that reach every operation through search and call; a single toolset such as ?toolsets=sites (60 tools) also fits, but sites and servers together are 121 tools. Windsurf's file has been at ~/.codeium/windsurf/mcp_config.json, and the current documentation lists ~/.config/devin/mcp_config.json on macOS and Linux and %APPDATA%\devin\mcp_config.json on Windows; the icon opens the one your version reads.
JSON
```
{
  "mcpServers": {
    "xcloud": {
      "serverUrl": "https://app.xcloud.host/mcp?profile=compact"
    }
  }
}
```
3
No browser sign-in? Use an API key
Create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things in Settings, Developers, API Tokens, export it as XCLOUD_TOKEN and add a headers field to the xcloud entry. Both agents fill in the ${env:XCLOUD_TOKEN} reference from your environment, so the token itself stays out of the file. The Devin Local entry is shown; for Cascade the same headers field sits beside serverUrl.
JSON
```
"xcloud": {
  "url": "https://app.xcloud.host/mcp",
  "transport": "http",
  "headers": {
    "Authorization": "Bearer ${env:XCLOUD_TOKEN}"
  }
}
```

Check it worked

Then ask Windsurf for the job itself, for example:

Prompt

Use xCloud to check whether Ghost fits my Frankfurt server and tell me if the resource check was inconclusive.

In practice

How Does One-click apps Work from Windsurf?

In Windsurf you are usually in the middle of something else, and the agent chat is where the request goes. A typical case: you are building a site and want an uptime monitor or a blog running on your own server. Type the app name and the server, and the Devin Local agent calls the catalogue search, then the install form, and replies in the chat with what the app needs. Because the work happens on a server and not in your project, it does not touch your files for this job. It uses the xCloud tools only, and the tool calls appear in the chat as they run.

Connecting is short: devin mcp add xcloud https://app.xcloud.host/mcp, then devin mcp login xcloud. Devin Local has no documented tool cap, so the full URL works. The tool budget is a wrinkle only if your tab runs the legacy Cascade agent, which allows 100 tools in total across your MCP servers, so most people point it at the compact URL. If the install tools do not show up in Cascade's tool list with the compact profile, widen its entry to ?toolsets=oneclick-apps,catalog,servers, which loads the catalogue, the install and lifecycle tools and the server list and leaves everything else out. After that the flow is the usual one: the agent lists your servers, asks which one, runs the compatibility check and reports stack, runtime, state, billing and the RAM, CPU and disk verdict. A missing monitoring reading comes back as inconclusive, never as a pass.

Approval happens in two places. Devin Local asks before an MCP tool runs by default, and xCloud refuses the install unless it carries an explicit confirmation, so the agent restates the app, server and address and asks you once before sending it. Then it polls the install status and tells you when the app is ready. If the prompts for reads get tedious, Devin Local's permissions allow, deny and ask lists take patterns such as mcp__xcloud__* or a single tool name, and xCloud's own confirmation for the install applies either way.

Windsurf specific: Team admins decide which servers an agent may use. For legacy Cascade, once an admin allowlists even one MCP server every server not on the list is blocked, and the server ID has to match the key name, xcloud, exactly, otherwise the install tools never appear and the request fails before it reaches xCloud. Devin Local can instead be restricted to a team MCP registry, so in a team ask your admin whether xcloud is allowed before you spend time debugging the config. Where the entry lives also depends on the agent: Devin Local reads the Devin CLI config files, and Cascade opens its file from Open MCP config file in the Cascade panel menu.

What xCloud does for one-click apps

xCloud lists the one-click catalogue, checks whether an app fits a given server, installs it once you approve and reports each install phase until it finishes. Afterwards the agent can fetch the login details and stop, start or redeploy the app. A few apps install only from the dashboard, and the agent tells you where to click.

Find the app. The agent searches the catalogue by name or purpose and shows what it found. An empty catalogue means the list has not synced on that environment, so the agent never answers that an app does not exist from an empty list.
Read the install form. The agent reads the app's fields. Fields xCloud generates for you can be left out. For the address you choose a free xCloud staging hostname or your own domain, and a live domain needs the full site name.
Check the server fits. You name the server, or the agent lists yours and asks. The compatibility check covers the server stack, runtime, state, billing and RAM, CPU and disk against the latest monitoring snapshot. If monitoring data is missing the resource check was skipped, and the agent says the result is inconclusive.
Approve and install. The agent restates the app, the server and the address, and asks once. On your yes it sends the install with an explicit confirmation and an idempotency key, so a retried request cannot create a second copy.
Poll the install. The agent polls the install status every five to ten seconds until it is terminal. A failure names its phase: pre_install, install, post_install or provisioning, so you know where it stopped.
Hand over and manage. The agent gives you the URL. It fetches the login details only when you ask, shows them once in the reply and tells you to store them in a password manager. Later it can stop, start, restart or redeploy the app after your approval.

Reference

One-click apps Settings and Limits on xCloud

The facts Windsurf works within when it installs one-click apps. Where a row names the dashboard, that step stays yours to take there.

Setting or limit	What applies
Catalogue	Searchable by name. It holds hundreds of apps, and most run on a Docker server. Public facts such as supported stacks and minimum size come from the catalogue listing
Compatibility check	Per server: stack, runtime, server state, billing and RAM, CPU and disk. monitor_available set to false means the resource check was skipped, not passed
Too-small servers	A server that is too small stays too small. The agent suggests a larger server instead of retrying the install
Stack requirements	An app that needs another stack is refused with a 422 that reads "This app requires a ... server. This server is on the ... stack."
Dashboard-only installs	n8n, Supabase, Nextcloud, Mautic, LibreChat, Open WebUI, Ollama, Umami, WireGuard, phpMyAdmin and Site.pro. The API answers 404 for these eleven; install them from Add site, One-Click Apps in the dashboard
Address	Staging hostname for a free xCloud address, or go live with your own domain. A demo site promoted to a live domain cannot return to the demo address
Idempotency	The install carries an Idempotency-Key, so a retried request cannot create a duplicate site
Install phases	pre_install, install, post_install and provisioning. is_terminal marks the end, and failed_phase says where a failure happened
Credentials	Read on request and shown once in the reply. Some apps have none to read because you create the first admin inside the app
Lifecycle	Stop, start, restart and redeploy run synchronously. Stop takes the app offline and redeploy recreates its containers. Both answer 422 while an install is running or after a failed install
Agentic servers	An OpenClaw, Hermes, Paperclip or DeepSeek Harness server never takes a one-click app

Rules Windsurf has to follow

Installing, stopping and redeploying an app stop for your approval; browsing the catalogue and the compatibility check never change anything.
A missing resource reading is reported as inconclusive, never as a pass.
Login details are shown once, only when you ask, and never repeated in a summary or a later message.
For the eleven dashboard-only apps the agent checks that the server fits, then gives you the dashboard path instead of trying the install.
A failed install is not retried blindly: the agent names the failed phase and reads the site's recent events first.

Example prompts

What Can You Ask Windsurf to Do for One-click apps?

Type these as written and swap in your own repository, site and server names. Reads and routine actions such as backups, cache purges, PageSpeed scans and vulnerability scans run straight away; creating, deploying, updating, rebooting, deleting, buying or starting a broken-link scan stops and asks first.

Prompt

Use xCloud to check whether Ghost fits my Frankfurt server and tell me if the resource check was inconclusive.

Prompt

Install Uptime Kuma on the Frankfurt server with a staging hostname. Show me the app, server and address before you send it.

Prompt

The Uptime Kuma install on Frankfurt failed. Which phase failed, and what do the recent events say?

Prompt

Which one-click apps are compatible with my Frankfurt server?

Prompt

Search the one-click catalogue for a self-hosted blog and tell me what each result needs from a server.

Prompt

Install Uptime Kuma on the Frankfurt server on a staging hostname, wait until it is ready, then give me the login details.

Prompt

Check whether Immich fits my Amsterdam server before I install it, and tell me if the resource check was inconclusive.

Prompt

I want n8n on my Frankfurt server. Check that the server fits, then tell me where to click to install it.

Prompt

The Uptime Kuma install on the Frankfurt server failed. Which phase failed, and what do the recent events say?

Prompt

Redeploy the Ghost app on blog.example.com, but tell me what a redeploy does before you run it.

Windsurf and One-click apps: Frequently Asked Questions

What people ask before they let Windsurf install one-click apps through xCloud.

Why can Windsurf not find the one-click install tools?

Check the agent and the config first. Devin Local reads the Devin CLI config files, so run devin mcp add xcloud https://app.xcloud.host/mcp, then sign in with devin mcp login xcloud. On the legacy Cascade agent the connection may be too narrow, so try ?toolsets=oneclick-apps,catalog,servers on the serverUrl. On a team plan, also check that your admin allowlisted a server named xcloud or added it to the team registry.

Does the agent change my project files when it installs a one-click app?

No. A one-click app is installed on your xCloud server, not in your repository. The agent only calls xCloud tools for this job, so your open files stay as they are.

Can an agent install any app in the one-click catalogue?

Most of them. Eleven apps install only from the dashboard: n8n, Supabase, Nextcloud, Mautic, LibreChat, Open WebUI, Ollama, Umami, WireGuard, phpMyAdmin and Site.pro. For those the agent checks that your server fits and points you to Add site, One-Click Apps.

How does the agent know an app will fit my server?

It runs the compatibility check for that server, which covers the stack, runtime, server state, billing and the RAM, CPU and disk readings from the latest monitoring snapshot. If monitoring data is missing, the agent tells you the resource check was inconclusive.

What does a 422 during an app install mean?

Usually that the app needs a different server stack than the one you picked, and the message names both. Pick a server on the required stack. A 422 on stop, start or redeploy means an install is still running or the last install failed.

Where do the login details for a one-click app come from?

The agent can read them from xCloud when you ask and shows them once in the reply. Store them in a password manager. Some apps have no generated login because you create the first administrator inside the app.

Can an agent stop or restart a one-click app?

Yes. Stop, start, restart and redeploy are available, and they run straight away once you approve. Stop takes the app offline and redeploy recreates its containers, so the agent asks before either.

Other agents