From 2d5f4423ab52b31a5bbb6a5c73257102cd373880 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 20 Jul 2026 22:50:49 +0200 Subject: [PATCH 1/3] docs(discovery): recommend ETag revalidation Document opaque entity tags and conditional requests for AI Catalogs and Server Cards, including the CORS headers needed by browser clients.\n\nRefs #33\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>\nCopilot-Session: a1429be2-5e67-4475-92c1-081657fe049e --- docs/discovery.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 59dd287..1f201f8 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -239,25 +239,38 @@ treat a Server Card as authoritative and reconcile it against the live connectio ### CORS Requirements -Hosted Server Card endpoints MUST include appropriate CORS headers to allow browser-based -clients: +Hosted AI Catalog and Server Card endpoints MUST include appropriate CORS headers to allow +browser-based clients: ``` Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET -Access-Control-Allow-Headers: Content-Type +Access-Control-Allow-Headers: Content-Type, If-None-Match +Access-Control-Expose-Headers: ETag ``` -This is safe because Server Cards contain only public metadata and are read-only. +This is safe because these documents contain only public metadata and are read-only. ### Caching -Server Card hosts SHOULD include caching headers to reduce unnecessary requests: +Hosts serving AI Catalogs or Server Cards SHOULD include caching headers to reduce unnecessary +requests: ``` Cache-Control: public, max-age=3600 ``` +Hosts SHOULD also return an `ETag` response header. Entity tags are opaque HTTP validators; this +specification does not prescribe their form. + +After receiving an `ETag`, clients SHOULD send its value in the `If-None-Match` header on +subsequent requests for the same resource. Hosts SHOULD honor `If-None-Match` and return +`304 Not Modified` when the selected representation has not changed. This complements +`Cache-Control`: fresh responses avoid requests, while entity-tag validation avoids transferring +an unchanged document after it becomes stale. + +MCP Clients SHOULD respect `Cache-Control` headers and avoid unnecessary polling. + ### Transport Security Hosted Server Cards MUST be served over HTTPS (TLS 1.2 or later) in production. HTTP MAY @@ -266,5 +279,3 @@ be used for local development only. ### Denial of Service MCP Servers SHOULD implement rate limiting on their Server Card endpoint to prevent abuse. - -MCP Clients SHOULD respect `Cache-Control` headers and avoid unnecessary polling. From 9ec96c0c741bf473656ce69dcd3b737527b4bcc4 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 20 Jul 2026 22:51:17 +0200 Subject: [PATCH 2/3] docs(discovery): scope ETags to Server Cards Keep the normative caching and CORS requirements within the Server Card extension rather than applying them to the external AI Catalog specification.\n\nRefs #33\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>\nCopilot-Session: a1429be2-5e67-4475-92c1-081657fe049e --- docs/discovery.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 1f201f8..e0e87de 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -239,8 +239,8 @@ treat a Server Card as authoritative and reconcile it against the live connectio ### CORS Requirements -Hosted AI Catalog and Server Card endpoints MUST include appropriate CORS headers to allow -browser-based clients: +Hosted Server Card endpoints MUST include appropriate CORS headers to allow browser-based +clients: ``` Access-Control-Allow-Origin: * @@ -249,12 +249,11 @@ Access-Control-Allow-Headers: Content-Type, If-None-Match Access-Control-Expose-Headers: ETag ``` -This is safe because these documents contain only public metadata and are read-only. +This is safe because Server Cards contain only public metadata and are read-only. ### Caching -Hosts serving AI Catalogs or Server Cards SHOULD include caching headers to reduce unnecessary -requests: +Server Card hosts SHOULD include caching headers to reduce unnecessary requests: ``` Cache-Control: public, max-age=3600 From ae1353ddf63a1a9998a68387d715250166b4128c Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 20 Jul 2026 22:54:34 +0200 Subject: [PATCH 3/3] docs(discovery): link DoS guidance to ETags Keep the anti-polling recommendation in the denial-of-service section while linking it to the conditional caching behavior.\n\nRefs #33\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>\nCopilot-Session: a1429be2-5e67-4475-92c1-081657fe049e --- docs/discovery.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index e0e87de..bc4bdf7 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -268,8 +268,6 @@ subsequent requests for the same resource. Hosts SHOULD honor `If-None-Match` an `Cache-Control`: fresh responses avoid requests, while entity-tag validation avoids transferring an unchanged document after it becomes stale. -MCP Clients SHOULD respect `Cache-Control` headers and avoid unnecessary polling. - ### Transport Security Hosted Server Cards MUST be served over HTTPS (TLS 1.2 or later) in production. HTTP MAY @@ -278,3 +276,6 @@ be used for local development only. ### Denial of Service MCP Servers SHOULD implement rate limiting on their Server Card endpoint to prevent abuse. + +MCP Clients SHOULD respect `Cache-Control` headers, use returned `ETag` validators as described +in [Caching](#caching), and avoid unnecessary polling.