fix(mcp): RFC 9728 protected-resource metadata path + audience binding

Codex/RFC review showed that Claude Desktop addresses the MCP resource
as <PUBLIC_URL>/mcp (the streamable-HTTP endpoint) rather than the
base URL. Per RFC 9728 the protected-resource metadata then lives at
.well-known/oauth-protected-resource inserted between host and path:

  https://mcp.buildmymcpserver.com/.well-known/oauth-protected-resource/<slug>/mcp

Runner template now:
  - publishes `resource: <PUBLIC_URL>/mcp`
  - sets WWW-Authenticate to the RFC 9728 well-known URL
  - serves /.well-known/oauth-protected-resource[/*] so the metadata
    answers at both the legacy and RFC paths during transition
  - accepts both audiences (<PUBLIC_URL>/mcp + <PUBLIC_URL>) during
    rollout so already-issued tokens keep working

API:
  - resolveServerByResource() tries port first, then path segment
    (production path-routing), with a guard against treating "mcp" as
    a tenant slug
  - AS metadata advertises resource_parameter_supported: true

nginx (scripts/setup-runner-tls.sh + scripts/bmm-mcp-runners.nginx):
  - new location matches /.well-known/oauth-protected-resource/<slug>/...
    and proxies to the slug's runner with the slug stripped, so the
    runner sees the local well-known path

Docs (oauth + api-reference) updated to the RFC paths.

apps/api/src/routes/oauth.ts

@@ -41,24 +41,9 @@ function pkceVerify(verifier: string, challenge: string, method: string): boolea
 async function resolveServerByResource(resource: string) {
   const url = new URL(resource);
 
-  // Path routing (the prod topology on mcp.buildmymcpserver.com): the slug
-  // is the first path segment. Has to be checked BEFORE the subdomain
-  // heuristic below, otherwise we extract "mcp" from "mcp.example.com/<slug>"
-  // and look up the wrong (or no) server. Claude Desktop's RFC 8707 resource
-  // parameter matches the `resource` field we publish in /.well-known/
-  // oauth-protected-resource, which is exactly the path-routed public URL.
-  const firstSegment = url.pathname.split('/').filter(Boolean)[0];
-  if (firstSegment) {
-    const [s] = await db
-      .select()
-      .from(mcpServers)
-      .where(eq(mcpServers.slug, firstSegment))
-      .limit(1);
-    if (s) return s;
-  }
-
-  // Port-based lookup — used in local dev where the runner is reached
-  // directly at http://<RUNNER_HOST>:<port>.
+  // Local direct runner URLs are addressed by host port, e.g.
+  // http://localhost:4103/mcp. Resolve those before path routing so the
+  // transport endpoint segment is not treated as a tenant slug.
   const port = url.port ? Number(url.port) : null;
   if (port !== null) {
     const [s] = await db
@@ -69,6 +54,22 @@ async function resolveServerByResource(resource: string) {
     if (s) return s;
   }
 
+  // Path routing (the prod topology on mcp.buildmymcpserver.com): the slug
+  // is the first path segment. Has to be checked BEFORE the subdomain
+  // heuristic below, otherwise we extract "mcp" from "mcp.example.com/<slug>/mcp"
+  // and look up the wrong server. Claude Desktop's RFC 8707 resource parameter
+  // matches the `resource` field we publish in RFC 9728 protected resource
+  // metadata, which is the path-routed MCP endpoint URL.
+  const firstSegment = url.pathname.split('/').filter(Boolean)[0];
+  if (firstSegment) {
+    const [s] = await db
+      .select()
+      .from(mcpServers)
+      .where(eq(mcpServers.slug, firstSegment))
+      .limit(1);
+    if (s) return s;
+  }
+
   // Subdomain routing — legacy / future <slug>.mcp.example.com setup.
   const slug = url.hostname.split('.')[0];
   if (slug && slug !== 'mcp') {
@@ -119,6 +120,7 @@ export async function oauthRoutes(app: FastifyInstance): Promise<void> {
         'none',
       ],
       scopes_supported: ['mcp:read', 'mcp:write'],
+      resource_parameter_supported: true,
     };
   };
   const asMetadataHandler = async (_req: unknown, reply: { send: (body: unknown) => unknown }) =>
@@ -439,4 +441,3 @@ export async function oauthRoutes(app: FastifyInstance): Promise<void> {
     });
   });
 }
-

apps/generator/src/lib/render.ts

@@ -59,9 +59,24 @@ import Fastify from 'fastify';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import { randomUUID } from 'node:crypto';
 
-const PUBLIC_URL = process.env.PUBLIC_URL ?? 'http://localhost:3000';
-const CONTROL_PLANE_URL = process.env.CONTROL_PLANE_URL ?? 'http://host.docker.internal:4000';
-const OAUTH_ISSUER = process.env.OAUTH_ISSUER ?? CONTROL_PLANE_URL + '/oauth';
+function stripTrailingSlash(value) {
+  return value.replace(/\\/$/, '');
+}
+
+function protectedResourceMetadataUrl(resourceUrl) {
+  const url = new URL(resourceUrl);
+  const resourcePath = url.pathname === '/' ? '' : url.pathname;
+  url.pathname = '/.well-known/oauth-protected-resource' + resourcePath;
+  url.hash = '';
+  return url.toString();
+}
+
+const PUBLIC_URL = stripTrailingSlash(process.env.PUBLIC_URL ?? 'http://localhost:3000');
+const CONTROL_PLANE_URL = stripTrailingSlash(process.env.CONTROL_PLANE_URL ?? 'http://host.docker.internal:4000');
+const OAUTH_ISSUER = stripTrailingSlash(process.env.OAUTH_ISSUER ?? CONTROL_PLANE_URL + '/oauth');
+const MCP_RESOURCE_URL = PUBLIC_URL + '/mcp';
+const PROTECTED_RESOURCE_METADATA_URL = protectedResourceMetadataUrl(MCP_RESOURCE_URL);
+const EXPECTED_AUDIENCES = Array.from(new Set([MCP_RESOURCE_URL, PUBLIC_URL]));
 const PORT = Number.parseInt(process.env.PORT ?? '3000', 10);
 
 const server = new McpServer(
@@ -75,15 +90,18 @@ const app = Fastify({ logger: { level: 'info' } });
 
 app.get('/health', async () => ({ ok: true }));
 
-app.get('/.well-known/oauth-protected-resource', async () => ({
-  resource: PUBLIC_URL,
+const protectedResourceMetadata = async () => ({
+  resource: MCP_RESOURCE_URL,
   authorization_servers: [OAUTH_ISSUER],
   bearer_methods_supported: ['header'],
   scopes_supported: ${JSON.stringify(spec.scopes)},
-}));
+});
+
+app.get('/.well-known/oauth-protected-resource', protectedResourceMetadata);
+app.get('/.well-known/oauth-protected-resource/*', protectedResourceMetadata);
 
 app.get('/.well-known/oauth-authorization-server', async () => {
-  const r = await fetch(CONTROL_PLANE_URL + '/oauth/.well-known/oauth-authorization-server');
+  const r = await fetch(CONTROL_PLANE_URL + '/.well-known/oauth-authorization-server/oauth');
   return await r.json();
 });
 
@@ -96,16 +114,17 @@ app.all('/mcp', async (request, reply) => {
   if (!auth || !auth.startsWith('Bearer ')) {
     return reply
       .code(401)
-      .header('WWW-Authenticate', \`Bearer resource_metadata="\${PUBLIC_URL}/.well-known/oauth-protected-resource"\`)
+      .header('WWW-Authenticate', \`Bearer resource_metadata="\${PROTECTED_RESOURCE_METADATA_URL}"\`)
       .send({ error: 'unauthorized' });
   }
   const token = auth.slice(7);
   try {
     const { payload } = await jwtVerify(token, JWKS, {
       issuer: OAUTH_ISSUER,
-      audience: PUBLIC_URL,
+      audience: EXPECTED_AUDIENCES,
     });
-    if (payload.aud !== PUBLIC_URL) {
+    const audiences = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
+    if (!audiences.some((aud) => EXPECTED_AUDIENCES.includes(aud))) {
       return reply.code(403).send({ error: 'invalid_audience' });
     }
   } catch (e) {

apps/web/app/docs/api-reference/page.tsx

@@ -60,7 +60,7 @@ export default function ApiReference() {
 
       <DocsH2 id="oauth">OAuth (clients of generated servers, not dashboard)</DocsH2>
       <DocsP>
-        <Mono>GET /oauth/.well-known/oauth-authorization-server</Mono> — RFC 8414 metadata.
+        <Mono>GET /.well-known/oauth-authorization-server/oauth</Mono> — RFC 8414 metadata.
       </DocsP>
       <DocsP><Mono>GET /oauth/jwks</Mono> — RS256 public key for verifying access tokens.</DocsP>
       <DocsP><Mono>POST /oauth/register</Mono> — RFC 7591 dynamic client registration.</DocsP>

apps/web/app/docs/oauth/page.tsx

@@ -24,8 +24,8 @@ export default function OAuthDocs() {
       <DocsH2 id="rfcs">Standards we follow</DocsH2>
       <DocsList>
         <DocsLi>OAuth 2.1 draft (<Mono>draft-ietf-oauth-v2-1</Mono>) — no implicit, mandatory PKCE</DocsLi>
-        <DocsLi>RFC 8414 — Authorization Server Metadata at <Mono>/.well-known/oauth-authorization-server</Mono></DocsLi>
-        <DocsLi>RFC 9728 — Protected Resource Metadata at <Mono>/.well-known/oauth-protected-resource</Mono></DocsLi>
+        <DocsLi>RFC 8414 — Authorization Server Metadata at <Mono>/.well-known/oauth-authorization-server/oauth</Mono></DocsLi>
+        <DocsLi>RFC 9728 — Protected Resource Metadata at <Mono>/.well-known/oauth-protected-resource/&lt;server-path&gt;</Mono></DocsLi>
         <DocsLi>RFC 8707 — Resource Indicators (audience binding)</DocsLi>
         <DocsLi>RFC 7591 — Dynamic Client Registration</DocsLi>
       </DocsList>
@@ -41,7 +41,7 @@ export default function OAuthDocs() {
         code={`$ curl -i http://localhost:4103/mcp -d '{}' -H 'content-type: application/json'
 
 HTTP/1.1 401 Unauthorized
-www-authenticate: Bearer resource_metadata="http://localhost:4103/.well-known/oauth-protected-resource"
+www-authenticate: Bearer resource_metadata="http://localhost:4103/.well-known/oauth-protected-resource/mcp"
 content-type: application/json
 
 {"error":"unauthorized"}`}
@@ -53,10 +53,10 @@ content-type: application/json
       </DocsP>
       <DocsCode
         label="step 2 — resource metadata"
-        code={`$ curl http://localhost:4103/.well-known/oauth-protected-resource
+        code={`$ curl http://localhost:4103/.well-known/oauth-protected-resource/mcp
 
 {
-  "resource": "http://localhost:4103",
+  "resource": "http://localhost:4103/mcp",
   "authorization_servers": ["http://localhost:4000/oauth"],
   "bearer_methods_supported": ["header"],
   "scopes_supported": ["mcp:read"]
@@ -74,7 +74,7 @@ content-type: application/json
   "client_name": "Claude Desktop",
   "redirect_uris": ["claude://oauth/callback"],
   "token_endpoint_auth_method": "none",
-  "resource": "http://localhost:4103"
+  "resource": "http://localhost:4103/mcp"
 }
 
 201 Created
@@ -94,7 +94,7 @@ content-type: application/json
   "code_verifier": "riSU-w1DT…",
   "client_id": "bmm_8aee2fe0…",
   "redirect_uri": "claude://oauth/callback",
-  "resource": "http://localhost:4103"
+  "resource": "http://localhost:4103/mcp"
 }
 
 200 OK
@@ -109,7 +109,7 @@ content-type: application/json
       <DocsP>
         Subsequent <Mono>/mcp</Mono> calls carry the JWT. The runner verifies the signature
         against the AS&apos;s JWKS, checks the <Mono>iss</Mono>, the <Mono>aud</Mono>
-        (RFC 8707 — must match the runner&apos;s own public URL), and the expiry. No token
+        (RFC 8707 — must match the runner&apos;s MCP resource URL), and the expiry. No token
         passthrough; the runner never forwards the client&apos;s token to a downstream API.
       </DocsP>
 

scripts/bmm-mcp-runners.nginx

@@ -0,0 +1,80 @@
+# BMM per-runner proxy via PATH routing on mcp.buildmymcpserver.com.
+# The combined snippet file (regenerated by the bmm-api and bmm-generator
+# containers + reloaded by the systemd inotify watcher) is a sequence of
+# `if ($bmm_slug = "<slug>") { set $bmm_port <port>; }` lines that map the
+# slug captured from the URL path to the local runner port.
+
+server {
+  listen 80;
+  listen [::]:80;
+  listen 443 ssl http2;
+  listen [::]:443 ssl http2;
+  server_name mcp.buildmymcpserver.com;
+
+  ssl_certificate     /etc/ssl/buildmymcpserver/mcp-runners.crt;
+  ssl_certificate_key /etc/ssl/buildmymcpserver/mcp-runners.key;
+
+  client_max_body_size 4M;
+
+  # Cheap health probe for monitoring — doesn't go through the slug router.
+  location = /health {
+    return 200 "ok\n";
+    add_header Content-Type text/plain;
+  }
+
+  # RFC 9728 for path-routed resources:
+  # /<slug>/mcp derives metadata at /.well-known/oauth-protected-resource/<slug>/mcp.
+  # Route that well-known URL back to the same runner while preserving only the
+  # resource sub-path after the slug.
+  location ~ ^/\.well-known/oauth-protected-resource/(?<bmm_slug>[a-z0-9][a-z0-9-]*)(?<bmm_path>/.*)?$ {
+    set $bmm_port "";
+    include /opt/buildmymcpserver/runner-map.combined;
+
+    if ($bmm_port = "") {
+      return 404;
+    }
+
+    proxy_pass http://127.0.0.1:$bmm_port/.well-known/oauth-protected-resource$bmm_path;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto https;
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 600s;
+  }
+
+  # /<slug>/<rest> → 127.0.0.1:<port>/<rest>
+  location ~ ^/(?<bmm_slug>[a-z0-9][a-z0-9-]*)(?<bmm_path>/.*)?$ {
+    set $bmm_port "";
+    include /opt/buildmymcpserver/runner-map.combined;
+
+    # Unknown slug — return 404 instead of a confusing default.
+    if ($bmm_port = "") {
+      return 404;
+    }
+
+    # Default sub-path to /  when client asked for /<slug> with no trailing slash.
+    set $bmm_target_path $bmm_path;
+    if ($bmm_target_path = "") {
+      set $bmm_target_path "/";
+    }
+
+    proxy_pass http://127.0.0.1:$bmm_port$bmm_target_path;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto https;
+    # MCP uses Streamable HTTP — disable buffering so response chunks flow.
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 600s;
+  }
+
+  # Root of mcp.buildmymcpserver.com — nothing to serve here.
+  location = / {
+    return 404;
+  }
+}

scripts/setup-runner-tls.sh

@@ -105,6 +105,29 @@ server {
     add_header Content-Type text/plain;
   }
 
+  # RFC 9728 for path-routed resources:
+  # /<slug>/mcp derives metadata at /.well-known/oauth-protected-resource/<slug>/mcp.
+  # Route that well-known URL back to the same runner while preserving only the
+  # resource sub-path after the slug.
+  location ~ ^/\.well-known/oauth-protected-resource/(?<bmm_slug>[a-z0-9][a-z0-9-]*)(?<bmm_path>/.*)?$ {
+    set $bmm_port "";
+    include /opt/buildmymcpserver/runner-map.combined;
+
+    if ($bmm_port = "") {
+      return 404;
+    }
+
+    proxy_pass http://127.0.0.1:$bmm_port/.well-known/oauth-protected-resource$bmm_path;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto https;
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 600s;
+  }
+
   # /<slug>/<rest> → 127.0.0.1:<port>/<rest>
   location ~ ^/(?<bmm_slug>[a-z0-9][a-z0-9-]*)(?<bmm_path>/.*)?$ {
     set $bmm_port "";