Windsurf (Devin Desktop)

Set up Spicrawl in Windsurf, now named Devin Desktop: add the hosted MCP server, install the agent skill, and add a rule so the agent fetches web pages cheaply and handles errors correctly.

Windsurf is now called Devin Desktop (renamed on 2026-06-02; same editor, and Cognition's docs at docs.windsurf.com redirect to docs.devin.ai/desktop). This page covers both names. Devin Desktop has two agents, and they configure MCP differently:

Agent	Where MCP servers live
Devin Local, the default agent for new tabs	The Devin CLI files `.devin/mcp_config.json`, `.devin/mcp_config.local.json` and `~/.config/devin/mcp_config.json`
Cascade, the legacy agent	`~/.config/devin/mcp_config.json`, with `serverUrl` and `${env:VAR}` interpolation

Set your key first, in the environment Devin Desktop starts from:

export SPICRAWL_API_KEY=spicrawl_live_...   # add to your shell profile, then restart Devin Desktop

1. Add the MCP server

Add the server in local scope. It is saved to .devin/mcp_config.local.json, which Devin gitignores, so the key stays out of your repository:

devin mcp add spicrawl https://mcp.spicrawl.com/mcp -H "Authorization: Bearer $SPICRAWL_API_KEY"

Your shell expands $SPICRAWL_API_KEY, so the file holds the key itself. The equivalent file:

.devin/mcp_config.local.json

{
  "mcpServers": {
    "spicrawl": {
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer spicrawl_live_..." }
    }
  }
}

Use -s user to write ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows) for every project. Do not use -s project, which writes the shared, committed .devin/mcp_config.json. Check with devin mcp list. Remote servers use Streamable HTTP by default.

The server exposes 25 spicrawl_* tools. See MCP server for each tool.

Tool limit

Cascade allows 100 tools in total across all enabled servers. Spicrawl uses 25 of them. If you are near the limit, disable other servers or list tool names in a server's disabledTools array in mcp_config.json.

Team allowlists

On a Teams or Enterprise plan, an admin can allowlist MCP servers. Once one server is allowlisted, every other server is blocked for the team. Ask the admin to add Server ID spicrawl (case-sensitive, the key name in your config) and to leave Server Config (JSON) empty to accept any configuration.

2. Install the skill

Devin Desktop loads skills from .devin/skills/, .windsurf/skills/ and .agents/skills/ in the project, and from ~/.config/devin/skills/ for every project. .agents/skills/ is what the CLI's codex client writes:

spicrawl skill install --client codex

This writes .agents/skills/spicrawl/SKILL.md. Without the CLI:

mkdir -p .agents/skills/spicrawl
curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.md

See Agent skill.

3. Add a rule

Save this as .devin/rules/spicrawl.md (.windsurf/rules/ still works, and .devin/ wins when both exist). With trigger: model_decision only the description sits in the prompt, and the agent reads the rule when a task involves web data. Use trigger: always_on to include it in every message. A rule file is limited to 12,000 characters.

.devin/rules/spicrawl.md

---
trigger: model_decision
description: Fetching, scraping or extracting data from web pages with Spicrawl
---

# Web data (Spicrawl)

Use Spicrawl to read web pages: the spicrawl_* MCP tools in chat, or
POST https://api.spicrawl.com/v1/scrape with `Authorization: Bearer $SPICRAWL_API_KEY` in code.
Docs: https://docs.spicrawl.com/llms.txt (append .md to any page URL for Markdown).

- Ask for markdown: `response_format: "markdown"` (API default is html); on spicrawl_scrape, `format: "markdown"`.
- Check the site's status, not only the HTTP status: `X-Target-Status` header, or `status`
  in the JSON envelope (spicrawl_scrape with `format: "json"`). 200 is the page; 404/410
  mean it does not exist; 403/429/503 mean the site refused, so escalate.
- On an error, switch on `code`. Retry only when `retryable` is true, after
  `retry_after_seconds`. Read `diagnostics.hint` and change what it names first.
  Never retry ERR::REQUEST::*, ERR::AUTH::* or ERR::LIMIT::QUOTA_EXCEEDED.
- Escalate one step at a time and stop at the first that works:
  plain fetch (1 credit) -> `js_render: true` (3) -> add the user's own `proxy`
  if they have one. Empty or skeleton content means render; ERR::UPSTREAM::CHALLENGE
  or a 403 target status means retry once, then the user's own proxy.
- Set `max_cost` on every request to the price of the step you intend.
- Keep the cache on (default). Set `cache: false` only for prices, stock or other live data.
- Trim tokens with `main_content_only` (on by default for markdown), `include_tags`, `exclude_tags`.
- For more than 20 URLs, use a batch job (spicrawl_batch_submit / POST /v1/batch).
  Batch items return raw HTML and apply only render, proxy and block_resources settings.
- Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.

Devin Desktop also reads AGENTS.md at the project root as an always-on rule. If you already keep agent instructions there, paste the same section into it instead of creating a rule file.

A first task to try

Open a new agent tab and ask:

Use Spicrawl to read https://example.com/pricing as markdown. List each plan with its monthly price.
If the page comes back empty, retry with rendering.

The agent should call spicrawl_scrape with url and format: "markdown", and add render: true only if the first result is empty. For a coding task:

Add a fetchPage(url) function to this project that calls the Spicrawl API for markdown,
following the Spicrawl rule's error-handling steps. Read the key from process.env.SPICRAWL_API_KEY.

Compare the result with the reference implementation in Best practices.

Troubleshooting

Symptom	Fix
401 from the server (Cascade)	`SPICRAWL_API_KEY` was not set when Devin Desktop started, so the header was empty. Export it and restart from that shell.
401 from the server (Devin Local)	The key in `.devin/mcp_config.local.json` is wrong or empty. Run `devin mcp remove spicrawl` and add it again.
Spicrawl does not appear in the MCP list	You edited the file for the other agent. Devin Local reads the `.devin/` files and `devin mcp add`. Cascade reads its own MCP config file from the Actions menu.
The server is blocked	A team allowlist is active. Ask the admin to allowlist Server ID `spicrawl`.
Tools are missing or capped	Cascade allows 100 tools across all servers. Disable other servers.
The agent writes `js_render` on `spicrawl_scrape` and gets "unknown argument"	The tool's argument is `render`. The API field is `js_render`.
Usage tools return `ERR::AUTH::INSUFFICIENT_SCOPE`	Grant the `read` scope to the key in the dashboard.