Skip to content

Commit ca89cc2

Browse files
fix(website): a site's MCP calls through /svc carry the gateway's role, sites are found at once, and conformance reads every page
- A call to a site's MCP endpoint through /svc/<name>/ gets the gateway's role in its JSON-RPC _meta, as an MCP server's does, at the endpoint its card declares (site_mcp_endpoints), so a caller can't claim another role there. - The gateway asks every site for its card at once, so a site that never comes up leaves another its own retries. - Conformance reads every page of tools/list, fails a listed tool the card doesn't name, and warns on a card's tool it doesn't list, as a hidden-by-default one is listed to no caller. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 67af267 commit ca89cc2

6 files changed

Lines changed: 134 additions & 42 deletions

File tree

‎packages/agentenv-protocol/src/agentenv_protocol/website/conformance.py‎

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,10 @@
88
``sync_time`` against a clock the checker serves, and the forwarded headers wherever an answer shows them, on ``/`` and
99
on a GET route with its trailing slash toggled, which a server may redirect, and the cookies those answers set:
1010
none tied to a domain, and a warning for one whose lifetime is an absolute ``Expires`` with no ``Max-Age``. A site whose
11-
card declares an ``mcp`` interface, being an MCP server too, must answer ``initialize`` there and ``tools/list`` with
12-
the tools its card lists (streamable HTTP, ``MCP_PROTOCOL_VERSION``); a site without one skips that check.
11+
card declares an ``mcp`` interface, being an MCP server too, must answer ``initialize`` there and list, every page of
12+
``tools/list`` read, no tool its card doesn't (streamable HTTP, ``MCP_PROTOCOL_VERSION``); a card's tool it doesn't
13+
list is a warning, since a hidden-by-default tool is listed to no caller until one enables it. A site without one
14+
skips that check.
1315
1416
Every request goes to the server under check: a card's path or URL naming another scheme, host or port fails the check
1517
that would have used it, with nothing sent there. The round trip leaves the server's data as it found it, adding the
@@ -43,6 +45,7 @@
4345
CLOCK_START = datetime.datetime(2031, 5, 6, 7, 8, 9, tzinfo=datetime.timezone.utc)
4446
CLOCK_SLACK_S = 120
4547
MCP_PROTOCOL_VERSION = "2025-06-18"
48+
MCP_LIST_PAGES = 100
4649

4750

4851
@dataclasses.dataclass(frozen=True)
@@ -203,8 +206,9 @@ def _data_plane(self, card: dict) -> tuple[Status, str]:
203206
return "passed", f"{len(exported)} part(s) round-tripped through reset and add"
204207

205208
def _mcp(self, card: dict) -> tuple[Status, str]:
206-
"""The MCP endpoint the card declares answers ``initialize`` and lists the card's tools; its answers needn't
207-
carry ``X-Universe-Now``, which the MCP transport doesn't promise."""
209+
"""The MCP endpoint the card declares answers ``initialize`` and lists no tool the card doesn't, reading up to
210+
``MCP_LIST_PAGES`` pages of ``tools/list``; its answers needn't carry ``X-Universe-Now``, which the MCP
211+
transport doesn't promise."""
208212
interfaces = [i for i in card.get("additionalInterfaces") or [] if isinstance(i, dict)
209213
and i.get("transport") == MCP_TRANSPORT]
210214
if not interfaces:
@@ -223,18 +227,30 @@ def _mcp(self, card: dict) -> tuple[Status, str]:
223227
headers["Mcp-Session-Id"] = session
224228
try:
225229
self.client.post(url, headers=headers, json={"jsonrpc": "2.0", "method": "notifications/initialized"})
226-
listed = _mcp_result(self.client.post(url, headers=headers, json={
227-
"jsonrpc": "2.0", "id": "tools/list", "method": "tools/list"}), "tools/list")
230+
served: list = []
231+
cursor = None
232+
for _page in range(MCP_LIST_PAGES):
233+
listed = _mcp_result(self.client.post(url, headers=headers, json={
234+
"jsonrpc": "2.0", "id": "tools/list", "method": "tools/list",
235+
**({"params": {"cursor": cursor}} if cursor else {})}), "tools/list")
236+
served += [t.get("name") for t in listed.get("tools") or [] if isinstance(t, dict)]
237+
cursor = listed.get("nextCursor")
238+
if not cursor:
239+
break
240+
else:
241+
return "failed", f"tools/list at {path} still had a next page after {MCP_LIST_PAGES}"
228242
finally:
229243
if session:
230244
with contextlib.suppress(httpx.HTTPError):
231245
self.client.delete(url, headers=headers)
232-
served = sorted(t.get("name") for t in listed.get("tools") or [] if isinstance(t, dict))
233-
advertised = sorted(t.get("name") for t in (card.get("capabilities") or {}).get("tools") or []
234-
if isinstance(t, dict))
235-
if served != advertised:
236-
return "failed", f"tools/list at {path} named {served}, the card {advertised}"
237-
return "passed", f"{server.get('name') or 'the server'} at {path} lists the card's {len(served)} tool(s)"
246+
advertised = {t.get("name") for t in (card.get("capabilities") or {}).get("tools") or [] if isinstance(t, dict)}
247+
if unadvertised := sorted(set(served) - advertised):
248+
return "failed", f"tools/list at {path} named {unadvertised}, which the card doesn't list"
249+
name = server.get("name") or "the server"
250+
if unlisted := sorted(advertised - set(served)):
251+
return "warned", (f"{name} at {path} lists {len(served)} of the card's tools, not {unlisted}: hidden by "
252+
"default, or missing")
253+
return "passed", f"{name} at {path} lists the card's {len(served)} tool(s)"
238254

239255
def _clock(self, card: dict) -> tuple[Status, str]:
240256
if find_extension(card, CLOCK_EXTENSION_URI) is None:

‎packages/agentenv-protocol/tests/test_website_mcp.py‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -138,21 +138,27 @@ def _declaring(mcp: Route | None) -> Starlette:
138138
return Starlette(routes=routes + ([mcp] if mcp is not None else []))
139139

140140

141-
def _listing(*names: str) -> Route:
141+
def _listing(*pages: tuple[str, ...]) -> Route:
142+
"""An MCP endpoint whose tools/list answers ``pages`` in turn, each pointing at the next by its cursor."""
142143
async def answer(request: Request) -> Response:
143144
body = await request.json()
144145
if body.get("method") == "initialize":
145146
return JSONResponse({"jsonrpc": "2.0", "id": body["id"], "result": {"serverInfo": {"name": "x"}}})
146147
if body.get("method") == "tools/list":
147-
return JSONResponse({"jsonrpc": "2.0", "id": body["id"], "result": {"tools": [{"name": n} for n in names]}})
148+
at = int((body.get("params") or {}).get("cursor") or 0)
149+
result = {"tools": [{"name": n} for n in pages[at]], **({"nextCursor": str(at + 1)} if at + 1 < len(pages)
150+
else {})}
151+
return JSONResponse({"jsonrpc": "2.0", "id": body["id"], "result": result})
148152
return Response(status_code=202)
149153

150154
return Route("/mcp", answer, methods=["POST"])
151155

152156

153157
@pytest.mark.parametrize(("mcp", "status", "detail"), [
154-
(_listing("a"), "passed", "lists the card's 1 tool(s)"),
155-
(_listing("a", "b"), "failed", "named ['a', 'b'], the card ['a']"),
158+
(_listing(("a",)), "passed", "lists the card's 1 tool(s)"),
159+
(_listing((), ("a",)), "passed", "lists the card's 1 tool(s)"),
160+
(_listing(("a", "b")), "failed", "named ['b'], which the card doesn't list"),
161+
(_listing(()), "warned", "lists 0 of the card's tools, not ['a']: hidden by default, or missing"),
156162
(None, "failed", "initialize answered 404"),
157163
])
158164
def test_the_mcp_check_reads_the_endpoint_the_card_declares(mcp: Route | None, status: str, detail: str) -> None:
@@ -162,6 +168,24 @@ def test_the_mcp_check_reads_the_endpoint_the_card_declares(mcp: Route | None, s
162168
assert found[0] == status and detail in found[1], found
163169

164170

171+
def test_a_hidden_by_default_tool_on_the_card_warns_without_failing_the_run(tmp_path: Path) -> None:
172+
site = _shop(static=tmp_path)
173+
174+
class Gated(type(site)):
175+
tool_access = True
176+
177+
@tool(hidden_by_default=True)
178+
def refund(self, item: str) -> str:
179+
"""Refund an order."""
180+
return "refunded"
181+
182+
gated = environment_card(name="shop")(Gated)()
183+
with TestClient(gated.create_app()) as client:
184+
results = {r.name: r for r in conformance.check("http://testserver", client=client)}
185+
assert results["mcp"].status == "warned" and "['refund']" in results["mcp"].detail
186+
assert all(r.passed for r in results.values()), results
187+
188+
165189
def test_an_mcp_interface_on_another_server_fails_the_check_with_nothing_sent_there() -> None:
166190
sent = []
167191
client = httpx.Client(transport=httpx.MockTransport(lambda request: sent.append(request) or httpx.Response(500)))

‎src/agent_env/env/gateway/entrypoint.py‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -108,20 +108,19 @@ async def website_mcp_servers(sites: dict[str, str], taken: frozenset[str] = fro
108108
"""The sites, by name at the address their server answers, that are MCP servers too: each as an internal server at
109109
the MCP endpoint its card declares, so the gateway serves its tools as it does an MCP env's. A site whose card
110110
declares no MCP interface, or that answers no card, is left out, as is one named as an internal server already
111-
(``taken``). A site whose server can't be reached yet is asked again until ``timeout_s``."""
112-
found: list[InternalMCPServer] = []
111+
(``taken``). Every site is asked at once, and one whose server can't be reached yet is asked again until
112+
``timeout_s``."""
113+
asked = {name: url.rstrip("/") for name, url in sites.items() if name not in taken}
113114
deadline = time.monotonic() + timeout_s
114115
async with httpx.AsyncClient() as client:
115-
for name, base_url in sites.items():
116-
if name in taken:
117-
continue
118-
base = base_url.rstrip("/")
119-
card = await _site_card(client, name, base, deadline)
120-
path = next((i.get("url") for i in (card or {}).get("additionalInterfaces") or []
121-
if isinstance(i, dict) and i.get("transport") == MCP_TRANSPORT and i.get("url")), None)
122-
if isinstance(path, str) and path.startswith("/"):
123-
logger.info(f"Site {name} is an MCP server at {path}")
124-
found.append(InternalMCPServer(name=name, mcp_url=f"{base}{path}"))
116+
cards = await asyncio.gather(*(_site_card(client, name, base, deadline) for name, base in asked.items()))
117+
found: list[InternalMCPServer] = []
118+
for (name, base), card in zip(asked.items(), cards):
119+
path = next((i.get("url") for i in (card or {}).get("additionalInterfaces") or []
120+
if isinstance(i, dict) and i.get("transport") == MCP_TRANSPORT and i.get("url")), None)
121+
if isinstance(path, str) and path.startswith("/"):
122+
logger.info(f"Site {name} is an MCP server at {path}")
123+
found.append(InternalMCPServer(name=name, mcp_url=f"{base}{path}"))
125124
return found
126125

127126

‎src/agent_env/env/gateway/gateway.py‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ def __init__(
153153
self.internal_mcp_servers = internal_mcp_servers
154154
self.website_urls = website_urls or {}
155155
self.rest_proxy_urls = rest_proxy_urls or {}
156+
self._site_mcp_endpoints = site_mcp_endpoints(internal_mcp_servers, self.website_urls, self.rest_proxy_urls)
156157
self._site_reserved: dict[str, frozenset[str]] = {}
157158
self._withheld = frozenset(name.strip().lower().encode() for name in provider_headers if name.strip())
158159
self._browsers = BrowserRoutes(self.rest_proxy_urls, self.REST_PROXY_TIMEOUT, self._log_event,
@@ -651,12 +652,14 @@ async def _proxy_rest_request(self, request: Request, url_map: dict[str, str] |
651652
if base_url is None:
652653
return self._json_response({"error": f"Unknown service: {service_name}"}, 404)
653654
role = self._request_role(request)
654-
mcp_server = url_map is self.rest_proxy_urls and service_name.startswith("mcp-")
655+
site_mcp = self._site_mcp_endpoints.get(service_name) if url_map is self.rest_proxy_urls else None
656+
mcp_server = url_map is self.rest_proxy_urls and (service_name.startswith("mcp-") or site_mcp is not None)
657+
mcp_endpoint = site_mcp or "mcp"
655658
if url_map is self.rest_proxy_urls and (cdp := await self._browsers.cdp_answer(request, base_url, role)) is not None:
656659
return cdp
657660
if request.method in _SAFE_METHODS:
658661
return await forward(request, base_url, role=role, timeout=self.REST_PROXY_TIMEOUT, mcp_server=mcp_server,
659-
withheld=self._withheld)
662+
withheld=self._withheld, mcp_endpoint=mcp_endpoint)
660663
changelog_before = self._query_changelog_id()
661664
attribution = self._attribution(role) # at the start: a fire may be gone by the time the response ends
662665

@@ -681,7 +684,7 @@ async def log_write(status: int) -> None:
681684
})
682685

683686
return await forward(request, base_url, role=role, timeout=self.REST_PROXY_TIMEOUT, mcp_server=mcp_server,
684-
on_done=log_write, withheld=self._withheld)
687+
on_done=log_write, withheld=self._withheld, mcp_endpoint=mcp_endpoint)
685688

686689
async def _proxy_website_request(self, request: Request) -> Response:
687690
"""Proxy a website request; with a website or state trigger registered, feed it to the engine and hold barriers.
@@ -1668,6 +1671,18 @@ def reserved_site_path(path: str, reserved: frozenset[str] = frozenset()) -> boo
16681671
for base in (RPC_PATH, *reserved))
16691672

16701673

1674+
def site_mcp_endpoints(servers: list[InternalMCPServer], website_urls: dict[str, str],
1675+
rest_proxy_urls: dict[str, str]) -> dict[str, str]:
1676+
"""The MCP endpoint, as a path under its /svc/<name>/ base, of each site that is an internal MCP server too, by
1677+
name: where a call through /svc/<name>/ gets the gateway's role in its JSON-RPC ``_meta``, as an MCP server's does."""
1678+
endpoints = {}
1679+
for server in servers:
1680+
base = rest_proxy_urls.get(server.name, "").rstrip("/")
1681+
if server.name in website_urls and base and server.mcp_url.startswith(base + "/"):
1682+
endpoints[server.name] = server.mcp_url[len(base):]
1683+
return endpoints
1684+
1685+
16711686
def site_reserved_paths(card: dict) -> frozenset[str]:
16721687
"""The paths a site's card advertises for agentenv, which its route never reaches: its ``url``, every interface's,
16731688
such as the MCP endpoint of a site that is an MCP server too, and every extension's endpoint and each of its

‎src/agent_env/env/gateway/rest_proxy.py‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -86,19 +86,19 @@
8686

8787
async def forward(request: Request, base_url: str, *, role: str, timeout: httpx.Timeout, mcp_server: bool,
8888
on_done: Callable[[int], Awaitable[None]] | None = None,
89-
withheld: frozenset[bytes] = frozenset()) -> Response:
89+
withheld: frozenset[bytes] = frozenset(), mcp_endpoint: str = "mcp") -> Response:
9090
"""Forward `request` to the service at `base_url` as `role`, without the headers named in `withheld`, and stream
9191
the response through. `mcp_server` says
92-
the service is a backing MCP server, whose own endpoint takes the role in its JSON-RPC `_meta` as well as in the
93-
header. A 400 names a request-target the proxy cannot route; a 502 names an upstream that never answered.
92+
the service is a backing MCP server, whose own endpoint, `mcp_endpoint` under it, takes the role in its JSON-RPC
93+
`_meta` as well as in the header. A 400 names a request-target the proxy cannot route; a 502 names an upstream that never answered.
9494
`on_done` is awaited with the status once the response has ended, after its last byte when streamed."""
9595
try:
9696
target_url = upstream_url(base_url, request)
9797
except ValueError as e: # an escaped slash inside the route prefix; refuse rather than forward a wrong path
9898
return await _done(_json_response({"error": str(e)}, 400), on_done)
9999
content = await request.body() # /svc and /website request bodies are small (JSON-RPC, forms)
100100
headers = upstream_headers(request, role, withheld=withheld)
101-
if mcp_server and request.method == "POST" and is_child_mcp_path(request.path_params.get("path", "")):
101+
if mcp_server and request.method == "POST" and is_child_mcp_path(request.path_params.get("path", ""), mcp_endpoint):
102102
# The gateway is the trust boundary for identity: a child's proxied MCP endpoint stays reachable, but the
103103
# role in its JSON-RPC `_meta` is the gateway's to write, like the header above.
104104
content = stamp_jsonrpc_role(content, role)
@@ -187,15 +187,19 @@ def route_prefix(request: HTTPConnection) -> str:
187187
return raw_path.decode("latin-1").rstrip("/")
188188

189189

190-
def is_child_mcp_path(decoded_rest: str) -> bool:
191-
"""Whether a /svc/{service}/{path} remainder reaches the backing server's MCP endpoint (`mcp` or anything under
192-
it), judged after dot-segment normalisation, since httpx collapses `x/../mcp` to `/mcp` on the way upstream.
190+
def is_child_mcp_path(decoded_rest: str, endpoint: str = "mcp") -> bool:
191+
"""Whether a /svc/{service}/{path} remainder reaches the backing server's MCP endpoint (`endpoint`, `mcp` unless
192+
its card declares another, or anything under it), judged after dot-segment normalisation, since httpx collapses
193+
`x/../mcp` to `/mcp` on the way upstream.
193194
194195
>>> [is_child_mcp_path(p) for p in ("mcp", "mcp/", "mcp/x", "x/../mcp", "./mcp", "/mcp", "mcpx", "agentenv", "")]
195196
[True, True, True, True, True, True, False, False, False]
197+
>>> [is_child_mcp_path(p, "/tools/mcp/") for p in ("tools/mcp", "tools/x/../mcp", "mcp")]
198+
[True, True, False]
196199
"""
197200
normalized = posixpath.normpath("/" + decoded_rest.lstrip("/"))
198-
return normalized == "/mcp" or normalized.startswith("/mcp/")
201+
at = posixpath.normpath("/" + endpoint.strip("/"))
202+
return normalized == at or normalized.startswith(at + "/")
199203

200204

201205
def stamp_jsonrpc_role(body: bytes, role: str) -> bytes:

0 commit comments

Comments
 (0)