How Do I Fix Broken Links in Link Text for SEO on Shopify? (1-Hour Workflow)

Build-in-public post — real workflow, real token cost. Part of our AI workflows pillar.

The customer pain point

The client's site had broken links scattered through blog posts and pages — old internal links to URLs that had changed, dead external references, and anchor text pointing at 404s. The damage:

• SEO equity leaks. Internal links pass authority. A link to a 404 wastes that signal entirely.
• Crawl budget waste. Googlebot follows links to dead ends; that's crawl budget not spent on pages that matter.
• User trust. A reader clicking "see our full guide here" and hitting a 404 bounces — and remembers.
• It compounds silently. Nobody audits links until something forces it. By then there are dozens.

Manually finding every broken link across a content library and fixing each one is the kind of task that never gets prioritized — so it never gets done.

Table of Contents

• The Approach
• The Claude MCP Setup
• The Prompt
• Cost & Time
• What to Watch For

Key Takeaways

The Approach

1. Crawl all content (blog posts + pages) and extract every <a href>.
2. Check each link's HTTP status (200 / 301 / 404 / timeout).
3. Classify: working, redirected (should update to final URL), broken (404/dead).
4. Resolve broken links — for each broken internal link, find the correct current URL (slug changed, page moved). For ambiguous cases, Claude suggests the best replacement based on the anchor text + surrounding context.
5. Write back the corrected links into the content.
6. Report every change for a human review before publish.

The Claude MCP Setup

We used Claude with MCP (Model Context Protocol) so Claude could directly read the content files and propose edits in context, rather than us shuttling data back and forth.

High-level setup:

• An MCP server exposing two tools: list_content (returns all blog/page files + their links) and check_url (returns HTTP status for a URL).
• Claude connected to that MCP server. It calls list_content, then check_url on each link, then reasons about replacements.
• A propose_fix tool that writes the suggested change to a review file (never directly to live content — human gate first).

If you're not running a custom MCP server, the lighter version: a script that produces a CSV of (file, anchor_text, href, status) and you paste the broken rows into Claude with the prompt below. Slower, but no MCP infra needed.

The Prompt

The core reasoning prompt (run per broken link, or batched):

You are fixing a broken internal link on a Shopify content site.

Broken link:
- Anchor text: "{anchor_text}"
- Current href: {href}
- HTTP status: {status}
- Surrounding sentence: "{context_sentence}"

Here is the current sitemap of valid URLs:
{list of valid /blog and page slugs}

Decide the correct replacement:
1. If a valid URL clearly matches the anchor text + context intent,
   return that URL.
2. If the link was external and is now dead with no clear replacement,
   return "REMOVE_LINK" (keep the anchor text as plain text).
3. If you are not confident, return "FLAG_FOR_HUMAN" with a one-line
   reason.

Respond as JSON: { "action": "...", "new_url": "...", "reason": "..." }

The JSON response made the write-back deterministic and the FLAG_FOR_HUMAN path kept Claude from guessing on ambiguous cases.

Cost & Time

Cost scales with how many links need judgment. Pure redirect-map fixes (slug A → slug B, known mapping) are free deterministic replacements — only the genuinely ambiguous ones hit the model. Most of the spend is on the ~10–20% that need contextual reasoning.

What to Watch For

• Don't auto-write to live content. The workflow writes to a review file. A human approves before publish. Wrong link replacements are worse than broken links — they silently send equity and users to the wrong page. (More on this in what AI-run means when the AI screws up.)
• Redirect chains. A link returning 301 isn't "broken" but should still be updated to the final destination — chained redirects dilute equity and slow crawl. Treat 301s as fix candidates, not just 404s.
• External links die unpredictably. For dead external references with no replacement, removing the link (keeping the text) is usually better than linking to an archive or a guess.
• Re-run on a cadence. Links rot continuously. A monthly re-run keeps the content library clean for a few dollars. Pair it with the weekly metrics digest cadence.

Talk to Branva

We run link audits, internal-linking optimization, and custom AI workflows as part of our managed operations. Book a free call — we'll run a link audit on your content in the first session.

Frequently Asked Questions

Can't a free broken-link checker do this?

A checker finds broken links. It doesn't fix them — it can't decide what the correct replacement URL is based on anchor text and context. The fix step is the hard part and where the AI earns its few dollars.

What's MCP and do I need it?

MCP (Model Context Protocol) lets Claude directly call tools — read your content, check URLs, propose edits — in one reasoning loop instead of you copy-pasting. It's faster and cleaner but optional; the CSV-and-paste version works without any MCP infrastructure.

How is this different from just setting up redirects?

Redirects fix the destination (a 404 becomes a 301). They don't fix the link itself, which still points at a dead URL and still wastes a redirect hop + equity. This workflow updates the actual link to point directly at the correct live URL.

How often do links break?

Continuously — every slug change, every removed page, every dead external reference. A site with active content publishing accumulates broken links monthly. A monthly re-run is the right cadence.

Related reading

• The AI Workflows pillar — the full set of workflows.
• How Do I Add Alt Text to Shopify Images in a Block? — same custom-app pattern.
• The Role of SEO in Ecommerce — why internal link health matters for ranking.
• How to Set Up Shopify Analytics Correctly — measure the crawl/index impact.