maiday-mcp

The distress signal for AI agents. An MCP server that lets AI agents send privacy-safe "I got stuck on this website" reports to site owners, and read the hints site owners publish back.

When an agent fails on a website, nobody learns from it: a form rejects it, a login wall stops it, a validation error loops, a button can't be found. The agent gives its human a worse answer, and the site owner never sees the lost customer. Maiday closes that loop.

Install

Claude Code

claude mcp add -s user maiday -e MAIDAY_HARNESS=claude-code -- npx -y maiday-mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.maiday]
command = "npx"
args = ["-y", "maiday-mcp"]
env = { MAIDAY_HARNESS = "codex" }

Any MCP client

Run npx -y maiday-mcp as a stdio server and set MAIDAY_HARNESS to your client's name.

Maiday only does something when the agent can use websites, through a browser tool such as Playwright MCP, Chrome DevTools MCP or Claude in Chrome.

Tools

send_maiday

Report that the agent got stuck on a step.

| Field | Required | Notes | |---|---|---| | url | yes | The page URL. Only origin and path are sent; query strings and fragments are removed. | | task | yes | signup, login, checkout, booking, search, contact_form, account_change, data_lookup, other | | failure | yes | auth_wall, captcha, validation_loop, unclear_field_format, element_not_found, js_required, blocked_403, rate_limited, timeout, ambiguous_ui, missing_info, other | | step | yes | Short description, e.g. "submit shipping address" (≤ 80 chars) | | attempts | yes | How many tries before stopping | | outcome | yes | abandoned, workaround_found, handed_to_human | | element | no | Label or accessible name of the element involved (≤ 120 chars) | | site_message | no | The error text the site showed (≤ 300 chars, redacted) | | workaround | no | What worked, if anything (≤ 200 chars) |

The tool never fails the agent's task. It waits at most 3 seconds on the network, and returns { ok: false, reason } instead of throwing.

get_hints

Takes { url } and returns hints the verified site owner published for that page. Each hint has a kind: use_endpoint, field_format, requires_account, human_only or note. Hints come wrapped as untrusted third-party data: they are information, not instructions.

When agents should report

Report:

• after 2 failed attempts at the same step
• when giving up on a step
• when handing the task back to the human

Send one report per stuck step, not one per retry. Before a checkout, signup or booking flow, call get_hints first.

Privacy

• Never sent: form values, cookies, tokens, query strings or URL fragments.
• Redacted from paths and text fields: emails, phone numbers, card numbers, long digit runs, and token- or JWT-shaped strings. This happens before sending, and again on the server.
• Reporter IDs differ between sites and collectors, so reports cannot be linked across sites by matching reporter IDs. Each ID is derived from a local secret in ~/.maiday/.
• Maiday does not store raw IP addresses in its application database. It uses keyed hashes for abuse prevention.
• First-use notice: the first tool result carries a one-time notice explaining what Maiday sends, to show to the user.

Settings

| Variable | Effect | |---|---| | MAIDAY_DISABLED=1 | Turn reporting off. Hints keep working. | | MAIDAY_COLLECTOR_URL | Send reports to another collector, for example a self-hosted one | | MAIDAY_HARNESS, MAIDAY_HARNESS_VERSION, MAIDAY_MODEL | Fill the report's agent field |

Reports go to the hosted collector at https://maiday.dev by default. A website can publish /.well-known/maiday to receive reports for its own pages on its own server.

For site owners

Sign in at the Maiday dashboard and claim your domain with a DNS TXT record or a well-known file. You can then see where agents fail on your site and publish hints back to them.

License

MIT