> Canonical URL: https://codingcat.dev/post/agent-ready-web-architecture-webmcp-streamable-mcp-llms-txt

# Architecting the Agent-Ready Web: Combining Client-Side WebMCP, Streamable HTTP MCP, and RFC 9727 Discovery

✏️ Blog PostSeptember 22, 2026[Cloudflare](/topic/cloudflare)[AI & MCP Agents](/topic/ai)

# Architecting the Agent-Ready Web: Combining Client-Side WebMCP, Streamable HTTP MCP, and RFC 9727 Discovery

![Alex Patterson and AJ the Cat presenting the Dual-Plane Agent-Ready Web Stack with WebMCP and Streamable HTTP MCP](https://cdn.sanity.io/images/hfh83o0w/production/dd8b89a42ee37457891b58d39c6273a31ac013e4-1376x768.jpg?w=1376&q=82&fit=max&auto=format)[![Alex Patterson](https://cdn.sanity.io/images/hfh83o0w/production/a606dfaa381aab08ddbe16a33fe1d3e1fb37c927-400x400.jpg?w=96&h=96&q=82&fit=max&auto=format)Alex Patterson](/author/alex-patterson)✏️ Visual Architecture Diagram

## how this post connects together.

Follow AJ from first principles to production-ready architecture.

Let’s build it!✏️ Visual Diagram: Architecting the Agent-Ready Web: Combining Clie…✓ Good PatternVISUAL DIAGRAM[Diagram Walkthrough]Step-by-step diagram breakdown for Architecting the Agent-Ready Web: Combining Client-Side WebMCP, Streamable HTTP MCP, and RFC 9727 Discovery: start with Architecting the Agent, implement Hands-On Implementation, and ship to production.AAA Contrast Verified

Over the past year, a new class of traffic has arrived on every developer documentation site, media platform, and SaaS application: autonomous coding agents, browser assistants, and MCP clients. Yet most websites still serve bloated 250KB HTML bundles to headless agents and force in-tab browser assistants to guess CSS selectors. On [**CodingCat.dev**](/developers) and [**alexpatterson.dev**](https://alexpatterson.dev), we engineered a dual-plane **Agent-Ready Web Architecture**  that serves both in-browser AI agents (via **WebMCP** ) and external CLI/cloud agents (via **Streamable HTTP MCP**, **RFC 9727 API Catalogs**, and `Accept: text/markdown` content negotiation).

## The Dual-Plane Architecture: Client Plane (WebMCP) + Edge Plane (HTTP MCP & RFC 9727)

Why do you need both **WebMCP**  and **Streamable HTTP MCP**? Because AI agents interact with your web property from two completely different execution contexts:

- **1. The Client Browser Plane (In-Tab Agents): ** When a user opens your site in Chrome and asks their built-in browser assistant to search tutorials, filter courses, or grab a speaker kit, the agent is already inside the DOM sandbox. Exposing `document.modelContext.registerTool()` and declarative `` tools lets the browser assistant execute actions in 0ms using the user's existing cookies and UI state.
- **2. The Edge Network Plane (Headless & IDE Agents): ** When a developer in Cursor, Claude Code, or Google Antigravity points their agent at `https://codingcat.dev`, there is no browser DOM. That agent discovers capabilities via RFC 8288 HTTP `Link` headers, reads `/llms.txt` or requests `Accept: text/markdown`, and calls tools over JSON-RPC at `POST /api/mcp`.

![Dark-mode Architecture Diagram showing the Dual-Plane Agent-Ready Web Architecture combining Client-Side WebMCP and Edge Streamable HTTP MCP](https://cdn.sanity.io/images/hfh83o0w/production/894b9dc977dfc37feca6d6ae6c539423bf0638d2-1376x768.jpg?w=1376&q=82&fit=max&auto=format)Architecture Diagram: Opaque HTML-Only Website (left, Coral anti-pattern) vs. Dual-Plane Agent-Ready Web Stack combining Client WebMCP and Edge RFC 9727 + Streamable HTTP MCP (right, Mint recommended pattern).

## The 5 Pillars of an Agent-Ready Web Application

Protocol / StandardLive Endpoint on CodingCat.devTarget Agent RuntimeToken & Latency ImpactW3C WebMCP (Imperative & Declarative)document.modelContext & <form toolname>In-Browser AI Assistants (Chrome AI, Extensions)Reduces DOM scraping tokens by 90%; 0ms in-tab execution.Streamable HTTP MCPPOST /api/mcp & /.well-known/mcp/server-card.jsonIDE & Cloud Agents (Antigravity, Cursor, Claude Code)Stateless JSON-RPC 2.0 tool execution at the Cloudflare Edge.Markdown Content NegotiationAccept: text/markdown or /post/[slug]/index.mdLLM Crawlers & RAG PipelinesCuts payload size from 180KB HTML to 6KB clean Markdown.RFC 9727 API Catalog & Link Headers/.well-known/api-catalog & HTTP Link HeaderAutonomous Discovery ScannersZero-guesswork capability discovery on any HTTP HEAD/GET.Scoped LLM Directories/llms.txt, /blog/llms.txt, /podcasts/llms.txtContext-Window-Bounded Answer EnginesProvides hierarchical site map optimized for LLM context windows.

## Sharing One Tool Schema Across Browser WebMCP and Edge HTTP MCP

The cleanest architectural pattern we discovered while building CodingCat.dev's agent layer is defining a single canonical tool contract in TypeScript and binding it to both `document.modelContext.registerTool()` on the client and your Astro `/api/mcp` JSON-RPC route on the edge:

```
// src/lib/mcp/shared-search-tool.ts
export const SEARCH_CONTENT_TOOL_SCHEMA = {
  name: "search_content",
  description:
    "Search CodingCat.dev Courses, Podcasts, and Blog Posts by keyword or topic",
  annotations: {
    readOnlyHint: true,
    untrustedContentHint: true,
  },
  inputSchema: {
    type: "object" as const,
    properties: {
      query: {
        type: "string",
        description: "Search keyword (e.g. WebMCP, Gemini Nano, WebGPU, Astro, Sanity)",
      },
    },
    required: ["query"],
  },
};

// 1. Client-side binding for Browser WebMCP (document.modelContext)
export function registerClientWebMcpSearch(origin = "") {
  const mc =
    (typeof document !== "undefined" && (document as any).modelContext) ||
    (typeof navigator !== "undefined" && (navigator as any).modelContext);
  if (!mc || typeof mc.registerTool !== "function") return;

  mc.registerTool({
    ...SEARCH_CONTENT_TOOL_SCHEMA,
    execute: async ({ query }: { query: string }) => {
      const res = await fetch(`${origin}/api/search?q=${encodeURIComponent(query)}`);
      return await res.json();
    },
  });
}

// 2. Edge-side binding for Streamable HTTP MCP (POST /api/mcp)
export async function handleEdgeMcpToolCall(
  toolName: string,
  args: Record,
  siteOrigin: string
) {
  if (toolName === SEARCH_CONTENT_TOOL_SCHEMA.name) {
    const query = String(args.query || "");
    const res = await fetch(`${siteOrigin}/api/search?q=${encodeURIComponent(query)}`);
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      isError: false,
    };
  }
  throw new Error(`Unknown MCP tool: ${toolName}`);
}
```

## Step 2: Astro Middleware for RFC 8288 Discovery Headers and Markdown Negotiation

To make sure every agent discovers your WebMCP manifest, MCP server card, and Markdown endpoints automatically, attach RFC 8288 `Link` headers and inspect the `Accept` header in your Astro middleware:

```
// src/middleware.ts (Excerpt from CodingCat.dev production middleware)
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  const origin = context.url.origin;
  const accept = context.request.headers.get("accept") || "";

  // If an AI agent sends Accept: text/markdown, rewrite transparently to the .md route
  if (
    accept.includes("text/markdown") &&
    !context.url.pathname.endsWith(".md") &&
    !context.url.pathname.startsWith("/api/")
  ) {
    const mdPath =
      context.url.pathname === "/" ? "/index.md" : `${context.url.pathname}/index.md`;
    return context.rewrite(mdPath);
  }

  const response = await next();
  response.headers.append(
    "Link",
    [
      `; rel="api-catalog"`,
      `; rel="mcp-server-card"`,
      `; rel="llms-txt"`,
      `; rel="agent-guide"`,
    ].join(", ")
  );
  return response;
});
```

## **Try the Live Browser AI & WebMCP Playground**

You can test every pattern from this article live right now in our interactive [**Web AI & WebMCP Playground**](/demos/web-ai) on CodingCat.dev, or inspect our production discovery manifests on the [**Developers & Agent APIs**](/developers) page. If you are organizing a developer conference or engineering summit, check out my Web AI talk abstracts on [**alexpatterson.dev**](https://alexpatterson.dev) and explore more hands-on [**Courses**](/courses), [**Podcasts**](/podcasts), and [**Blog Posts**](/blog) right here on CodingCat.dev.

## recent blog posts.

[All Blog Posts&rarr;](/blog)[![The Heads of AI wearing black company logo t-shirts and shaking hands in a circular web of cloud and GPU investments](https://cdn.sanity.io/images/hfh83o0w/production/d1d83d596ce5899d797cd3aaf1bd0142038f282a-1376x768.jpg?w=1376&q=82&fit=max&auto=format)](/post/anthropic-s1-ipo-circular-ai-economy-etf-risk)October 26, 2026[![](/logos/amplify/amplify.svg)![](/logos/amplify/amplify.svg)AWS Amplify](/topic/amplify)[AI & MCP Agents](/topic/ai)

### [Anthropic's S-1, $518B in cloud commitments, and circular AI capex](/post/anthropic-s1-ipo-circular-ai-economy-etf-risk)

Anthropic just filed its Form S-1 for a Nasdaq IPO under ticker ANT, revealing $518B in take-or-pay cloud commitments to Google, AWS, and Microsoft. Here is how Mark Zuckerberg, Elon Musk, Jensen Huang, Sundar Pichai, Satya Nadella, Tim Cook, and Dario Amodei built a circular revenue machine, and what happens to your S&P 500 ETF if it stalls.

[![Alex Patterson](https://cdn.sanity.io/images/hfh83o0w/production/a606dfaa381aab08ddbe16a33fe1d3e1fb37c927-400x400.jpg?w=96&h=96&q=82&fit=max&auto=format)Alex Patterson](/author/alex-patterson)[![PHP2Shell (CVE-2026-109618): How AI Found a Decade-Old Bug in 70% of the Web](https://cdn.sanity.io/images/hfh83o0w/production/e83065d0a4e2f841ce64d3f4aea8ddbbf07e5cb9-1376x768.jpg?w=1376&q=82&fit=max&auto=format)](/post/php2shell-cve-2026-109618-ai-php-security-scramble)October 22, 2026[![](/logos/amplify/amplify.svg)![](/logos/amplify/amplify.svg)AWS Amplify](/topic/amplify)[AI & MCP Agents](/topic/ai)

### [PHP2Shell (CVE-2026-109618): How AI Found a Decade-Old Bug in 70% of the Web](/post/php2shell-cve-2026-109618-ai-php-security-scramble)

Two critical pre-authentication RCE flaws in PHP (CVE-2026-109618 and CVE-2026-109619), uncovered by AI models from OpenAI and Google Gemini, sparked a global patching scramble across 70% of the web. Here is how PHP2Shell works and how to patch your servers.

[![Alex Patterson](https://cdn.sanity.io/images/hfh83o0w/production/a606dfaa381aab08ddbe16a33fe1d3e1fb37c927-400x400.jpg?w=96&h=96&q=82&fit=max&auto=format)Alex Patterson](/author/alex-patterson)