Agents & MCP

Hand broken links to your agent.

Your 404less instance is also an MCP server. Connect Claude Code, Cursor or any MCP client, and your agent can ask which links are broken, where visitors came from, and what the closest replacement is, then open the fix in your repo.

Setup Tools Prompts that work Trust model REST API

claude code mcp · 404less

list_broken_links

3 open on docs.acme.dev, ranked by visitor hits
get_link_details /docs/getting-startd

Referrers, the pages linking to it, the closest live page
PR
Opened PR #142
```
fix: redirect 3 broken docs URLs
```
Read-only tools: the fix lands in your repo, never in 404less

Setup

Create a key under API & MCP in the dashboard. Keys belong to the team and can read every site on it.

Claude Code

$ claude mcp add --transport http 404less https://your-404less.example/mcp \
    --header "Authorization: Bearer 404l_…"

The dashboard’s API & MCP page walks you through it per client (Claude Code, Cursor, VS Code, Codex, OpenCode, Claude Desktop) with your key filled in, plus a Prompt tab you can paste into any agent.

Cursor, Claude Desktop and others

{
  "mcpServers": {
    "404less": {
      "type": "http",
      "url": "https://your-404less.example/mcp",
      "headers": { "Authorization": "Bearer 404l_…" }
    }
  }
}

The server implements MCP streamable HTTP (protocol 2025-03-26): JSON-RPC over POST, no long-lived connection required.

Tools

Tool	What it returns
`list_sites`	The team’s sites with their open broken-link counts.
`list_broken_links`	Links for a site (by id, domain or name), filtered by status and time, ranked by hits, each with its page title and stored suggested fix.
`get_link_details`	One URL: hits, first/last seen, status, last crawler check with redirect chain, top referrers, pages linking to it, ranked fixes.
`get_suggestions`	Ranked replacement candidates for any URL on a site.

Prompts that work

“Which broken links on docs.acme.dev matter most this week? Draft redirects for the top five in vercel.json and open a PR.”
“Find every page on our site that links to /legacy/download and replace the link with the suggested target.”
“Summarize the referrers for /blog/launch-post so I know who to ask to update their link.”

Because the tools return structured data, not screenshots, the agent’s edits are grounded in the same list you see in the dashboard. Resolve the links there once the PR merges, or let the crawler notice they work again.

Trust model

404less is deliberately read-only toward your code. It never holds a repository token and never writes to your repo. The agent does the writing, inside the permissions you gave it, so every change is a reviewable pull request.

A key is shown once at creation and stored hashed. Revoke it from API & MCP at any time; the MCP endpoint rejects it immediately.

REST API

The same bearer key works against the JSON endpoints under /api: sites, the links list with filters, link details, the overview, and CSV exports. The MCP tools are thin wrappers over these handlers, so anything the dashboard shows, a script can fetch.

$ curl -s https://your-404less.example/mcp \
    -H "Authorization: Bearer 404l_…" -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
        "params":{"name":"list_broken_links","arguments":{"site":"docs.acme.dev"}}}'