[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.

E2E (agent-environments-admin VM, real gateway, local sandbox, Nov 6)

A shop site with two tools (place_order, count_orders), the Notes site without, and an MCP env in one multi env, with the run's website browser, at merge 555ab9b:

• The gateway lists the shop's tools beside the MCP env's, and none for Notes. Calls through the gateway's /mcp act on the site: its API, its data/get and its page in the website browser all show the orders, with the caller's role (agent) in ToolContext.
• /website/shop/mcp answers 404 (GET and POST); through /svc/shop/mcp a _meta role of admin sent with role default reaches the tool as the default role.
• Conformance through /svc/shop: the mcp check passes (2 tools); through /svc/notes it's skipped.
• Chaos: 30 concurrent tool calls 30/30 on a warm deploy; a site restart and a gateway restart each keep the tools working.
• The gateway doesn't start while a site's card can't be read (bc3a539), as it already doesn't for an MCP server that never comes up; a site answering no card counts as up with no tools. Before it, a site down past 180 s left the gateway up without its tools for good. Rerun at bc3a539: with the shop down 20 s the gateway starts once it answers (23 s), with its tools; down past 180 s, the gateway exits with RuntimeError: Website card(s) not readable after 180s: shop, compose restarts it (on-failure), and it comes up with the shop's tools once the shop is back (203 s).
• The mcp check is required (after feat(website): a session cookie per site, and conformance levels (FD-4683) #444's levels): through /svc/shop it passes, through /svc/notes it's skipped.
• Rerun at 493f52f with a second shop whose card names its MCP endpoint relatively (mcp): its tools are served and its mcp check passes; /website/<site>/mcp (and ./mcp) answers 404 for both shops, and a _meta role of admin through /svc/ reaches the tool as the default role. The same call against the gateway before the fix (bc3a539) reached the relative shop's endpoint through /website/shoprel/mcp and ran as admin. Chaos: 30/30 concurrent calls, a site restart, and a gateway restart with that shop down 20 s (up at 23 s with its tools).
• Found, not from this PR: the first burst of 30 concurrent calls after the server behind them restarts partly fails with "Connection closed" (18/30 for the site's tool, 24/30 for the MCP env's), and the next burst is 30/30.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the previously reported relative-path gap is fixed.

Summary

Websites can serve MCP tools alongside their pages. The gateway discovers these tools from each website's card, and conformance checks the declared endpoint.

• Website tools run beside a site's pages and data.
• The gateway serves tools from websites that declare MCP on their cards.
• Website browsing blocks the interface paths listed on a site's card.
• Website conformance checks MCP endpoints declared on a site's card.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Card[Website card] --> Discovery[Gateway discovers MCP endpoint]
  Discovery --> Tools[Gateway tool routes]
  Tools --> Site[Website tools and shared data]
  Browser[Browser request] --> Check{Reserved path?}
  Check -->|Yes| Block[404]
  Check -->|No| Pages[Website pages]

Loading

_{Reviews (11) · Last reviewed commit: "fix(gateway): an MCP endpoint a site's c..." · Reviewed by Greptile}