Windsurf

Windsurf's Cascade agent can use MCP servers or run terminal commands. Connect AgentServe either way and Cascade can deploy what it built to live URLs, check logs when a build fails, and pass you a claim link to keep the result.

What you get#

• Five tools: deploy_stack, stack_status, get_logs, extend_ttl and destroy_stack. Each takes the project directory as path.
• Or the agentserve CLI, if you'd rather the agent run shell commands: deploy, status, logs, extend and destroy.
• Multi-service stacks from an agentserve.yaml, or one inferred service if there's no manifest.
• Redeploys to the same URLs, tracked in .agentserve/stack.json in the project and shared with the CLI.

Set up with MCP#

You need uv. The MCP server runs on your machine over stdio, because it reads and packs your project directory; it deploys to https://agentserve.sh.

1. Open Windsurf's MCP config#

   In Windsurf, open the MCP settings from the Cascade panel and choose to edit the raw config. The file is ~/.codeium/windsurf/mcp_config.json.

2. Add AgentServe#

   {
     "mcpServers": {
       "agentserve": {
         "command": "uvx",
         "args": ["--from", "agentserve[mcp]", "agentserve-mcp"]
       }
     }
   }

   If the file already has other servers, add agentserve next to them inside mcpServers. uvx fetches the package on first start.

3. Refresh and check#

   Refresh the MCP servers in Windsurf (or restart it). agentserve should show its five tools.

Set up with the CLI#

Cascade can run terminal commands, so it can use the agentserve CLI instead of the MCP server.

1. Install the CLI#

   Put agentserve on your PATH, and check it installed:

   uv tool install agentserve
   agentserve --help

2. Give Cascade the rules#

   Save the AgentServe skill as a workspace rule, so Cascade knows the manifest format and to hand you the claim link:

   mkdir -p .windsurf/rules
   curl -s https://agentserve.sh/skill.md -o .windsurf/rules/agentserve.md

3. Skip the approval prompt (optional)#

   Cascade asks before running commands. Add agentserve to the allow list for Cascade's terminal commands in Windsurf's settings to let it deploy without asking.

The CLI and the MCP server share .agentserve/stack.json, so you can set up both and mix them: a stack deployed with one is redeployed by the other, at the same URLs. Every command is in the CLI reference.

A first prompt to try#

Create a shared shopping list: a FastAPI backend with SQLite under $DATA_DIR and a static
Vite frontend. Deploy it with the agentserve tools using this project's absolute path,
then give me both URLs and the claim link.

Cascade should write an agentserve.yaml, wire the frontend to ${api.url}, call deploy_stack and report back. Ask for a change and it redeploys to the same URLs, list items intact.

Using the CLI? Ask for it "with the agentserve CLI"; Cascade runs agentserve deploy and reads the URLs and claim link from the output.

How the claim link reaches you#

The deploy_stack result includes claim_url, and Cascade passes it to you in chat. Anonymous stacks run for 1 hour. Open the link, sign up or sign in, and the stack moves into your account with the same URLs and data. Claiming after expiry still works while the snapshot is kept. See Claiming.

With the CLI, agentserve deploy prints the claim URL with the expiry, and agentserve status shows it again.

The link is also in .agentserve/stack.json under claim_url.

To deploy straight into your account, add "env": { "AGENTSERVE_API_KEY": "as_live_…" } to the server entry. No claim code, no clock.

Troubleshooting#

• The server shows an error. Run the command in a terminal: uvx --from 'agentserve[mcp]' agentserve-mcp. If uvx isn't found, use its absolute path (which uvx) as command.
• The wrong directory got deployed, or "no stack linked to …". Relative paths resolve from wherever the MCP server was started, which may not be your project. Ask Cascade for the project's absolute path.
• Connection errors. https://agentserve.sh isn't reachable. Check your network or proxy settings.
• deploy_error in the result. The redeploy failed, and the previous version is still serving. Have Cascade read get_logs and fix the cause.
• 429 on deploy. Your network has too many unclaimed stacks running. Claim or destroy one.

More: Connect your agent, MCP tools, Manifest.