--- title: What it actually took to make a monitoring platform agent-ready description: AI agents are becoming real API consumers, and scanners now grade how usable your product is for them. We spent a week taking WatchFor from a mediocre agent-readiness score to 100/100 — two MCP servers, OAuth 2.1, signed probes, a no-auth sandbox, and a pile of lessons about what agents (and their scanners) actually check. Here's all of it, including what didn't work. canonical: https://watchfor.io/blog/what-it-took-to-make-monitoring-agent-ready --- [All posts](/blog) [Engineering](/blog/category/engineering) Aug 28, 2026 · 7 min read · WatchFor Team # What it actually took to make a monitoring platform agent-ready AI agents are becoming real API consumers, and scanners now grade how usable your product is for them. We spent a week taking WatchFor from a mediocre agent-readiness score to 100/100 — two MCP servers, OAuth 2.1, signed probes, a no-auth sandbox, and a pile of lessons about what agents (and their scanners) actually check. Here's all of it, including what didn't work. Update, 11 September 2026: the score below is from August. On 10 September ora.ai rated watchfor.io 100/100 and listed it first — the last six points, and what the number does not mean, are in [a follow-up](/blog/100-on-ora-ai). A growing share of the traffic hitting SaaS products isn't a person in a browser — it's an agent acting for one. "Set up uptime monitoring for my API" is now a sentence people type into Claude or ChatGPT, and whichever product the agent can actually operate wins that customer. There are now scanners that grade exactly this — automated audits that crawl a domain the way an agent would and score how usable it is for them. When we first pointed one at watchfor.io, we scored 40/100 . A week of focused work later we're at A-grade on orank (ora.ai's agent-readiness index — [see our live report](https://ora.ai/score/watchfor.io)) and [100/100 on is-agentic.com](https://is-agentic.com/scan/watchfor.io) — and, more importantly, an agent can go from never having heard of WatchFor to running its first authenticated API call with no human in the loop. This post is the honest engineering log: what we built, what each piece is for, and the measurement quirks we hit along the way. ## What "agent-ready" actually means Strip away the buzzwords and an agent needs the same things a good developer needs, minus patience: - Discovery — can it find out what you offer without clicking through marketing pages? - Authentication — can it get scoped credentials without a sales call? - Usability — do your APIs behave predictably: typed schemas, structured errors, rate-limit headers, pagination? - Trust — can both sides verify who they're talking to? Everything below maps to one of those four. ## The agent stack, in one table If half these acronyms are new — that was us three months ago. Quick reference for everything this post touches: Term What it is MCP (Model Context Protocol) An open protocol that lets AI assistants (Claude, ChatGPT, Cursor…) call a product's "tools" directly — think USB for AI integrations. A product runs an MCP server ; the assistant is the client . A2A (Agent2Agent) A protocol for agent-to-agent delegation: instead of calling individual endpoints, one agent hands another a whole task ("diagnose what's broken") described in its Agent Card. Function calling How LLMs invoke external code: the model picks a function and fills its typed arguments. OpenAPI specs get converted into these function definitions automatically. OpenAPI 3.1 The machine-readable description of a REST API — every operation, parameter and schema. For agents it doubles as the function-calling contract. OAuth 2.1 The current consolidation of OAuth: authorization-code flow with mandatory PKCE. MCP clients use it to get scoped tokens with zero copy-pasted API keys. DCR (Dynamic Client Registration) Lets an OAuth client register itself programmatically — required so any MCP client can connect without us pre-approving it. llms.txt A convention (llmstxt.org): a markdown site guide at /llms.txt that tells language models what a site offers and where. agents.md A companion convention: an instruction card for agents — when to use the product, how to authenticate, first calls to make. ARD (Agentic Resource Discovery) A /.well-known catalog listing every machine surface a domain offers (APIs, MCP servers, agents, SDKs) with stable identifiers. Web Bot Auth / RFC 9421 HTTP message signatures: a bot signs its requests with a private key and publishes the public key, so anyone can verify the traffic is genuine — not a spoofed User-Agent. JSON-RPC The lightweight request/response format both MCP and A2A speak: {"method": …, "params": …} over HTTP. ## Discovery: files agents actually read The entry points are boring text files at predictable URLs: - [/llms.txt](/llms.txt) — a structured site guide. One hard lesson: there's a soft 30,000-character budget for a navigation index. Ours crept to 30.5k and got flagged; we now treat it like a performance budget. - [/agents.md](/agents.md) — an instruction card: when to use WatchFor, when not to (we explicitly say "not for log aggregation or APM"), how to authenticate, and the first three calls to make. - [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — an ARD catalog listing every machine surface (API, MCP servers, A2A, SDKs) with stable URN identifiers. - Markdown twins — every content page is also served as clean markdown: append .md to the path, send Accept: text/markdown , or add ?mode=agent . Browsers and Googlebot still get HTML, so there's no SEO impact; agents skip the DOM parsing entirely. A Next.js gotcha that cost us real hours: a rewrite whose destination contains a .well-known dot-segment silently 404s. Everything under /.well-known/ on our site is rewritten to clean /api/well-known/* routes for that reason. ## The OpenAPI spec is a function-calling contract now Agents don't read your API docs — their frameworks convert your OpenAPI spec into tool definitions for function calling. That conversion is stricter than any human reader: - Every operation needs an operationId — it becomes the function name. - Responses should be $ref s to named schemas. We moved every list envelope from inline objects to named List components. - The subtle one: path-level parameters are invisible to most converters. OpenAPI lets you declare shared parameters on the path item, and we did — which made GET /monitors/{id} look like a function with no arguments . A scanner insisted only 30 of our 57 operations were typed until we hoisted every path-level parameter down into the operations. If your detail endpoints look argless to agents, this is probably why. We also changed DELETE endpoints from 204 No Content to 200 with {"object": "deleted", "id": …} — Stripe semantics. An empty 204 is fine for humans; an agent wants a schema'd confirmation it can assert on. ## Two MCP servers, not one Our [MCP server](/docs/api/mcp) exposes 40 tools over the same REST API — same auth, same rate limits, same validation. Design choices that mattered: - Anonymous discovery. initialize and tools/list work without credentials. Scanners, registries and curious agents can inspect the full tool inventory before anyone creates an account. Tool calls still require auth. - Structured errors. An unknown tool returns a JSON-RPC -32602 with the available tool names; tool-level failures return {"error": {"code", "message"}} . Prose errors are where agent loops go to die. - Resources and prompts, not just tools. The monitor-type catalog, the OpenAPI spec and the quickstart are MCP resources ; common jobs ("diagnose what's broken") are parameterized prompts . Then we added a second, read-only documentation MCP server at [/api/docs-mcp](/docs/api/mcp#documentation-mcp-server) — list_docs , search_docs , read_doc over all 67 docs pages, no auth at all. Agents use one protocol to act and the same protocol to learn . ## OAuth 2.1: zero-key onboarding API keys assume a human in a dashboard. For MCP clients we run a full OAuth 2.1 authorization server: dynamic client registration, PKCE (S256 only), and a mandatory consent screen. Add https://watchfor.io/api/mcp to Claude and it discovers the auth server, opens a browser consent page, and gets scoped tokens — no key is ever copied . The same tokens work on the REST API, with write scope gating anything that mutates. For agents that would rather delegate whole tasks than call endpoints, there's also an [A2A agent](/.well-known/agent-card.json) exposing task-level skills ("diagnose incidents", "reliability report") over JSON-RPC. The agent card is generated from the live skill registry, so it always lists the current set. ## A sandbox agents can find Every payload of our no-auth sandbox returns sample data in the exact production shapes, marked "sandbox": true . Two discoverability lessons: - We documented it in agents.md — scanners still couldn't "verify a sandbox exists". They don't follow prose links reliably. - What worked: serving it at the conventional paths scanners actually probe — [/sandbox](/sandbox) and /api/sandbox — and declaring it as a second server in the OpenAPI spec. If you build a thing for agents, put it where conventions say it should be, not just where your docs say it is. ## Signed probes: trust in both directions The trust question runs both ways. Our probes hit customer infrastructure millions of times a day identifying as WatchForBot — and a User-Agent string is trivially spoofable. So every HTTP(S) probe request is now signed with the fleet's Ed25519 key using [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) HTTP message signatures (the Web Bot Auth profile): Signature-Agent: "https://watchfor.io" Signature-Input: sig1=("@authority" "signature-agent");created=…;expires=…; keyid="watchfor-probes-2026";alg="ed25519";tag="web-bot-auth" Signature: sig1=:…: Public keys live at [/.well-known/http-message-signatures-directory](/.well-known/http-message-signatures-directory). Before enabling it fleet-wide we captured a live probe request with tcpdump and verified the signature against the published key — it checks out end to end. Bot-management platforms that support Web Bot Auth can now allowlist WatchFor probes on cryptographic proof instead of substring-matching a User-Agent. Details on [/bot](/bot). ## Registries, SDKs, and the long tail The rest is distribution: the MCP server is listed on [Smithery](https://smithery.ai/servers/hello-65wl/watchfor); official zero-dependency SDKs with a watchfor CLI ship on [npm](https://www.npmjs.com/package/watchfor), [PyPI](https://pypi.org/project/watchfor/) and [RubyGems](https://rubygems.org/gems/watchfor); and our [agent-toolkit repo](https://github.com/watchfor-io/agent-toolkit) carries AGENTS.md , installable agent skills and an Agent Plugins manifest. ## What didn't move the needle (yet) Honesty section. Two things resisted a week of engineering: - Brand search. Scanners literally Google (and Bing) your name. Our site is young; "WatchFor" doesn't reliably crack the top results yet. No amount of code fixes that — only indexing time and mentions. If you're launching something agent-facing, submit to Google Search Console and Bing (ChatGPT search runs on Bing) on day one, not month two. - Live onboarding tests. One scanner runs an actual agent through your signup flow. It's a genuinely good check that's genuinely hard to fully satisfy — and that's fine. The point was never the score; it's that the friction it measures is real. ## Takeaways - Agent-readiness is mostly normal API craftsmanship , applied ruthlessly: typed everything, structured errors, predictable URLs, self-serve auth. - Conventions beat documentation. Agents and scanners probe well-known paths; being described somewhere is worth far less than being where expected . - The exotic-sounding parts — MCP, A2A, signed requests — are each a few hundred lines on top of a clean REST API. If your API is a mess, no protocol adapter saves you. - Scanners are imperfect proxies, but arguing with the mirror misses the point: every gap they flagged was something a real agent would also trip on. Want to poke at any of this? Start at [/agents.md](/agents.md) — no account needed for the interesting parts. [#engineering](/blog/tag/engineering)[#architecture](/blog/tag/architecture)[#monitoring](/blog/tag/monitoring) ## Monitor yo … --- Canonical page: https://watchfor.io/blog/what-it-took-to-make-monitoring-agent-ready · Site guide: https://watchfor.io/llms.txt