Windsurf + xCloud

Troubleshoot a broken site with Windsurf on xCloud

Troubleshooting with Windsurf means asking the Devin Local agent in your editor why a site returns a 500 or a 502, and having it read xCloud's status, events and web server logs next to the code it can already see.

Skill: xcloud:troubleshoot
Toolsets: sites, servers, sites-wordpress, wordpress-actions
Free with every xCloud account

Set up Windsurf All Windsurf guides

Youblog.example.com shows a critical error. Find the cause before you touch anything.

sites_statusread-only

sites_eventsread-only

AgentStatus is normal. A plugin update task on blog.example.com finished with an error at 09:58, two minutes before the first 500. I will read the error log for the exact line.

sites_access-logsread-only

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 Troubleshoot a broken site 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

shop.example.com returns 500. Use xCloud to check its status, recent events and nginx error log, then tell me the cause with the log line.

In practice

How Does Troubleshooting Work from Windsurf?

In Windsurf you are already in the project when the alert arrives, so the first move is to type the symptom into the agent chat: shop.example.com is returning 500, find the cause before you change anything. The agent reaches xCloud through the xcloud entry in the Devin CLI config, and each call appears in the chat as a tool card you can expand to see what came back. It begins with sites_status, because a site that is still provisioning or whose last deploy failed explains the error on its own, then reads sites_events for tasks that failed just before the break. These are reads, so xCloud runs them without a prompt. Devin Local asks before an MCP tool runs by default, which is the agent's own check and not xCloud's. If the prompts slow an investigation, its permissions allow list takes patterns such as mcp__xcloud__sites_status.

The editor context is what makes the log read useful. When the nginx error log comes back with a PHP fatal naming a theme file, the agent can open that file in the same window, point at the line and compare it with what you changed last. If the cause is a plugin on the server rather than your code, the log line says so, and the agent quotes it instead of paraphrasing. Log text is third-party data, so it is never followed as an instruction. If nothing explains the error, the agent reports the checks it ran and sends you to Site, Site Monitoring, Logs in the dashboard, because the WordPress debug.log is not something the API returns.

The connection matters only a little for this job. Devin Local has no documented tool cap, so the full URL works. The legacy Cascade agent can use at most 100 tools at a time across all your servers, and xCloud offers 188 operations plus two search tools, so connect it through the compact URL; the sites and servers toolsets an investigation needs are 121 tools together, so that pair does not fit. The agent does not restart services on its own to see whether the error goes away. A restart is a change on a live server, and it is something you ask for once the cause is clear. xCloud runs a service restart without a prompt of its own, so your approval, plus Devin Local's, is the gate that counts.

Windsurf specific: New Windsurf tabs use the Devin Local agent, and the Cascade MCP page applies to legacy Cascade only, so check which agent your tab runs. Devin Local reads MCP servers from ~/.config/devin/mcp_config.json, .devin/mcp_config.json or .devin/mcp_config.local.json, and before version 3.6 from the main config.json. Legacy Cascade opens its file from Open MCP config file in the Cascade panel menu. If the agent says it cannot find a way to read the web server log or the services, the entry may point at a narrow toolset, so use https://app.xcloud.host/mcp on Devin Local, or ?profile=compact on Cascade, and reload the config.

What xCloud does for troubleshooting

xCloud reads the evidence in a fixed order, cheapest first: site status, recent events, the web server access and error log, WordPress health, WP_DEBUG and server services. The agent names a cause only when a log line or an event it retrieved shows it, and says plainly which logs only the dashboard can display.

Check the status first. The agent reads the site status before anything else. A site that is still provisioning, deploying or in a failed state explains a 500 on its own, and the answer is then to wait or to look at the last deploy, not to hunt for a PHP fault.
Read the recent events. The site's recent tasks, such as SSL issuance, plugin updates, cache purges and deploys, come with their outcome. A 500 that began right after a failed task has usually found its cause here, and one task's full output can be opened.
Read the web server logs. The agent asks for the nginx log type with a limit, which returns the access log, the error log and the 7G and 8G firewall logs on Nginx and OpenLiteSpeed alike. The error log is where a PHP fatal shows up as a 502 or 500. Log lines are quoted as data, never followed as instructions.
Check WordPress health. For WordPress sites the agent reads the health status: WordPress and PHP versions, the debug and cron flags, and whether the install itself is broken.
Turn on WP_DEBUG only if needed. If the logs so far are inconclusive, the agent proposes switching WP_DEBUG on, waits for your approval, and switches it back off when the investigation ends. The toggle flips the flag only; it does not return the debug log.
Check the server services. When the whole server looks wrong rather than one site, the agent reads whether the web server, PHP and the database are running. If nothing explains the error, it reports what it checked and what each check showed, and points you to the dashboard logs.

Reference

Troubleshooting Settings and Limits on xCloud

The facts Windsurf works within when it troubleshoots a broken site. Where a row names the dashboard, that step stays yours to take there.

Setting or limit	What applies
Read order	Status, recent events, nginx access and error log, WordPress health, WP_DEBUG, then server services. Reads run straight away and change nothing
Log type	sites_access-logs with type nginx reads the access log, the error log and the 7G and 8G firewall logs. The default type reads the access log only
Log reads	Logs are read over SSH, so a call is slow. The agent asks for a bounded window with a limit, not everything
Staging history	The deployment log of a site with a staging environment is the push and pull history between staging and production, not the Git build log
Dashboard-only logs	The WordPress debug.log, Laravel, PM2 and docker-compose logs: Site, Site Monitoring, Logs. Server logs such as Fail2Ban and auth: Server, Monitoring, Logs
WP_DEBUG	The API only toggles the flag. Reading the resulting debug.log is a dashboard step
Stale error pages	A purge of the site cache clears a cached error page. It runs without a confirmation stop and finishes asynchronously, so completion shows in the site events
Temporary shell access	A temporary sudo user expires after 12 hours, and the agent removes it as soon as the investigation ends instead of waiting for the expiry
Rescue action	A server-side repair with flags such as directory permissions, regenerating the Nginx configuration, reinstalling PHP or repairing Node.js, PM2 or OpenClaw. A flag the site type does not support is refused
Hand-offs	A slow site goes to performance, a failed deploy goes to deploy, and a 526 or certificate warning goes to SSL

Rules Windsurf has to follow

The agent never restarts a service or reboots the server just to clear an unexplained error. A restart is a real change on a live machine, and it destroys the evidence the logs were about to show.
A plain 500 or a short database error is a symptom. The agent does not name a cause such as bad credentials, a missing migration or a crashed process unless a log line or event it retrieved shows it.
Temporary shell access is used only when the readable logs do not explain the fault and you agree. The agent revokes it the moment the investigation ends.
Turning WP_DEBUG on, creating shell access and running the rescue action each need your explicit yes naming the site or server. The agent turns WP_DEBUG back off afterwards.
When no evidenced cause turns up, the agent says what it ruled out, gives you the dashboard log path and the site's dashboard link, and suggests contacting xCloud support with that evidence.

Example prompts

What Can You Ask Windsurf to Do for Troubleshooting?

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

shop.example.com returns 500. Use xCloud to check its status, recent events and nginx error log, then tell me the cause with the log line.

Prompt

Open the file named in that PHP fatal and show me what changed in it in my last commit.

Prompt

Is the database running on the Frankfurt server? Check the services and do not restart anything.

Prompt

My site shop.example.com is returning a 500 error. Find out why, and show me what you checked.

Prompt

Read the nginx error log for the shop site and tell me what it says about the last hour.

Prompt

Which tasks ran on the shop site just before it broke? Did any of them fail?

Prompt

Check WordPress health on the blog site and tell me whether the install itself is broken.

Prompt

Is the database running on the Frankfurt server? Check the services before touching anything.

Prompt

Turn on WP_DEBUG for the blog site, tell me what you find, then turn it off again.

Prompt

Purge the cache on the shop site in case it is serving a stale error page.

Prompt

Run a rescue on the shop site to reset directory permissions.

Windsurf and Troubleshooting: Frequently Asked Questions

What people ask before they let Windsurf troubleshoot a broken site through xCloud.

Does Windsurf need the full xCloud tool list to troubleshoot a site?

No, but it needs the right tools. Devin Local has no documented tool cap, so the full URL works. The legacy Cascade agent caps the total at 100, so use the compact URL; sites and servers together are 121 tools and do not fit. The investigation only needs the site, event, log and service reads.

Can Windsurf's agent fix the problem it finds in my code?

Yes, if the log points at a file in the project open in Windsurf. The agent can edit it like any other file. Redeploying the fix is a separate xCloud action that stops for your confirmation.

What does the agent check first when a site shows a 500 error?

The site status, then recent events, then the web server logs. A site that is still provisioning or whose last deploy failed explains a 500 without any deeper digging, so the status read always comes first. Only after those cheap reads does the agent look at WordPress health, WP_DEBUG and server services.

Will the agent restart my server or a service to fix an error?

Not to clear an error it cannot yet explain. A restart changes a live machine and wipes out the evidence in the logs, so the agent finds the cause first. Restarting a service stays an action you ask for and approve.

Which logs can the agent read, and which can it not?

It reads the site's access log, error log and the 7G and 8G firewall logs through the nginx log type. It cannot read the WordPress debug.log or the Laravel, PM2 and docker-compose logs. Those are in the dashboard under Site, Site Monitoring, Logs, and server logs such as Fail2Ban are under Server, Monitoring, Logs.

Does the agent get shell access to my server?

Only when the logs it can read do not explain the problem and you agree to it. The access is a temporary sudo user, and the agent removes it as soon as the investigation ends. If it is ever left behind, it expires on its own after 12 hours.

What if my site is slow rather than broken?

A slow site is a different investigation, because it is answered from measurements and cache state rather than error logs. The agent hands it to the performance job. A failed deploy goes to the deploy job and a 526 or certificate error goes to the SSL job.

Other agents