@lovable.dev/mcp-js 0.8.0 → 0.9.1

package/README.md

@@ -53,6 +53,8 @@ MCP (`POST /mcp`) is the public wire format clients speak directly. REST (`/.mcp
 
 The OAuth metadata route is emitted by default and returns `404` until OAuth auth is configured. Disable it with `mcpPlugin({ protectedResourceMetadataRoute: false })` only if the app owns `/.well-known/oauth-protected-resource` itself.
 
+To serve the metadata from a different path — e.g. a workspace-private project where only `/api/public/*` is anonymously reachable and `/.well-known/...` is gated — pass `mcpPlugin({ metadataPath: "/api/public/.well-known/oauth-protected-resource" })`. The plugin emits the route there and injects the same path into every handler, so the 401 `WWW-Authenticate` challenge advertises exactly what it serves. `metadataPath` is mutually exclusive with `auth.protectedResourceMetadataUrl` (and with `protectedResourceMetadataRoute: false`).
+
 ### `.lovable/mcp/manifest.json`
 
 `.lovable/mcp/manifest.json` is a snapshot the Lovable platform reads to register the MCP server. Envelope fields: `version` (manifest schema version), `sdk_version` (the `@lovable.dev/mcp-js` release that wrote the snapshot), `path`, and `auth`. `auth` is the server's auth configuration, lifted into the envelope (not into `mcp`): `{ "type": "none" }`, or `{ "type": "oauth", ... }` mirroring the `defineMcp({ auth })` config (snake_case — `issuer`, `accepted_audiences`, `required_scopes`, `resource`, …). The `mcp` field is **exactly the `GET /.mcp/list-tools` body** — `server` plus the tool catalog (`name`/`title`/`description`/`annotations` and JSON-Schema `inputSchema`/`outputSchema`) — so the committed snapshot can't drift from what the live route serves. It's produced by loading the entry and reading the catalog off the `defineMcp` result, so the manifest reflects exactly what the server exposes, including tools built programmatically (spreads, computed names, tools from npm). **The `lovable-mcp-extract-manifest` CLI writes it** (loading the entry through Vite's SSR module loader, so it works under Node/Bun), and removes it when the entry is deleted. The Lovable platform runs the CLI in its commit pipeline; the Vite plugin only generates routes. Commit it: the platform reads the committed file.
@@ -182,7 +184,7 @@ Use an OAuth access token from the configured authorization server for MCP calls
 | `algorithms` | Accepted JWT signing algorithms. Defaults to asymmetric algorithms (`RS*`, `ES*`, `EdDSA`); set explicitly only for a narrower policy. |
 | `clockToleranceSeconds` | Allowed JWT clock skew for `exp`/`nbf` checks, in seconds. Defaults to `30`; max `300`. |
 | `resourceName`, `resourceDocumentation` | Optional metadata fields for MCP clients and humans. `resourceName` defaults to the MCP server `title`. |
-| `protectedResourceMetadataUrl` | Absolute HTTPS URL of an externally hosted RFC 9728 protected-resource metadata document. When set, the SDK advertises this URL in the 401 `WWW-Authenticate: resource_metadata` challenge and stops generating its own metadata — the `/.well-known/oauth-protected-resource` handler returns 404. Use it when the resource server already publishes its own PRM; you'll typically also pass `protectedResourceMetadataRoute: false` to the Vite plugin so the now-unused route isn't emitted. |
+| `protectedResourceMetadataUrl` | Absolute HTTPS URL of an externally hosted RFC 9728 protected-resource metadata document. When set, the SDK advertises this URL in the 401 `WWW-Authenticate: resource_metadata` challenge and stops generating its own metadata — the `/.well-known/oauth-protected-resource` handler returns 404. Use it when the resource server already publishes its own PRM; you'll typically also pass `protectedResourceMetadataRoute: false` to the Vite plugin so the now-unused route isn't emitted. Mutually exclusive with the plugin's `metadataPath` (which has the SDK serve its own document at a custom path); configuring both throws at handler construction. |
 
 Protected-resource metadata is derived from the same config. When `resource` is omitted, the published resource is the incoming request origin plus the MCP route path the stack adapter supplies as `resourcePath` (for example, `https://my-app.lovable.app/mcp`); `authorization_servers` is the configured issuer, and `resource_name` is `defineMcp({ title })` unless `resourceName` overrides it. Because the metadata endpoint is served from `/.well-known/...`, it can't infer the resource from its own path — the handler throws at construction when neither `resource` nor `resourcePath` is set (the generated TanStack routes always pass `resourcePath`). For Supabase auth, this metadata still names the MCP resource even though Supabase JWTs use the project audience `"authenticated"`.
 

package/dist/authorize-HTd0GKmB.d.ts

@@ -0,0 +1,18 @@
+interface McpRuntimeOptions {
+    /**
+     * Public MCP protocol path. REST companion handlers pass this so OAuth
+     * resource/audience checks bind to `/mcp`, not internal `/.mcp/*` RPC URLs.
+     */
+    resourcePath?: string;
+    /**
+     * Host-relative path of the SDK-served protected-resource metadata document.
+     * The Vite plugin injects it into every emitted handler when it generates the
+     * PRM route, so the 401 challenge advertises the same path the route serves.
+     * Its presence is the signal that the SDK owns the PRM document, so it is
+     * mutually exclusive with `auth.protectedResourceMetadataUrl` (which points at
+     * an externally hosted document). Defaults to the well-known path when absent.
+     */
+    metadataPath?: string;
+}
+
+export type { McpRuntimeOptions as M };

package/dist/{chunk-E335BBVM.js → chunk-2RGXCDBU.js}

@@ -5,7 +5,7 @@ import {
   headResponse,
   methodNotAllowed,
   withCors
-} from "./chunk-HRMLGCXV.js";
+} from "./chunk-YQBOGY7D.js";
 
 // src/protocols/rest/list-tools.ts
 import { objectFromShape } from "@modelcontextprotocol/sdk/server/zod-compat.js";

package/dist/{chunk-W7F6JRDB.js → chunk-4JO3BZQG.js}

@@ -7,7 +7,7 @@ import {
   oauthConfigurationErrorResponse,
   resolveProtectedResource,
   withCors
-} from "./chunk-HRMLGCXV.js";
+} from "./chunk-YQBOGY7D.js";
 import {
   describeError,
   log

package/dist/{chunk-4Y72OCPS.js → chunk-6N7B7NZY.js}

@@ -8,7 +8,7 @@ import {
   createRequestAuthorizer,
   methodNotAllowed,
   withCors
-} from "./chunk-HRMLGCXV.js";
+} from "./chunk-YQBOGY7D.js";
 
 // src/protocols/rest/invoke-tool.ts
 import { getParseErrorMessage, objectFromShape, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";

package/dist/{chunk-3XPKR4G6.js → chunk-OXSSMKQE.js}

@@ -5,7 +5,7 @@ import {
   corsPreflightResponse,
   createRequestAuthorizer,
   withCors
-} from "./chunk-HRMLGCXV.js";
+} from "./chunk-YQBOGY7D.js";
 import {
   describeError,
   log

package/dist/{chunk-HRMLGCXV.js → chunk-YQBOGY7D.js}

@@ -30,10 +30,10 @@ function resolveProtectedResource(auth, request, options) {
   resourceURL.hash = "";
   return trimTrailingSlash(resourceURL.toString());
 }
-function assertResourcePathShape(resourcePath) {
+function assertResourcePathShape(resourcePath, label = "resourcePath") {
   if (!resourcePath.startsWith("/") || resourcePath.startsWith("//") || resourcePath.includes("\\") || /(^|\/)\.\.(\/|$)/.test(resourcePath)) {
     throw new Error(
-      `@lovable.dev/mcp-js: resourcePath must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
+      `@lovable.dev/mcp-js: ${label} must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
     );
   }
 }
@@ -225,6 +225,7 @@ async function fetchVerificationKeySet(jwksUri) {
 async function verifyJwtClaims(token, keySet, issuer, audience, auth) {
   try {
     const { payload } = await jwtVerify(token, keySet, {
+      typ: "at+jwt",
       // `issuer` is trimmed of any trailing slash; accept both forms so a token whose
       // `iss` carries the slash the AS publishes still verifies.
       issuer: [issuer, `${issuer}/`],
@@ -299,16 +300,16 @@ function quoteAuthenticateParam(value) {
   const sanitized = value.replace(/[\u0000-\u001F\u007F]/g, "");
   return `"${sanitized.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
-function resolveProtectedResourceMetadataUrl(auth, request) {
+function resolveProtectedResourceMetadataUrl(auth, request, options) {
   if (auth.protectedResourceMetadataUrl !== void 0)
     return auth.protectedResourceMetadataUrl;
   const base = auth.resource ?? request.url;
-  return new URL(OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
+  return new URL(options.metadataPath ?? OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
 }
-function wwwAuthenticateHeader(auth, request, params = {}) {
+function wwwAuthenticateHeader(auth, request, options, params = {}) {
   const values = [
     `realm=${quoteAuthenticateParam("mcp")}`,
-    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request))}`
+    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request, options))}`
   ];
   if (auth.requiredScopes && auth.requiredScopes.length > 0) {
     values.push(`scope=${quoteAuthenticateParam(auth.requiredScopes.join(" "))}`);
@@ -319,9 +320,12 @@ function wwwAuthenticateHeader(auth, request, params = {}) {
     values.push(`error_description=${quoteAuthenticateParam(params.errorDescription)}`);
   return `Bearer ${values.join(", ")}`;
 }
-function challengeResponse(auth, request, status, oauthError, errorDescription) {
+function challengeResponse(auth, request, options, status, oauthError, errorDescription) {
   const headers = new Headers(JSON_HEADERS);
-  headers.set("WWW-Authenticate", wwwAuthenticateHeader(auth, request, { error: oauthError, errorDescription }));
+  headers.set(
+    "WWW-Authenticate",
+    wwwAuthenticateHeader(auth, request, options, { error: oauthError, errorDescription })
+  );
   headers.set("Cache-Control", "no-store");
   return new Response(JSON.stringify({ error: status === 403 ? "forbidden" : "unauthorized" }), {
     status,
@@ -349,10 +353,17 @@ function parseBearerToken(request) {
 function getOAuthRuntime(mcp, options = {}) {
   if (options.resourcePath !== void 0)
     assertResourcePathShape(options.resourcePath);
-  const stableOptions = { resourcePath: options.resourcePath };
+  if (options.metadataPath !== void 0)
+    assertResourcePathShape(options.metadataPath, "metadataPath");
+  const stableOptions = { resourcePath: options.resourcePath, metadataPath: options.metadataPath };
   const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
   if (!auth)
     return { kind: "unconfigured", options: stableOptions };
+  if (options.metadataPath !== void 0 && auth.protectedResourceMetadataUrl !== void 0) {
+    throw new Error(
+      `@lovable.dev/mcp-js: the Vite plugin generates protected-resource metadata (metadataPath set), so auth.protectedResourceMetadataUrl must not also be set. Drop protectedResourceMetadataUrl, or set protectedResourceMetadataRoute: false in mcpPlugin(...) to host the document yourself.`
+    );
+  }
   const discovery = createOAuthDiscoveryResolver(auth);
   return {
     kind: "configured",
@@ -391,7 +402,7 @@ function createRequestAuthorizer(mcp, options = {}) {
       const token = parseBearerToken(request);
       if (!token) {
         log.info("auth.no_bearer_token", { outcome: "401" });
-        return { ok: false, response: challengeResponse(runtime.auth, request, 401) };
+        return { ok: false, response: challengeResponse(runtime.auth, request, runtime.options, 401) };
       }
       try {
         const auth = await runtime.verify(token, request, runtime.options);
@@ -406,13 +417,27 @@ function createRequestAuthorizer(mcp, options = {}) {
           log.info("auth.token_rejected", { status: err.status, oauthError: err.oauthError });
           return {
             ok: false,
-            response: challengeResponse(runtime.auth, request, err.status, err.oauthError, err.message)
+            response: challengeResponse(
+              runtime.auth,
+              request,
+              runtime.options,
+              err.status,
+              err.oauthError,
+              err.message
+            )
           };
         }
         log.error("auth.unexpected_error", { ...describeError(err), outcome: "401" });
         return {
           ok: false,
-          response: challengeResponse(runtime.auth, request, 401, "invalid_token", "Invalid access token")
+          response: challengeResponse(
+            runtime.auth,
+            request,
+            runtime.options,
+            401,
+            "invalid_token",
+            "Invalid access token"
+          )
         };
       }
     }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-zMlr1mOK.js';
-export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, R as ResourceLink, f as ResourceLinkIcon, T as TextContent, g as ToolAnnotations, h as ToolContent, i as ToolContext, k as ToolHandlerResult, l as ZodSchema } from './types-zMlr1mOK.js';
+import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-C5SSORxe.js';
+export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, R as ResourceLink, f as ResourceLinkIcon, T as TextContent, g as ToolAnnotations, h as ToolContent, i as ToolContext, k as ToolHandlerResult, l as ZodSchema } from './types-C5SSORxe.js';
 import 'zod';
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-zMlr1mOK.js';
-export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, R as ResourceLink, f as ResourceLinkIcon, T as TextContent, g as ToolAnnotations, h as ToolContent, i as ToolContext, k as ToolHandlerResult, l as ZodSchema } from './types-zMlr1mOK.js';
+import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-C5SSORxe.js';
+export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, R as ResourceLink, f as ResourceLinkIcon, T as TextContent, g as ToolAnnotations, h as ToolContent, i as ToolContext, k as ToolHandlerResult, l as ZodSchema } from './types-C5SSORxe.js';
 import 'zod';
 
 /**

package/dist/protocols/mcp/index.cjs

@@ -246,10 +246,10 @@ function resolveProtectedResource(auth, request, options) {
   resourceURL.hash = "";
   return trimTrailingSlash(resourceURL.toString());
 }
-function assertResourcePathShape(resourcePath) {
+function assertResourcePathShape(resourcePath, label = "resourcePath") {
   if (!resourcePath.startsWith("/") || resourcePath.startsWith("//") || resourcePath.includes("\\") || /(^|\/)\.\.(\/|$)/.test(resourcePath)) {
     throw new Error(
-      `@lovable.dev/mcp-js: resourcePath must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
+      `@lovable.dev/mcp-js: ${label} must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
     );
   }
 }
@@ -316,6 +316,7 @@ async function fetchVerificationKeySet(jwksUri) {
 async function verifyJwtClaims(token, keySet, issuer, audience, auth) {
   try {
     const { payload } = await (0, import_jose.jwtVerify)(token, keySet, {
+      typ: "at+jwt",
       // `issuer` is trimmed of any trailing slash; accept both forms so a token whose
       // `iss` carries the slash the AS publishes still verifies.
       issuer: [issuer, `${issuer}/`],
@@ -390,16 +391,16 @@ function quoteAuthenticateParam(value) {
   const sanitized = value.replace(/[\u0000-\u001F\u007F]/g, "");
   return `"${sanitized.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
-function resolveProtectedResourceMetadataUrl(auth, request) {
+function resolveProtectedResourceMetadataUrl(auth, request, options) {
   if (auth.protectedResourceMetadataUrl !== void 0)
     return auth.protectedResourceMetadataUrl;
   const base = auth.resource ?? request.url;
-  return new URL(OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
+  return new URL(options.metadataPath ?? OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
 }
-function wwwAuthenticateHeader(auth, request, params = {}) {
+function wwwAuthenticateHeader(auth, request, options, params = {}) {
   const values = [
     `realm=${quoteAuthenticateParam("mcp")}`,
-    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request))}`
+    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request, options))}`
   ];
   if (auth.requiredScopes && auth.requiredScopes.length > 0) {
     values.push(`scope=${quoteAuthenticateParam(auth.requiredScopes.join(" "))}`);
@@ -410,9 +411,12 @@ function wwwAuthenticateHeader(auth, request, params = {}) {
     values.push(`error_description=${quoteAuthenticateParam(params.errorDescription)}`);
   return `Bearer ${values.join(", ")}`;
 }
-function challengeResponse(auth, request, status, oauthError, errorDescription) {
+function challengeResponse(auth, request, options, status, oauthError, errorDescription) {
   const headers = new Headers(JSON_HEADERS);
-  headers.set("WWW-Authenticate", wwwAuthenticateHeader(auth, request, { error: oauthError, errorDescription }));
+  headers.set(
+    "WWW-Authenticate",
+    wwwAuthenticateHeader(auth, request, options, { error: oauthError, errorDescription })
+  );
   headers.set("Cache-Control", "no-store");
   return new Response(JSON.stringify({ error: status === 403 ? "forbidden" : "unauthorized" }), {
     status,
@@ -440,10 +444,17 @@ function parseBearerToken(request) {
 function getOAuthRuntime(mcp, options = {}) {
   if (options.resourcePath !== void 0)
     assertResourcePathShape(options.resourcePath);
-  const stableOptions = { resourcePath: options.resourcePath };
+  if (options.metadataPath !== void 0)
+    assertResourcePathShape(options.metadataPath, "metadataPath");
+  const stableOptions = { resourcePath: options.resourcePath, metadataPath: options.metadataPath };
   const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
   if (!auth)
     return { kind: "unconfigured", options: stableOptions };
+  if (options.metadataPath !== void 0 && auth.protectedResourceMetadataUrl !== void 0) {
+    throw new Error(
+      `@lovable.dev/mcp-js: the Vite plugin generates protected-resource metadata (metadataPath set), so auth.protectedResourceMetadataUrl must not also be set. Drop protectedResourceMetadataUrl, or set protectedResourceMetadataRoute: false in mcpPlugin(...) to host the document yourself.`
+    );
+  }
   const discovery = createOAuthDiscoveryResolver(auth);
   return {
     kind: "configured",
@@ -474,7 +485,7 @@ function createRequestAuthorizer(mcp, options = {}) {
       const token = parseBearerToken(request);
       if (!token) {
         log.info("auth.no_bearer_token", { outcome: "401" });
-        return { ok: false, response: challengeResponse(runtime.auth, request, 401) };
+        return { ok: false, response: challengeResponse(runtime.auth, request, runtime.options, 401) };
       }
       try {
         const auth = await runtime.verify(token, request, runtime.options);
@@ -489,13 +500,27 @@ function createRequestAuthorizer(mcp, options = {}) {
           log.info("auth.token_rejected", { status: err.status, oauthError: err.oauthError });
           return {
             ok: false,
-            response: challengeResponse(runtime.auth, request, err.status, err.oauthError, err.message)
+            response: challengeResponse(
+              runtime.auth,
+              request,
+              runtime.options,
+              err.status,
+              err.oauthError,
+              err.message
+            )
           };
         }
         log.error("auth.unexpected_error", { ...describeError(err), outcome: "401" });
         return {
           ok: false,
-          response: challengeResponse(runtime.auth, request, 401, "invalid_token", "Invalid access token")
+          response: challengeResponse(
+            runtime.auth,
+            request,
+            runtime.options,
+            401,
+            "invalid_token",
+            "Invalid access token"
+          )
         };
       }
     }

package/dist/protocols/mcp/index.d.cts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../../types-C5SSORxe.js';
 import 'zod';
 
 type McpProtocolHandler = (request: Request) => Promise<Response>;

package/dist/protocols/mcp/index.d.ts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../../types-C5SSORxe.js';
 import 'zod';
 
 type McpProtocolHandler = (request: Request) => Promise<Response>;

package/dist/protocols/mcp/index.js

@@ -1,8 +1,8 @@
 import {
   createMcpProtocolHandler
-} from "../../chunk-3XPKR4G6.js";
+} from "../../chunk-OXSSMKQE.js";
 import "../../chunk-MA5H6PSF.js";
-import "../../chunk-HRMLGCXV.js";
+import "../../chunk-YQBOGY7D.js";
 import "../../chunk-QC3DXQTH.js";
 import "../../chunk-6DXGZZA4.js";
 export {

package/dist/protocols/oauth-metadata.cjs

@@ -248,10 +248,10 @@ function resolveProtectedResource(auth, request, options) {
   resourceURL.hash = "";
   return trimTrailingSlash(resourceURL.toString());
 }
-function assertResourcePathShape(resourcePath) {
+function assertResourcePathShape(resourcePath, label = "resourcePath") {
   if (!resourcePath.startsWith("/") || resourcePath.startsWith("//") || resourcePath.includes("\\") || /(^|\/)\.\.(\/|$)/.test(resourcePath)) {
     throw new Error(
-      `@lovable.dev/mcp-js: resourcePath must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
+      `@lovable.dev/mcp-js: ${label} must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
     );
   }
 }
@@ -318,6 +318,7 @@ async function fetchVerificationKeySet(jwksUri) {
 async function verifyJwtClaims(token, keySet, issuer, audience, auth) {
   try {
     const { payload } = await (0, import_jose.jwtVerify)(token, keySet, {
+      typ: "at+jwt",
       // `issuer` is trimmed of any trailing slash; accept both forms so a token whose
       // `iss` carries the slash the AS publishes still verifies.
       issuer: [issuer, `${issuer}/`],
@@ -397,10 +398,17 @@ function oauthConfigurationErrorResponse() {
 function getOAuthRuntime(mcp, options = {}) {
   if (options.resourcePath !== void 0)
     assertResourcePathShape(options.resourcePath);
-  const stableOptions = { resourcePath: options.resourcePath };
+  if (options.metadataPath !== void 0)
+    assertResourcePathShape(options.metadataPath, "metadataPath");
+  const stableOptions = { resourcePath: options.resourcePath, metadataPath: options.metadataPath };
   const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
   if (!auth)
     return { kind: "unconfigured", options: stableOptions };
+  if (options.metadataPath !== void 0 && auth.protectedResourceMetadataUrl !== void 0) {
+    throw new Error(
+      `@lovable.dev/mcp-js: the Vite plugin generates protected-resource metadata (metadataPath set), so auth.protectedResourceMetadataUrl must not also be set. Drop protectedResourceMetadataUrl, or set protectedResourceMetadataRoute: false in mcpPlugin(...) to host the document yourself.`
+    );
+  }
   const discovery = createOAuthDiscoveryResolver(auth);
   return {
     kind: "configured",

package/dist/protocols/oauth-metadata.d.cts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../types-C5SSORxe.js';
 import 'zod';
 
 type OAuthProtectedResourceMetadataHandler = (request: Request) => Promise<Response>;

package/dist/protocols/oauth-metadata.d.ts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../types-C5SSORxe.js';
 import 'zod';
 
 type OAuthProtectedResourceMetadataHandler = (request: Request) => Promise<Response>;

package/dist/protocols/oauth-metadata.js

@@ -1,7 +1,7 @@
 import {
   createOAuthProtectedResourceMetadataHandler
-} from "../chunk-W7F6JRDB.js";
-import "../chunk-HRMLGCXV.js";
+} from "../chunk-4JO3BZQG.js";
+import "../chunk-YQBOGY7D.js";
 import "../chunk-QC3DXQTH.js";
 import "../chunk-6DXGZZA4.js";
 export {

package/dist/protocols/rest/index.cjs

@@ -256,10 +256,10 @@ function resolveProtectedResource(auth, request, options) {
   resourceURL.hash = "";
   return trimTrailingSlash(resourceURL.toString());
 }
-function assertResourcePathShape(resourcePath) {
+function assertResourcePathShape(resourcePath, label = "resourcePath") {
   if (!resourcePath.startsWith("/") || resourcePath.startsWith("//") || resourcePath.includes("\\") || /(^|\/)\.\.(\/|$)/.test(resourcePath)) {
     throw new Error(
-      `@lovable.dev/mcp-js: resourcePath must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
+      `@lovable.dev/mcp-js: ${label} must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
     );
   }
 }
@@ -326,6 +326,7 @@ async function fetchVerificationKeySet(jwksUri) {
 async function verifyJwtClaims(token, keySet, issuer, audience, auth) {
   try {
     const { payload } = await (0, import_jose.jwtVerify)(token, keySet, {
+      typ: "at+jwt",
       // `issuer` is trimmed of any trailing slash; accept both forms so a token whose
       // `iss` carries the slash the AS publishes still verifies.
       issuer: [issuer, `${issuer}/`],
@@ -400,16 +401,16 @@ function quoteAuthenticateParam(value) {
   const sanitized = value.replace(/[\u0000-\u001F\u007F]/g, "");
   return `"${sanitized.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
-function resolveProtectedResourceMetadataUrl(auth, request) {
+function resolveProtectedResourceMetadataUrl(auth, request, options) {
   if (auth.protectedResourceMetadataUrl !== void 0)
     return auth.protectedResourceMetadataUrl;
   const base = auth.resource ?? request.url;
-  return new URL(OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
+  return new URL(options.metadataPath ?? OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
 }
-function wwwAuthenticateHeader(auth, request, params = {}) {
+function wwwAuthenticateHeader(auth, request, options, params = {}) {
   const values = [
     `realm=${quoteAuthenticateParam("mcp")}`,
-    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request))}`
+    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request, options))}`
   ];
   if (auth.requiredScopes && auth.requiredScopes.length > 0) {
     values.push(`scope=${quoteAuthenticateParam(auth.requiredScopes.join(" "))}`);
@@ -420,9 +421,12 @@ function wwwAuthenticateHeader(auth, request, params = {}) {
     values.push(`error_description=${quoteAuthenticateParam(params.errorDescription)}`);
   return `Bearer ${values.join(", ")}`;
 }
-function challengeResponse(auth, request, status, oauthError, errorDescription) {
+function challengeResponse(auth, request, options, status, oauthError, errorDescription) {
   const headers = new Headers(JSON_HEADERS);
-  headers.set("WWW-Authenticate", wwwAuthenticateHeader(auth, request, { error: oauthError, errorDescription }));
+  headers.set(
+    "WWW-Authenticate",
+    wwwAuthenticateHeader(auth, request, options, { error: oauthError, errorDescription })
+  );
   headers.set("Cache-Control", "no-store");
   return new Response(JSON.stringify({ error: status === 403 ? "forbidden" : "unauthorized" }), {
     status,
@@ -450,10 +454,17 @@ function parseBearerToken(request) {
 function getOAuthRuntime(mcp, options = {}) {
   if (options.resourcePath !== void 0)
     assertResourcePathShape(options.resourcePath);
-  const stableOptions = { resourcePath: options.resourcePath };
+  if (options.metadataPath !== void 0)
+    assertResourcePathShape(options.metadataPath, "metadataPath");
+  const stableOptions = { resourcePath: options.resourcePath, metadataPath: options.metadataPath };
   const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
   if (!auth)
     return { kind: "unconfigured", options: stableOptions };
+  if (options.metadataPath !== void 0 && auth.protectedResourceMetadataUrl !== void 0) {
+    throw new Error(
+      `@lovable.dev/mcp-js: the Vite plugin generates protected-resource metadata (metadataPath set), so auth.protectedResourceMetadataUrl must not also be set. Drop protectedResourceMetadataUrl, or set protectedResourceMetadataRoute: false in mcpPlugin(...) to host the document yourself.`
+    );
+  }
   const discovery = createOAuthDiscoveryResolver(auth);
   return {
     kind: "configured",
@@ -492,7 +503,7 @@ function createRequestAuthorizer(mcp, options = {}) {
       const token = parseBearerToken(request);
       if (!token) {
         log.info("auth.no_bearer_token", { outcome: "401" });
-        return { ok: false, response: challengeResponse(runtime.auth, request, 401) };
+        return { ok: false, response: challengeResponse(runtime.auth, request, runtime.options, 401) };
       }
       try {
         const auth = await runtime.verify(token, request, runtime.options);
@@ -507,13 +518,27 @@ function createRequestAuthorizer(mcp, options = {}) {
           log.info("auth.token_rejected", { status: err.status, oauthError: err.oauthError });
           return {
             ok: false,
-            response: challengeResponse(runtime.auth, request, err.status, err.oauthError, err.message)
+            response: challengeResponse(
+              runtime.auth,
+              request,
+              runtime.options,
+              err.status,
+              err.oauthError,
+              err.message
+            )
           };
         }
         log.error("auth.unexpected_error", { ...describeError(err), outcome: "401" });
         return {
           ok: false,
-          response: challengeResponse(runtime.auth, request, 401, "invalid_token", "Invalid access token")
+          response: challengeResponse(
+            runtime.auth,
+            request,
+            runtime.options,
+            401,
+            "invalid_token",
+            "Invalid access token"
+          )
         };
       }
     }

package/dist/protocols/rest/index.d.cts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../../types-C5SSORxe.js';
 import 'zod';
 
 type RestListToolsHandler = (request: Request) => Promise<Response>;

package/dist/protocols/rest/index.d.ts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../../types-C5SSORxe.js';
 import 'zod';
 
 type RestListToolsHandler = (request: Request) => Promise<Response>;

package/dist/protocols/rest/index.js

@@ -1,11 +1,11 @@
 import {
   createInvokeToolHandler
-} from "../../chunk-4Y72OCPS.js";
+} from "../../chunk-6N7B7NZY.js";
 import "../../chunk-MA5H6PSF.js";
 import {
   createListToolsHandler
-} from "../../chunk-E335BBVM.js";
-import "../../chunk-HRMLGCXV.js";
+} from "../../chunk-2RGXCDBU.js";
+import "../../chunk-YQBOGY7D.js";
 import "../../chunk-QC3DXQTH.js";
 import "../../chunk-6DXGZZA4.js";
 export {

package/dist/stacks/tanstack/cli/extract-manifest.cjs

@@ -8,7 +8,7 @@ var import_node_path = require("path");
 var import_vite2 = require("vite");
 
 // package.json
-var version = "0.8.0";
+var version = "0.9.1";
 
 // src/protocols/rest/list-tools.ts
 var import_zod_compat = require("@modelcontextprotocol/sdk/server/zod-compat.js");

package/dist/stacks/tanstack/cli/extract-manifest.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   buildMcpListing
-} from "../../../chunk-E335BBVM.js";
-import "../../../chunk-HRMLGCXV.js";
+} from "../../../chunk-2RGXCDBU.js";
+import "../../../chunk-YQBOGY7D.js";
 import "../../../chunk-QC3DXQTH.js";
 import {
   isFileMissing
@@ -16,7 +16,7 @@ import { dirname, resolve } from "path";
 import { resolveConfig } from "vite";
 
 // package.json
-var version = "0.8.0";
+var version = "0.9.1";
 
 // src/stacks/tanstack/extract-manifest.ts
 var MANIFEST_VERSION = 1;

package/dist/stacks/tanstack/index.cjs

@@ -258,10 +258,10 @@ function resolveProtectedResource(auth, request, options) {
   resourceURL.hash = "";
   return trimTrailingSlash(resourceURL.toString());
 }
-function assertResourcePathShape(resourcePath) {
+function assertResourcePathShape(resourcePath, label = "resourcePath") {
   if (!resourcePath.startsWith("/") || resourcePath.startsWith("//") || resourcePath.includes("\\") || /(^|\/)\.\.(\/|$)/.test(resourcePath)) {
     throw new Error(
-      `@lovable.dev/mcp-js: resourcePath must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
+      `@lovable.dev/mcp-js: ${label} must be an absolute path beginning with "/" without ".." segments or backslashes (got ${JSON.stringify(resourcePath)})`
     );
   }
 }
@@ -328,6 +328,7 @@ async function fetchVerificationKeySet(jwksUri) {
 async function verifyJwtClaims(token, keySet, issuer, audience, auth) {
   try {
     const { payload } = await (0, import_jose.jwtVerify)(token, keySet, {
+      typ: "at+jwt",
       // `issuer` is trimmed of any trailing slash; accept both forms so a token whose
       // `iss` carries the slash the AS publishes still verifies.
       issuer: [issuer, `${issuer}/`],
@@ -402,16 +403,16 @@ function quoteAuthenticateParam(value) {
   const sanitized = value.replace(/[\u0000-\u001F\u007F]/g, "");
   return `"${sanitized.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
-function resolveProtectedResourceMetadataUrl(auth, request) {
+function resolveProtectedResourceMetadataUrl(auth, request, options) {
   if (auth.protectedResourceMetadataUrl !== void 0)
     return auth.protectedResourceMetadataUrl;
   const base = auth.resource ?? request.url;
-  return new URL(OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
+  return new URL(options.metadataPath ?? OAUTH_PROTECTED_RESOURCE_METADATA_PATH, base).toString();
 }
-function wwwAuthenticateHeader(auth, request, params = {}) {
+function wwwAuthenticateHeader(auth, request, options, params = {}) {
   const values = [
     `realm=${quoteAuthenticateParam("mcp")}`,
-    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request))}`
+    `resource_metadata=${quoteAuthenticateParam(resolveProtectedResourceMetadataUrl(auth, request, options))}`
   ];
   if (auth.requiredScopes && auth.requiredScopes.length > 0) {
     values.push(`scope=${quoteAuthenticateParam(auth.requiredScopes.join(" "))}`);
@@ -422,9 +423,12 @@ function wwwAuthenticateHeader(auth, request, params = {}) {
     values.push(`error_description=${quoteAuthenticateParam(params.errorDescription)}`);
   return `Bearer ${values.join(", ")}`;
 }
-function challengeResponse(auth, request, status, oauthError, errorDescription) {
+function challengeResponse(auth, request, options, status, oauthError, errorDescription) {
   const headers = new Headers(JSON_HEADERS);
-  headers.set("WWW-Authenticate", wwwAuthenticateHeader(auth, request, { error: oauthError, errorDescription }));
+  headers.set(
+    "WWW-Authenticate",
+    wwwAuthenticateHeader(auth, request, options, { error: oauthError, errorDescription })
+  );
   headers.set("Cache-Control", "no-store");
   return new Response(JSON.stringify({ error: status === 403 ? "forbidden" : "unauthorized" }), {
     status,
@@ -452,10 +456,17 @@ function parseBearerToken(request) {
 function getOAuthRuntime(mcp, options = {}) {
   if (options.resourcePath !== void 0)
     assertResourcePathShape(options.resourcePath);
-  const stableOptions = { resourcePath: options.resourcePath };
+  if (options.metadataPath !== void 0)
+    assertResourcePathShape(options.metadataPath, "metadataPath");
+  const stableOptions = { resourcePath: options.resourcePath, metadataPath: options.metadataPath };
   const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
   if (!auth)
     return { kind: "unconfigured", options: stableOptions };
+  if (options.metadataPath !== void 0 && auth.protectedResourceMetadataUrl !== void 0) {
+    throw new Error(
+      `@lovable.dev/mcp-js: the Vite plugin generates protected-resource metadata (metadataPath set), so auth.protectedResourceMetadataUrl must not also be set. Drop protectedResourceMetadataUrl, or set protectedResourceMetadataRoute: false in mcpPlugin(...) to host the document yourself.`
+    );
+  }
   const discovery = createOAuthDiscoveryResolver(auth);
   return {
     kind: "configured",
@@ -494,7 +505,7 @@ function createRequestAuthorizer(mcp, options = {}) {
       const token = parseBearerToken(request);
       if (!token) {
         log.info("auth.no_bearer_token", { outcome: "401" });
-        return { ok: false, response: challengeResponse(runtime.auth, request, 401) };
+        return { ok: false, response: challengeResponse(runtime.auth, request, runtime.options, 401) };
       }
       try {
         const auth = await runtime.verify(token, request, runtime.options);
@@ -509,13 +520,27 @@ function createRequestAuthorizer(mcp, options = {}) {
           log.info("auth.token_rejected", { status: err.status, oauthError: err.oauthError });
           return {
             ok: false,
-            response: challengeResponse(runtime.auth, request, err.status, err.oauthError, err.message)
+            response: challengeResponse(
+              runtime.auth,
+              request,
+              runtime.options,
+              err.status,
+              err.oauthError,
+              err.message
+            )
           };
         }
         log.error("auth.unexpected_error", { ...describeError(err), outcome: "401" });
         return {
           ok: false,
-          response: challengeResponse(runtime.auth, request, 401, "invalid_token", "Invalid access token")
+          response: challengeResponse(
+            runtime.auth,
+            request,
+            runtime.options,
+            401,
+            "invalid_token",
+            "Invalid access token"
+          )
         };
       }
     }

package/dist/stacks/tanstack/index.d.cts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../../types-C5SSORxe.js';
 import 'zod';
 
 interface TanStackRouteCtx {

package/dist/stacks/tanstack/index.d.ts

@@ -1,5 +1,5 @@
-import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
-import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import { M as McpRuntimeOptions } from '../../authorize-HTd0GKmB.js';
+import { d as McpDefinition } from '../../types-C5SSORxe.js';
 import 'zod';
 
 interface TanStackRouteCtx {

package/dist/stacks/tanstack/index.js

@@ -1,17 +1,17 @@
 import {
   createMcpProtocolHandler
-} from "../../chunk-3XPKR4G6.js";
+} from "../../chunk-OXSSMKQE.js";
 import {
   createOAuthProtectedResourceMetadataHandler
-} from "../../chunk-W7F6JRDB.js";
+} from "../../chunk-4JO3BZQG.js";
 import {
   createInvokeToolHandler
-} from "../../chunk-4Y72OCPS.js";
+} from "../../chunk-6N7B7NZY.js";
 import "../../chunk-MA5H6PSF.js";
 import {
   createListToolsHandler
-} from "../../chunk-E335BBVM.js";
-import "../../chunk-HRMLGCXV.js";
+} from "../../chunk-2RGXCDBU.js";
+import "../../chunk-YQBOGY7D.js";
 import "../../chunk-QC3DXQTH.js";
 import "../../chunk-6DXGZZA4.js";
 

package/dist/stacks/tanstack/vite.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/stacks/tanstack/vite.ts
 var vite_exports = {};
 __export(vite_exports, {
+  assertMetadataPathShape: () => assertMetadataPathShape,
   assertUrlPathShape: () => assertUrlPathShape,
   default: () => vite_default,
   deriveRouteFileName: () => deriveRouteFileName,
@@ -55,15 +56,17 @@ function wellKnownRouteFile(routesDir, urlPath) {
   });
   return (0, import_node_path.resolve)(routesDir, ...fileSegments);
 }
-function resolveAllRoutes(projectRoot, routesDirOption, routeFileName) {
+function resolveAllRoutes(projectRoot, routesDirOption, routeFileName, metadataUrlPath) {
   const routesDir = (0, import_node_path.resolve)(projectRoot, routesDirOption);
   assertContains(projectRoot, routesDir, `routesDir "${routesDirOption}"`);
   const mcpRouteFile = (0, import_node_path.resolve)(routesDir, routeFileName);
   assertContains(routesDir, mcpRouteFile, `routeFileName "${routeFileName}"`);
+  const metadataRouteFile = wellKnownRouteFile(routesDir, metadataUrlPath);
+  assertContains(routesDir, metadataRouteFile, `metadataPath "${metadataUrlPath}"`);
   return {
     routesDir,
     mcpRouteFile,
-    metadataRouteFile: wellKnownRouteFile(routesDir, OAUTH_PROTECTED_RESOURCE_METADATA_PATH),
+    metadataRouteFile,
     listToolsRouteFile: (0, import_node_path.resolve)(routesDir, "[.mcp]", "list-tools.ts"),
     invokeToolRouteFile: (0, import_node_path.resolve)(routesDir, "[.mcp]", "invoke-tool", "$tool.ts")
   };
@@ -87,6 +90,24 @@ function assertUrlPathShape(urlPath) {
 function deriveRouteFileName(urlPath) {
   return `${assertUrlPathShape(urlPath)}.ts`;
 }
+function assertMetadataPathShape(metadataPath) {
+  if (!metadataPath.startsWith("/")) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath must start with "/", got "${metadataPath}"`);
+  }
+  if (/\/{2,}/.test(metadataPath)) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" contains empty segments ("//")`);
+  }
+  if (/(^|\/)\.\.(\/|$)/.test(metadataPath)) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" must not contain ".." segments`);
+  }
+  const trimmed = metadataPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!trimmed) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" has no route segment`);
+  }
+  if (!/^[a-zA-Z0-9_\-./]+$/.test(trimmed)) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" contains unsupported characters`);
+  }
+}
 function canonicalUrlPath(urlPath) {
   return `/${urlPath.replace(/^\/+/, "").replace(/\/+$/, "")}`;
 }
@@ -95,10 +116,11 @@ function relativeImportSpecifier(routeFile, target) {
   const withoutExt = rel.replace(/\.ts$/, "");
   return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
 }
-function buildRouteSource(route, resourcePath, mcpEntry, projectRoot) {
+function buildRouteSource(route, resourcePath, metadataPath, mcpEntry, projectRoot) {
   const mcpImport = relativeImportSpecifier(route.file, mcpEntry);
   const routeRel = normalizePath((0, import_node_path.relative)(projectRoot, route.file));
   const note = route.spaFallbackNote ? "      // ANY: TanStack returns SPA HTML for methods not in `handlers`; the SDK 405s instead.\n" : "";
+  const runtimeOptions = metadataPath === void 0 ? `{ resourcePath: "${resourcePath}" }` : `{ resourcePath: "${resourcePath}", metadataPath: "${metadataPath}" }`;
   return `${GENERATED_BANNER}
 // route: ${route.routeLiteral}
 // emitted to: ${routeRel}
@@ -112,7 +134,7 @@ import mcp from "${mcpImport}";
 export const Route = createFileRoute("${route.routeLiteral}")({
   server: {
     handlers: {
-${note}      ANY: ${route.handlerFactory}(mcp, { resourcePath: "${resourcePath}" }),
+${note}      ANY: ${route.handlerFactory}(mcp, ${runtimeOptions}),
     },
   },
 });
@@ -191,12 +213,23 @@ function mcpPlugin(options = {}) {
   const urlPath = canonicalUrlPath(rawUrlPath);
   const emitRestRoutes = options.restRoutes !== false;
   const emitProtectedResourceMetadataRoute = options.protectedResourceMetadataRoute !== false;
+  if (options.metadataPath !== void 0) {
+    if (!emitProtectedResourceMetadataRoute) {
+      throw new Error(
+        `@lovable.dev/mcp-js: metadataPath sets where the protected-resource metadata route is served, so it can't be combined with protectedResourceMetadataRoute: false.`
+      );
+    }
+    assertMetadataPathShape(options.metadataPath);
+  }
+  const metadataUrlPath = canonicalUrlPath(options.metadataPath ?? OAUTH_PROTECTED_RESOURCE_METADATA_PATH);
+  const injectedMetadataPath = emitProtectedResourceMetadataRoute ? metadataUrlPath : void 0;
   let projectRoot = process.cwd();
   let mcpEntry = (0, import_node_path.resolve)(projectRoot, mcpEntryOption);
   let { routesDir, mcpRouteFile, metadataRouteFile, listToolsRouteFile, invokeToolRouteFile } = resolveAllRoutes(
     projectRoot,
     routesDirOption,
-    routeFileName
+    routeFileName,
+    metadataUrlPath
   );
   const regenerate = () => {
     let mcpEntryExists = true;
@@ -215,7 +248,7 @@ function mcpPlugin(options = {}) {
       if (emitProtectedResourceMetadataRoute) {
         routes.push({
           file: metadataRouteFile,
-          routeLiteral: OAUTH_PROTECTED_RESOURCE_METADATA_PATH,
+          routeLiteral: metadataUrlPath,
           handlerFactory: "createTanStackOAuthProtectedResourceMetadataHandler"
         });
       }
@@ -237,7 +270,7 @@ function mcpPlugin(options = {}) {
       }
       for (const route of routes) {
         expected.add(route.file);
-        writeIfChanged(route.file, buildRouteSource(route, urlPath, mcpEntry, projectRoot));
+        writeIfChanged(route.file, buildRouteSource(route, urlPath, injectedMetadataPath, mcpEntry, projectRoot));
       }
     }
     for (const file of findAdoptedFiles(routesDir)) {
@@ -271,7 +304,8 @@ function mcpPlugin(options = {}) {
       ({ routesDir, mcpRouteFile, metadataRouteFile, listToolsRouteFile, invokeToolRouteFile } = resolveAllRoutes(
         projectRoot,
         routesDirOption,
-        routeFileName
+        routeFileName,
+        metadataUrlPath
       ));
       regenerate();
     },
@@ -298,6 +332,7 @@ function mcpPlugin(options = {}) {
 var vite_default = mcpPlugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  assertMetadataPathShape,
   assertUrlPathShape,
   deriveRouteFileName,
   mcpPlugin

package/dist/stacks/tanstack/vite.d.cts

@@ -48,6 +48,21 @@ interface McpPluginOptions {
      * @default true
      */
     protectedResourceMetadataRoute?: boolean;
+    /**
+     * Public URL path for the OAuth protected-resource metadata route (RFC 9728).
+     * Both the emitted route file and the runtime `WWW-Authenticate` challenge use
+     * this path, so they can't drift. Use it when a host gate exposes only a
+     * sub-prefix (e.g. workspace-private projects where only `/api/public/*` is
+     * anonymously reachable) and the default well-known path is blocked.
+     *
+     * Leading-dot segments are bracket-escaped for TanStack file routing
+     * (`.well-known` → `[.well-known]`); the final segment becomes the route file.
+     * Mutually exclusive with `auth.protectedResourceMetadataUrl` (that option
+     * advertises an externally hosted document instead of serving one), and
+     * cannot be combined with `protectedResourceMetadataRoute: false`.
+     * @default "/.well-known/oauth-protected-resource"
+     */
+    metadataPath?: string;
 }
 interface McpPluginApi {
     readonly mcpEntry: string;
@@ -55,6 +70,7 @@ interface McpPluginApi {
 }
 declare function assertUrlPathShape(urlPath: string): string;
 declare function deriveRouteFileName(urlPath: string): string;
+declare function assertMetadataPathShape(metadataPath: string): void;
 /**
  * Generate the TanStack route(s) that mount the MCP server.
  *
@@ -69,4 +85,4 @@ declare function deriveRouteFileName(urlPath: string): string;
  */
 declare function mcpPlugin(options?: McpPluginOptions): Plugin;
 
-export { type McpPluginApi, type McpPluginOptions, assertUrlPathShape, mcpPlugin as default, deriveRouteFileName, mcpPlugin };
+export { type McpPluginApi, type McpPluginOptions, assertMetadataPathShape, assertUrlPathShape, mcpPlugin as default, deriveRouteFileName, mcpPlugin };

package/dist/stacks/tanstack/vite.d.ts

@@ -48,6 +48,21 @@ interface McpPluginOptions {
      * @default true
      */
     protectedResourceMetadataRoute?: boolean;
+    /**
+     * Public URL path for the OAuth protected-resource metadata route (RFC 9728).
+     * Both the emitted route file and the runtime `WWW-Authenticate` challenge use
+     * this path, so they can't drift. Use it when a host gate exposes only a
+     * sub-prefix (e.g. workspace-private projects where only `/api/public/*` is
+     * anonymously reachable) and the default well-known path is blocked.
+     *
+     * Leading-dot segments are bracket-escaped for TanStack file routing
+     * (`.well-known` → `[.well-known]`); the final segment becomes the route file.
+     * Mutually exclusive with `auth.protectedResourceMetadataUrl` (that option
+     * advertises an externally hosted document instead of serving one), and
+     * cannot be combined with `protectedResourceMetadataRoute: false`.
+     * @default "/.well-known/oauth-protected-resource"
+     */
+    metadataPath?: string;
 }
 interface McpPluginApi {
     readonly mcpEntry: string;
@@ -55,6 +70,7 @@ interface McpPluginApi {
 }
 declare function assertUrlPathShape(urlPath: string): string;
 declare function deriveRouteFileName(urlPath: string): string;
+declare function assertMetadataPathShape(metadataPath: string): void;
 /**
  * Generate the TanStack route(s) that mount the MCP server.
  *
@@ -69,4 +85,4 @@ declare function deriveRouteFileName(urlPath: string): string;
  */
 declare function mcpPlugin(options?: McpPluginOptions): Plugin;
 
-export { type McpPluginApi, type McpPluginOptions, assertUrlPathShape, mcpPlugin as default, deriveRouteFileName, mcpPlugin };
+export { type McpPluginApi, type McpPluginOptions, assertMetadataPathShape, assertUrlPathShape, mcpPlugin as default, deriveRouteFileName, mcpPlugin };

package/dist/stacks/tanstack/vite.js

@@ -25,15 +25,17 @@ function wellKnownRouteFile(routesDir, urlPath) {
   });
   return resolve(routesDir, ...fileSegments);
 }
-function resolveAllRoutes(projectRoot, routesDirOption, routeFileName) {
+function resolveAllRoutes(projectRoot, routesDirOption, routeFileName, metadataUrlPath) {
   const routesDir = resolve(projectRoot, routesDirOption);
   assertContains(projectRoot, routesDir, `routesDir "${routesDirOption}"`);
   const mcpRouteFile = resolve(routesDir, routeFileName);
   assertContains(routesDir, mcpRouteFile, `routeFileName "${routeFileName}"`);
+  const metadataRouteFile = wellKnownRouteFile(routesDir, metadataUrlPath);
+  assertContains(routesDir, metadataRouteFile, `metadataPath "${metadataUrlPath}"`);
   return {
     routesDir,
     mcpRouteFile,
-    metadataRouteFile: wellKnownRouteFile(routesDir, OAUTH_PROTECTED_RESOURCE_METADATA_PATH),
+    metadataRouteFile,
     listToolsRouteFile: resolve(routesDir, "[.mcp]", "list-tools.ts"),
     invokeToolRouteFile: resolve(routesDir, "[.mcp]", "invoke-tool", "$tool.ts")
   };
@@ -57,6 +59,24 @@ function assertUrlPathShape(urlPath) {
 function deriveRouteFileName(urlPath) {
   return `${assertUrlPathShape(urlPath)}.ts`;
 }
+function assertMetadataPathShape(metadataPath) {
+  if (!metadataPath.startsWith("/")) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath must start with "/", got "${metadataPath}"`);
+  }
+  if (/\/{2,}/.test(metadataPath)) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" contains empty segments ("//")`);
+  }
+  if (/(^|\/)\.\.(\/|$)/.test(metadataPath)) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" must not contain ".." segments`);
+  }
+  const trimmed = metadataPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!trimmed) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" has no route segment`);
+  }
+  if (!/^[a-zA-Z0-9_\-./]+$/.test(trimmed)) {
+    throw new Error(`@lovable.dev/mcp-js: metadataPath "${metadataPath}" contains unsupported characters`);
+  }
+}
 function canonicalUrlPath(urlPath) {
   return `/${urlPath.replace(/^\/+/, "").replace(/\/+$/, "")}`;
 }
@@ -65,10 +85,11 @@ function relativeImportSpecifier(routeFile, target) {
   const withoutExt = rel.replace(/\.ts$/, "");
   return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
 }
-function buildRouteSource(route, resourcePath, mcpEntry, projectRoot) {
+function buildRouteSource(route, resourcePath, metadataPath, mcpEntry, projectRoot) {
   const mcpImport = relativeImportSpecifier(route.file, mcpEntry);
   const routeRel = normalizePath(relative(projectRoot, route.file));
   const note = route.spaFallbackNote ? "      // ANY: TanStack returns SPA HTML for methods not in `handlers`; the SDK 405s instead.\n" : "";
+  const runtimeOptions = metadataPath === void 0 ? `{ resourcePath: "${resourcePath}" }` : `{ resourcePath: "${resourcePath}", metadataPath: "${metadataPath}" }`;
   return `${GENERATED_BANNER}
 // route: ${route.routeLiteral}
 // emitted to: ${routeRel}
@@ -82,7 +103,7 @@ import mcp from "${mcpImport}";
 export const Route = createFileRoute("${route.routeLiteral}")({
   server: {
     handlers: {
-${note}      ANY: ${route.handlerFactory}(mcp, { resourcePath: "${resourcePath}" }),
+${note}      ANY: ${route.handlerFactory}(mcp, ${runtimeOptions}),
     },
   },
 });
@@ -161,12 +182,23 @@ function mcpPlugin(options = {}) {
   const urlPath = canonicalUrlPath(rawUrlPath);
   const emitRestRoutes = options.restRoutes !== false;
   const emitProtectedResourceMetadataRoute = options.protectedResourceMetadataRoute !== false;
+  if (options.metadataPath !== void 0) {
+    if (!emitProtectedResourceMetadataRoute) {
+      throw new Error(
+        `@lovable.dev/mcp-js: metadataPath sets where the protected-resource metadata route is served, so it can't be combined with protectedResourceMetadataRoute: false.`
+      );
+    }
+    assertMetadataPathShape(options.metadataPath);
+  }
+  const metadataUrlPath = canonicalUrlPath(options.metadataPath ?? OAUTH_PROTECTED_RESOURCE_METADATA_PATH);
+  const injectedMetadataPath = emitProtectedResourceMetadataRoute ? metadataUrlPath : void 0;
   let projectRoot = process.cwd();
   let mcpEntry = resolve(projectRoot, mcpEntryOption);
   let { routesDir, mcpRouteFile, metadataRouteFile, listToolsRouteFile, invokeToolRouteFile } = resolveAllRoutes(
     projectRoot,
     routesDirOption,
-    routeFileName
+    routeFileName,
+    metadataUrlPath
   );
   const regenerate = () => {
     let mcpEntryExists = true;
@@ -185,7 +217,7 @@ function mcpPlugin(options = {}) {
       if (emitProtectedResourceMetadataRoute) {
         routes.push({
           file: metadataRouteFile,
-          routeLiteral: OAUTH_PROTECTED_RESOURCE_METADATA_PATH,
+          routeLiteral: metadataUrlPath,
           handlerFactory: "createTanStackOAuthProtectedResourceMetadataHandler"
         });
       }
@@ -207,7 +239,7 @@ function mcpPlugin(options = {}) {
       }
       for (const route of routes) {
         expected.add(route.file);
-        writeIfChanged(route.file, buildRouteSource(route, urlPath, mcpEntry, projectRoot));
+        writeIfChanged(route.file, buildRouteSource(route, urlPath, injectedMetadataPath, mcpEntry, projectRoot));
       }
     }
     for (const file of findAdoptedFiles(routesDir)) {
@@ -241,7 +273,8 @@ function mcpPlugin(options = {}) {
       ({ routesDir, mcpRouteFile, metadataRouteFile, listToolsRouteFile, invokeToolRouteFile } = resolveAllRoutes(
         projectRoot,
         routesDirOption,
-        routeFileName
+        routeFileName,
+        metadataUrlPath
       ));
       regenerate();
     },
@@ -267,6 +300,7 @@ function mcpPlugin(options = {}) {
 }
 var vite_default = mcpPlugin;
 export {
+  assertMetadataPathShape,
   assertUrlPathShape,
   vite_default as default,
   deriveRouteFileName,

package/dist/{types-zMlr1mOK.d.ts → types-C5SSORxe.d.ts}

@@ -52,6 +52,10 @@ interface McpAuthConfig {
      * `WWW-Authenticate: resource_metadata` challenge and does not generate or
      * serve its own metadata (the `/.well-known/oauth-protected-resource` handler
      * 404s). Use it when the resource server already publishes its own PRM.
+     *
+     * Mutually exclusive with the Vite plugin's `metadataPath`: that option has
+     * the SDK serve the document itself at a custom path, so configuring both is
+     * rejected at handler construction.
      */
     readonly protectedResourceMetadataUrl?: string;
     readonly requireOAuthClientClaim?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovable.dev/mcp-js",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Author MCP servers for Lovable apps. Declare tools with defineTool, register them in defineMcp, and the framework adapter (TanStack today, Supabase Edge Functions next) emits the route(s) at build time.",
   "type": "module",
   "repository": {

package/dist/authorize-DpTEIFvs.d.ts

@@ -1,9 +0,0 @@
-interface McpRuntimeOptions {
-    /**
-     * Public MCP protocol path. REST companion handlers pass this so OAuth
-     * resource/audience checks bind to `/mcp`, not internal `/.mcp/*` RPC URLs.
-     */
-    resourcePath?: string;
-}
-
-export type { McpRuntimeOptions as M };