0027 — Serve the web app from the MCP server's origin
Status: Accepted; amended by ADR-0062 (the app’s pages forbid framing, and its files answer no other origin) Edited 2026-11-15 to remove deployment details. Date: 2026-11-05
Context and Problem Statement
Section titled “Context and Problem Statement”The SolidJS app in web/ (ADR-0003)
talks to chartgen over MCP and OAuth. ADR-0003 assumed the production app
and the backend would share one origin, but nothing deployed the app. The
Docker image that the container platform builds contained only the Rust binary, so opening
https://chartgen.example.com/ in a browser showed the JSON health
document, not the chart app.
GET / is also probed by health checks and by MCP clients, and existing
connectors were added with the root URL and send POST /. Any change has
to keep those requests working exactly as before.
Decision Drivers
Section titled “Decision Drivers”- One deploy (the root
Dockerfileon the container platform) without new platform settings or a second hosting service. - Same origin for the app and the API: no CORS, and OAuth
redirect_uriis justorigin + "/". - Non-browser requests to
/must keep getting the same JSON. - Running
chartgen --servewithout the web build must work as before. - Connectors must discover OAuth from the MCP URL they were given.
Considered Options
Section titled “Considered Options”Same origin, served by chartgen (chosen). The image builds web/dist
and chartgen serves it as static files next to its MCP and OAuth routes.
Separate static host (Cloudflare Pages). The app is built and hosted
on its own origin and calls the API through VITE_CHARTGEN_BASE_URL. This
needs a second deploy pipeline, CORS for every route, and OAuth redirects
across origins, and the two deploys can drift apart.
Backend only. Keep the image API-only and leave the app to local
npm run dev. The deployed URL would never show the app.
Decision Outcome
Section titled “Decision Outcome”Chosen option: same origin, served by chartgen.
CHARTGEN_WEB_DIRpoints at a builtweb/dist. Unset, chartgen serves no static files and behaves as before. The Dockerfile builds the app in anode:22-bookworm-slimstage with an emptyVITE_CHARTGEN_BASE_URL, copies it to/usr/share/chartgen/web, and setsCHARTGEN_WEB_DIRthere.- Routes:
/is the web app for browsers and the JSON health document for everyone else. AGET /whoseAcceptheader containstext/htmlgetsindex.html; any otherGET /gets the JSON. The OAuth callback (/?code=…&state=…) is a browser navigation, so it loads the app./mcpis the canonical MCP endpoint (POSTfor JSON-RPC,GETfor the SSE stream). Documentation nameshttps://<domain>/mcp(the deployment’s own host) as the connector URL.POST /is a deprecated compatibility alias for connectors added with the root URL, like the older/messageand/ssealiases. It is kept and not advertised.- All explicit routes (
/mcp,/sse,/message,/register,/authorize,/token,/.well-known/oauth-authorization-server,/.well-known/oauth-protected-resource,/.well-known/oauth-protected-resource/mcp,/favicon.*) take precedence. Static files are the router fallback, served by tower-httpServeDir, which rejects..paths. An unknownGETthat acceptstext/htmlgetsindex.html(SPA routing). Other unknown paths, including missing/assets/*files and non-GET requests, stay 404. Paths with a dot-prefixed segment (/.env,/.git/…) or a leading//are refused with 404 beforeServeDir.CHARTGEN_WEB_DIRmust hold only the build output: symlinks inside it are followed.
- Cache headers: hashed files under
/assets/getpublic, max-age=31536000, immutable. Everything else, includingindex.html, getsno-cache. All static responses carryX-Content-Type-Options: nosniff. - OAuth discovery from
/mcpfollows RFC 9728./.well-known/oauth-protected-resource/mcpdescribes the resource<base>/mcp, and/.well-known/oauth-protected-resourcedescribes<base>for the root alias. Both name<base>as the authorization server. A 401 from an MCP endpoint carriesWWW-Authenticate: Bearer resource_metadata="…"pointing at the matching document.
Consequences
Section titled “Consequences”- Good: one image, one origin, one deploy. Opening the public URL shows the app, and the OAuth redirect stays on the same origin.
- Good: health checks and MCP probes see no change. Root-URL connectors
keep working, but 401s from
/,/sseand/messagenow carry aWWW-Authenticate: Bearer resource_metadata="…"hint pointing at the root document (resource= base URL). - Good: connectors starting at
/mcpfind the authorization server through the 401 hint or the path-suffixed metadata. - Bad: the image build now also needs Node and
npm ci, which makes it slower and adds the web dependencies to the build. - Bad: telling browsers from other clients relies on
Accept: text/html. A client that sendstext/htmltoGET /gets HTML instead of JSON. - Neutral: the app and the server ship together and cannot be deployed
separately.
VITE_CHARTGEN_BASE_URLstill supports a separate host for anyone who wants one.
- Web stack: ADR-0003
- MCP transport and aliases: ADR-0002
- RFC 9728: OAuth 2.0 Protected Resource Metadata