Optimize images and alt text with Windsurf
Optimizing your store's images with Windsurf means asking the Cascade agent in your editor to find heavy or unlabelled images through StoreSEO and then compress, caption and rename them one image at a time, with a restore for each change.
Last updated: October 2026
Set up Windsurf for StoreSEO
Skip this if Windsurf is already connected. The full guide, with the alternatives, is on the Windsurf page.
- 1
Add StoreSEO to mcp_config.json
In the Cascade panel, open the ... menu and click the Open MCP config file icon in the MCPs section. Add the entry under mcpServers and save. Remote servers use serverUrl.
JSON{ "mcpServers": { "storeseo": { "serverUrl": "https://mcp.storeseo.com/mcp" } } } - 2
Sign in to your store
Windsurf supports OAuth for remote servers. When it asks you to sign in to storeseo, a browser window opens: pick your Shopify store and approve access. Then ask this to confirm the connection.
PromptUse StoreSEO to show me my store's SEO score breakdown.
How does this work in Windsurf?
You are in the Windsurf window you already use for the theme, with the Cascade panel open beside a Liquid file. You type something like find my ten heaviest unoptimized product images and tell me what compressing them will use. Cascade calls storeseo_start first, because every other StoreSEO tool needs the conversation id it returns, and then storeseo_list_images, whose default sort puts the largest uncompressed files on top. Each row shows three axes, compression, alt text and file name, with an optimized count out of three, so the answer reads as a short worklist rather than a wall of data.
The editor context is the useful part. A product image with no alt text often sits in a theme snippet that hard-codes an image URL or an empty alt attribute, and Cascade can open that file while StoreSEO shows which images lack alt text on the Shopify side. Before it changes anything, ask Cascade to state the image count and the kind of spend: compression uses the Image Optimizer add-on quota, while alt text and file names use AI Content Optimizer credit. Then storeseo_optimize_image runs once per image with the axes you chose, and the reply reports each axis as applied, already applied, skipped or refused.
Cascade can reach all 44 StoreSEO tools within its 100-tool limit, so the image tools are available without trimming. If the store has no Image Optimizer add-on, compression is refused while alt text and file names still apply, and Cascade should say so instead of retrying. A file name change moves the image to a new storefront URL, which matters when a theme file hard-codes the old one; with the file open next to the chat, you can search for it right away.
-
You: Find my heaviest unoptimized product images and fix the top three.
- storeseo_start read-only
- storeseo_list_images read-only
-
Windsurf: The three heaviest are on Canvas Tote, Linen Apron and Market Basket, each over 2 MB with no alt text. Compression uses Image Optimizer quota and alt text uses AI credit, and a file rename changes the image URL. Shall I run all three axes on those three images?
-
You: Yes, go ahead.
- storeseo_optimize_image needs approval
-
Windsurf: Canvas Tote main image: compressed, alt text written, renamed. The new URL is in the report, so grep the theme for the old file name before you close the tab.
What to ask Windsurf
Use StoreSEO to list my ten heaviest unoptimized product images. Tell me the quota compression will use before you start.
Which product images have no alt text? Check the theme files in this workspace for hard-coded image URLs before we rename anything.
Optimize every image on the product Canvas Tote: compression, alt text and file name. Wait for my yes first.
- Find my ten heaviest unoptimized product images and compress them. Tell me the quota it will use first.
- Which product images have no alt text at all? Write alt text for the ones on my best seller.
- Optimize every image on the product Canvas Tote: compression, alt text and file name.
- Restore the original alt text on the last image you changed.
- Give my collection images descriptive file names, and warn me which URLs will change.
What StoreSEO does: image seo and alt text
StoreSEO tracks three things per image: file-size compression, alt text and file name. The agent finds the heaviest or unlabelled images, optimizes them one call per image, and can restore any of the three if you do not like the result.
Requires: Compression needs the Image Optimizer add-on and counts against its monthly quota; alt text and file names spend AI Content Optimizer credit.
- 1
Find the images
The agent lists product, collection or article images, heaviest unoptimized first by default. It can filter to images with no alt text, or scope the list to one product by title.
- 2
Check what it found
A title search can also match image file names from other resources, so the agent checks each row belongs to the product you meant.
- 3
Agree the scope and cost
Compression uses image quota and alt text and file names use AI credit, so the agent confirms before working through many images.
- 4
Optimize one image per call
Each call takes the axes you want: compression, alt text, file name or all three. The axes always run compression, then file name, then alt text, and the response reports each one separately.
- 5
Report or restore
The agent reports what applied, what was already done and what was refused. If a result is wrong, the restore tool brings back the original file, alt text or name.
Image SEO and alt text reference
| Axes per image | Compression, alt text, file name |
|---|---|
| Image sources | Products, collections and articles (pages have no images) |
| Batching | One image per call; never two calls on the same image at once |
| Compression | Image Optimizer add-on and its monthly quota; an already compressed image is reported as already applied |
| Alt text and file name | AI Content Optimizer credit; both together are billed as one generation |
| File name change | Renames the file on Shopify and changes the image's storefront URL |
| Collection and article renames | Re-upload the image, so the call can take a couple of minutes |
| Restore | Reverts compression, alt text or file name per axis |
| Score impact | Alt text and file names count on products, collections and articles; compression counts on products |
Rules Windsurf follows
- The agent confirms the number of images and the kind of spend before a bulk run.
- One image per call, all wanted axes together; never parallel calls on the same image.
- A renamed image has a new URL, so the agent tells you, because anything that hard-coded the old URL keeps serving the old file.
- If a response is lost, the agent re-lists the image instead of retrying, because a retry regenerates and spends again.
- A refused axis, for example compression without the add-on, is reported as such while the other axes still apply.
In Windsurf
Windsurf's MCP page describes the legacy Cascade agent, and the Devin Local agent that opens by default in new tabs reads different configuration files, so check which agent you are in if the image tools do not appear. The page also says nothing about how Cascade asks before running a tool, so treat StoreSEO's confirmation as an instruction the agent follows and read each optimize call before you accept it. Because storeseo_optimize_image handles one image per call, a bulk run is many calls in the panel.
What runs without asking. Reads such as SEO scores, store listings, settings and Google reports run straight away. Generating a preview spends AI credit but writes nothing, and StoreSEO tells the agent to say what a generation will cost before it runs one. Applying content, optimizing images, changing settings, publishing llms.txt or agents.md, writing a product description and deleting anything wait for your yes in the conversation. That yes is an instruction the agent follows, not a lock on the server, so your client's own tool-approval setting is the hard stop.
Questions
Can Windsurf find the theme code that uses an image I renamed?
Yes. A new file name gives the image a new storefront URL, and Cascade can search the workspace for the old file name in your theme files. StoreSEO cannot see your theme code, so that search is a separate step.
Does Windsurf compress images without the Image Optimizer add-on?
No. StoreSEO refuses compression without the add-on, while alt text and file names still apply on the same call. Cascade should report the refused axis and carry on with the others.
Can the agent compress images without the Image Optimizer add-on?
No. Compression needs the Image Optimizer add-on and counts against its monthly quota. Alt text and file names work without it and spend AI Content Optimizer credit instead.
Can I undo an image optimization?
Yes. The restore tool reverts compression, alt text or file name for one image, per axis. Restoring compression brings back the original file.
Why did my image URL change?
Giving an image a new file name renames the file on Shopify and re-points its storefront URL. Pages that use the image through Shopify keep working, but anything that hard-coded the old URL keeps the old file.
Can I write my own file name or alt text through the agent?
No. StoreSEO writes the alt text and file name from the resource's own context. You can steer the language, and you can always edit alt text yourself in Shopify admin.
Keep going
Image SEO and alt text with other agents
More Windsurf guides