[williamloo-scale]

A website env can now also be an MCP server. A site gives agents tools beside its pages, its card declares them, and the gateway serves them as it does an MCP env's. Stacked on #429 (the Notes example, rebased onto main after #428 merged). The Notes example skips the new mcp check, since it serves no tools.

What changes

• SDK (agentenv_protocol.website):
  • A WebsiteEnvironment with @tool or @resource methods serves them at /mcp (streamable HTTP, needs the mcp package). They run in the site's own process, beside its pages, @api routes and data plane, so a tool call changes what the pages show and what data/get returns, and it reads the universe clock (self.now()).
  • The card declares the endpoint as its mcp interface (additionalInterfaces) and lists the tools under capabilities.tools.
  • A site without tools serves no /mcp and declares no interface. serves_mcp() tells you which kind a site is.
• Gateway:
  • At startup the gateway reads each site's card. When a card declares an mcp interface, the gateway adds the site as an internal MCP server, so agents see its tools with the rest, called with the caller's role in ToolContext.
  • This is decided from the card, not from stored config, and needs no compose changes. A site that answers no card, or declares no interface, is left out.
• Reserved paths: site_reserved_paths now includes a card's interfaces, so the browsing route (/website/<name>/) never reaches a site's /mcp, as with the data plane.
• Conformance: a new mcp check. When the card declares the interface, the endpoint must answer initialize and tools/list must name exactly the card's tools. A site without one skips the check.
• README: a "Websites with tools" section.

Tests

• packages/agentenv-protocol/tests/test_website_mcp.py:
  • the card declares /mcp and its tools;
  • a tool call changes what the site's API and data/get return, with the caller's role and X-Universe-Now;
  • a site without tools serves no /mcp;
  • conformance passes with tools and skips without them;
  • the mcp check fails on a tools mismatch or a missing endpoint, and sends nothing when the interface names another server.
• tst/unit/env/gateway/website_mcp_test.py:
  • finding sites from their cards (retrying a site that isn't up yet, skipping names already taken, no card, other transports);
  • interfaces counted as reserved paths;
  • end to end on loopback, a real site and a real gateway: the gateway lists and calls the site's tool with the caller's role, /website/shop/mcp answers 404, and /svc/shop/agentenv data/get sees the order the tool placed.
• Full suite: 13,337 passed and 7 failed.
  • 6 of the 7 fail on unmodified main on this machine too: cua_driver_test, test_disk_recipe and two in test_optional_extras_stay_optional.
  • The 7th, process_scope_socket_test::test_an_armed_time_trigger_keeps_firing_after_a_client_leaves, is a timing test that failed under full-suite load and passed 5 out of 5 on its own. tst/unit/env/gateway passes on its own (810 tests).
  • ruff is clean.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no blocking issues remain.

Summary

Websites can serve MCP tools beside their pages. The gateway discovers those tools from each site's card and keeps MCP endpoints out of browser routes.

• Website environments can serve tools beside their pages.
• The gateway serves tools from websites that declare an MCP endpoint.
• Website conformance checks compare MCP tools with the site card.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Card[Website card] --> Discovery[Gateway discovery]
  Discovery --> Tools[Gateway tools]
  Tools --> MCP[Website MCP endpoint]
  Service[Service route] --> Stamp[Gateway writes caller role]
  Stamp --> MCP
  Browser[Browser route] --> Block[Declared MCP path returns 404]

Loading

_{Reviews (7) · Last reviewed commit: "fix(website): a full MCP URL on a site b..." · Reviewed by Greptile}