@mongoosejs/studio 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+## 0.7.0
+
+### MCP support for Next.js and Vercel
+
+Mongoose Studio's MCP endpoint now works on Next.js and standalone Vercel Functions, not only Express.
+MCP uses the same defaults as Express: it is enabled by default without an `apiKey`, and with an `apiKey` it requires `mcp: true` and `publicUrl` and uses OAuth.
+
+For Next.js, rename `pages/api/studio.js` to the optional catch-all route `pages/api/studio/[[...studioRoute]].js`.
+The same `vercelAPIRouteHandler()` handles Studio actions at `/api/studio`, MCP at `/api/studio/mcp`, and OAuth metadata at `/api/studio/.well-known/oauth-protected-resource`.
+`withMongooseStudio()` now accepts a second `options` argument with `mcp`, `apiKey`, and `publicUrl`, and adds rewrites so MCP clients connect to `/studio/mcp`:
+
+```javascript
+// next.config.js
+export default withMongooseStudio({ reactStrictMode: true }, {
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+
+// pages/api/studio/[[...studioRoute]].js
+export default vercelAPIRouteHandler(db, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+```
+
+For standalone Vercel Functions, keep `api/studio.js` for Studio actions and add `api/studio-mcp.js` using the new `vercelMCPRouteHandler()`:
+
+```javascript
+// api/studio-mcp.js
+const { vercelMCPRouteHandler } = require('@mongoosejs/studio/vercel');
+
+module.exports = vercelMCPRouteHandler(mongoose, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+```
+
+With an `apiKey` and `mcp: true`, building the frontend with `frontend()` now writes the OAuth protected resource metadata to `frontend/public/.well-known/oauth-protected-resource` and registers `/api/studio-mcp` with the authorization server.
+Copy the frontend only after the `frontend()` promise resolves, and make sure the copy includes hidden directories such as `.well-known`.
+See the README for the full Vercel setup.
+
+### Breaking: Vercel and Next.js handlers without an API key are limited to localhost
+
+`vercelAPIRouteHandler()` now applies the same `bindIp` restriction as the Express integration.
+Without an `apiKey`, Studio API actions and MCP requests are only accepted from localhost by default, and other clients get a 403.
+On Vercel, the client IP comes from the `x-vercel-forwarded-for` header, so a deployed handler without an `apiKey` rejects every request unless you configure `bindIp`.
+
+Set `bindIp` to an IP address or an array of IP addresses to allow specific clients, or set `bindIp: null` to restore the previous behavior of accepting requests from any IP:
+
+```javascript
+const handler = vercelAPIRouteHandler(db, {
+  bindIp: null
+});
+```
+
+Handlers configured with an `apiKey` are unaffected.
+
+## 0.6.1
+
+### Safer MCP defaults with API keys
+
+MCP now defaults to disabled when Mongoose Studio is configured with an `apiKey`. Existing API-key integrations therefore continue to start without requiring additional MCP configuration.
+
+To enable OAuth-protected MCP, set `mcp: true` and provide `publicUrl` with the publicly reachable base URL where Mongoose Studio is mounted:
+
+```javascript
+app.use('/studio', await studio('/studio/api', mongoose, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  mcp: true,
+  publicUrl: 'https://myproduct.app/studio'
+}));
+```
+
+Mongoose Studio only requires `publicUrl` when both `apiKey` and `mcp: true` are set. Without an API key, MCP remains enabled by default and protected by `bindIp`.
+
+## 0.6.0
+
+### MCP support
+
+Mongoose Studio now serves an MCP endpoint at `<mount>/mcp` using the same access controls as the rest of Mongoose Studio.
+
+- MCP is enabled by default. Without an API key, access is protected by `bindIp`, so only clients running on the same machine can connect by default.
+- Set `mcp: false` to disable the MCP endpoint and its OAuth discovery metadata.
+- With an `apiKey`, MCP uses OAuth and requires `publicUrl` containing the publicly reachable base URL where Mongoose Studio is mounted, such as `https://myproduct.app/studio`.
+
+```javascript
+app.use('/studio', await studio('/studio/api', mongoose, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  publicUrl: 'https://myproduct.app/studio'
+}));
+```
+
+Mongoose Studio throws an error during setup when MCP is enabled with an `apiKey` but `publicUrl` is missing.

package/README.md

@@ -56,23 +56,24 @@ app.use('/studio', await studio('/studio/api', mongoose, {
 }));
 ```
 
-The Express integration also exposes a Streamable HTTP MCP endpoint at `/studio/mcp`.
-Set `mcp: false` to turn it off, along with the OAuth protected resource metadata that advertises it.
+Without an API key, the Express integration exposes a Streamable HTTP MCP endpoint at `/studio/mcp` by default.
+Set `mcp: false` to turn it off.
 It provides authorized Dashboard and Model actions, plus `Script.createScript`, as MCP tools.
 With a Pro API key, pass the logged-in Studio access token in the `Authorization` header (either directly or as a bearer token); tools receive that user's roles and permissions.
-Without workspace authentication, the MCP endpoint uses the same localhost and `bindIp` restrictions as the rest of Studio.
+Without workspace authentication, the MCP endpoint uses the same localhost and `bindIp` restrictions as the rest of Mongoose Studio.
 
 #### Connecting ChatGPT or Claude with OAuth
 
-With a Pro API key, `/studio/mcp` is also an OAuth 2.1 protected resource, so MCP clients such as ChatGPT and Claude can connect to it directly.
+With a Pro API key, MCP is disabled by default. Set `mcp: true` to expose `/studio/mcp` as an OAuth 2.1 protected resource so MCP clients such as ChatGPT and Claude can connect to it directly.
 Point the client at your `/studio/mcp` URL and it will discover the Mongoose Studio authorization server, walk the user through signing in and approving access, and receive a short-lived access token.
 Users review and revoke these connections from their Mongoose Studio account page, and the access an AI client gets can never exceed the access the user who approved it already has.
 
 Mongoose Studio advertises itself to MCP clients using its externally reachable URL.
-When MCP and a Pro API key are enabled, set `publicUrl` to the URL where Mongoose Studio is mounted:
+When enabling MCP with a Pro API key, also set `publicUrl` to the URL where Mongoose Studio is mounted:
 
 ```javascript
 opts.publicUrl = 'https://app.example.com/studio';
+opts.mcp = true;
 ```
 
 Mongoose Studio finds the authorization server through the mothership it is already configured to use, so it needs no separate authorization server configuration.
@@ -90,28 +91,109 @@ import withMongooseStudio from '@mongoosejs/studio/next';
 export default withMongooseStudio({
   // Your Next.js config here
   reactStrictMode: true,
+}, {
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
 });
 ```
 
-Then, add `pages/api/studio.js` to your Next.js project to host the Mongoose Studio API:
+Add `pages/api/studio/[[...studioRoute]].js` to your Next.js project to host
+both the Mongoose Studio API and MCP. If you already have
+`pages/api/studio.js`, move its handler into the new file and remove the old
+file. The optional catch-all keeps `/api/studio` working for existing Studio
+actions and also accepts `/api/studio/mcp` and the OAuth metadata path.
 
 ```javascript
+// pages/api/studio/[[...studioRoute]].js
 // Make sure to import the database connection
-import db from '../../src/db';
-import studio from '@mongoosejs/studio/backend/next';
+import db from '../../../src/db';
+import { vercelAPIRouteHandler } from '@mongoosejs/studio/vercel';
 
-const handler = studio(
+const handler = vercelAPIRouteHandler(
   db, // Mongoose connection or Mongoose global. Or null to use `import mongoose`.
   {
     apiKey: process.env.MONGOOSE_STUDIO_API_KEY, // optional
     connection: db, // Optional: Connection or Mongoose global. If omitted, will use `import mongoose`
     connectToDB: async () => { /* connection logic here */ }, // Optional: if you need to call a function to connect to the database put it here
+    mcp: true, // Also enabled by default without an API key
+    publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL // Required with an API key; e.g. https://app.example.com/studio
   }
 );
 
 export default handler;
 ```
 
+With `mcp: true`, the same API function handles Streamable HTTP
+at `/studio/mcp`. With an API key, it also serves OAuth discovery at
+`/studio/.well-known/oauth-protected-resource`. `withMongooseStudio` installs
+rewrites from those public URLs to the catch-all API route and shows
+`/studio/mcp` in the frontend. No additional API function or `mcpUrl` setting
+is needed. The rewrites are needed to keep the public URL at `/studio/mcp`;
+the catch-all file itself lives under `/api/studio`. A Pro API key is required
+for OAuth-based Vercel MCP. Without an API key, MCP is enabled by default and
+is limited to localhost unless `bindIp` is configured. Set `bindIp` to an IP
+address or an array of IP addresses to permit other clients; set it to `null`
+to allow access from any IP. The same restriction applies to Studio API actions.
+With an API key, set `publicUrl` to the externally reachable `/studio` URL. The OAuth resource
+URL is derived from it, even if the workspace's `baseUrl` differs.
+
+The handler is stateless and returns a JSON response for each POST. No Redis,
+sticky sessions, or long-lived SSE connection is needed. Tool calls still count
+against Vercel Function duration and payload limits, so set an appropriate
+`maxDuration` for longer database operations and keep results reasonably sized.
+
+### Standalone Vercel Functions
+
+If your project uses `api/studio.js` rather than Next.js, keep it for Studio
+actions and add a separate `api/studio-mcp.js` function for MCP. Next.js
+optional catch-all filenames such as `[[...studioRoute]].js` do not apply to
+standalone Vercel Functions:
+
+```javascript
+// api/studio-mcp.js
+// Make sure to import the database connection
+import db from '../../../src/db';
+const { vercelMCPRouteHandler } = require('@mongoosejs/studio/vercel');
+
+module.exports = vercelMCPRouteHandler(db, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+```
+
+Set `MONGOOSE_STUDIO_PUBLIC_URL` to the externally reachable Studio URL, for
+example `https://app.example.com/studio`, when using an API key. Without an
+API key, MCP is enabled by default and follows the same localhost and `bindIp`
+restriction described above. Connect MCP clients to `/api/studio-mcp`; no
+rewrite is required.
+
+For OAuth, the protected resource metadata is generated in the Studio frontend
+by the same `frontend()` call used to write `config.js`. It registers the MCP
+resource before the returned promise resolves, so copy the frontend after
+that promise resolves. Existing `publicUrl` fallbacks can stay as they are;
+the copy source must include hidden files:
+
+```javascript
+const { execSync } = require('child_process');
+const opts = {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+};
+require('@mongoosejs/studio/frontend')('/api/studio', true, opts).then(() => {
+  execSync('mkdir -p ./public/studio && cp -r ./node_modules/@mongoosejs/studio/frontend/public/. ./public/studio/');
+});
+```
+
+The `/.` source copies hidden directories such as `.well-known`; a `/*` source
+does not. This places `public/studio/.well-known/oauth-protected-resource`
+and registers `/api/studio-mcp` with the authorization server. The metadata is
+needed only with an API key. Set `Content-Type: application/json` and
+`Access-Control-Allow-Origin: *` for that static path, as in the
+[standalone Vercel example](development/movies-vercel/vercel.json). Its
+[build script](development/movies-vercel/build.js) shows the complete asset
+copy and metadata generation sequence.
+
 ### Nest.js
 
 Add `MongooseStudioModule` to your app module as follows.

package/backend/next.js

@@ -1,17 +1,41 @@
 'use strict';
 
 const Backend = require('./');
+const vercelMCP = require('./vercel/vercelMCP');
+const checkVercelBindIp = require('./vercel/checkBindIp');
 const { defaultMothershipURL } = require('../constants');
 
 module.exports = function next(conn, options) {
   options = { ...options };
+  options.mcp = options.mcp ?? !options.apiKey;
+  const checkRequest = checkVercelBindIp(options);
   const backend = Backend(conn, options.studioConnection, options);
+  const mcpHandlers = options.mcp ? vercelMCP(conn, options, backend) : null;
 
   const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
   let workspace = null;
 
   return async function wrappedNextJSFunction(req, res) {
+    if (!checkRequest(req, res)) {
+      return;
+    }
+
+    const route = req.query?.studioRoute;
+    if (route != null && (!Array.isArray(route) || route.length > 0)) {
+      const routePath = Array.isArray(route) ? route.join('/') : null;
+      if (routePath !== 'mcp' && routePath !== '.well-known/oauth-protected-resource') {
+        return res.status(404).json({ message: 'Not found' });
+      }
+      if (!mcpHandlers) {
+        return res.status(404).json({ message: 'Not found' });
+      }
+      return routePath === 'mcp'
+        ? mcpHandlers.endpoint(req, res)
+        : mcpHandlers.metadata(req, res);
+    }
+
     const params = { ...req.query, ...req.body, ...req.params, authorization: req.headers.authorization };
+    delete params.studioRoute;
     const actionName = params?.action;
 
     const authorization = params?.authorization;

package/backend/vercel/checkBindIp.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const isBindIPConnection = require('../helpers/isBindIPConnection');
+const isLocalhostConnection = require('../helpers/isLocalhostConnection');
+const normalizeBindIPOption = require('../helpers/normalizeBindIPOption');
+
+module.exports = function checkVercelBindIp(options) {
+  const hasBindIpOption = options.bindIp != null;
+  const bindIp = normalizeBindIPOption(options.bindIp);
+
+  return function checkRequest(req, res) {
+    if (options.apiKey || bindIp === null) {
+      return true;
+    }
+    const ip = (process.env.VERCEL && req.headers['x-vercel-forwarded-for']) ||
+      req.ip || req.socket?.remoteAddress || '';
+    const allowed = hasBindIpOption
+      ? isBindIPConnection({ ip }, bindIp)
+      : isLocalhostConnection({ ip });
+    if (!allowed) {
+      res.status(403).json({ message: 'Mongoose Studio without an API key only accepts localhost or configured bindIp connections' });
+    }
+    return allowed;
+  };
+};

package/backend/vercel/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../next');

package/backend/vercel/mcpConfig.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { defaultMothershipURL } = require('../../constants');
+
+module.exports = function vercelMCPConfig(options) {
+  if (!options.publicUrl) {
+    throw new Error('Mongoose Studio requires publicUrl when Vercel MCP is enabled with an API key');
+  }
+  const baseUrl = new URL(options.publicUrl);
+  baseUrl.search = '';
+  baseUrl.hash = '';
+  baseUrl.pathname = `${baseUrl.pathname.replace(/\/+$/, '')}/`;
+  const resource = new URL(options._mcpPath || 'mcp', baseUrl).toString();
+  const metadataUrl = new URL('.well-known/oauth-protected-resource', baseUrl).toString();
+  const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
+
+  return {
+    resource,
+    metadataUrl,
+    metadata: {
+      resource,
+      authorization_servers: [new URL(mothershipUrl).origin],
+      scopes_supported: ['mcp'],
+      bearer_methods_supported: ['header'],
+      resource_documentation: 'https://mongoosestudio.app/docs/'
+    }
+  };
+};

package/backend/vercel/vercelMCP.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const Backend = require('../');
+const mcp = require('../mcp');
+const mothership = require('../integrations/mothership');
+const vercelMCPConfig = require('./mcpConfig');
+const { defaultMothershipURL } = require('../../constants');
+
+module.exports = function createVercelMCPHandlers(conn, options, existingBackend) {
+  if (!options.mcp) {
+    throw new Error('Mongoose Studio requires mcp: true for the Vercel MCP handler');
+  }
+  const config = options.apiKey ? vercelMCPConfig(options) : null;
+  const { resource, metadataUrl } = config || {};
+  const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
+  const backend = existingBackend || Backend(conn, options.studioConnection, options);
+  let workspacePromise;
+  let registered = false;
+
+  async function workspace() {
+    if (!workspacePromise) {
+      workspacePromise = fetch(`${mothershipUrl}/getWorkspace`, {
+        method: 'POST',
+        body: JSON.stringify({ apiKey: options.apiKey }),
+        headers: { Authorization: `Bearer ${options.apiKey}`, 'Content-Type': 'application/json' }
+      }).then(async response => {
+        const data = await response.json();
+        if (!response.ok) {
+          throw new Error(data.message || `Mongoose Studio API Key Error ${response.status}`);
+        }
+        options.workspace = data.workspace;
+        return data.workspace;
+      }).catch(err => {
+        workspacePromise = null;
+        throw err;
+      });
+    }
+    return workspacePromise;
+  }
+
+  async function registerResource() {
+    if (registered) {
+      return;
+    }
+    try {
+      await mothership.Workspace.registerMCPResource({ apiKey: options.apiKey, resource }, options);
+      registered = true;
+    } catch (err) {
+      console.warn(`[MONGOOSE STUDIO] Could not register MCP resource ${resource}: ${err.message}`);
+    }
+  }
+
+  function challenge(res, error) {
+    const detail = error ? `, error="invalid_token", error_description="${error.replace(/"/g, '')}"` : '';
+    res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${metadataUrl}"${detail}`);
+  }
+
+  function cors(req, res) {
+    res.setHeader('Access-Control-Allow-Origin', req.headers.origin || '*');
+    res.setHeader('Vary', 'Origin');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Mcp-Protocol-Version, Mcp-Session-Id, Last-Event-ID');
+    res.setHeader('Access-Control-Expose-Headers', 'WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version');
+    res.setHeader('Access-Control-Max-Age', '86400');
+    if (req.method === 'OPTIONS') {
+      res.status(204).end();
+      return true;
+    }
+    return false;
+  }
+
+  async function metadata(req, res) {
+    if (!options.apiKey) {
+      return res.status(404).json({ message: 'Not found' });
+    }
+    if (cors(req, res)) {
+      return;
+    }
+    if (req.method !== 'GET') {
+      return res.status(405).end();
+    }
+    try {
+      await workspace();
+      await registerResource();
+      res.setHeader('Cache-Control', 'no-store');
+      return res.status(200).json(config.metadata);
+    } catch (err) {
+      return res.status(500).json({ message: err.message });
+    }
+  }
+
+  async function endpoint(req, res) {
+    if (cors(req, res)) {
+      return;
+    }
+    if (!options.apiKey) {
+      return mcp(backend)(req, res);
+    }
+    try {
+      const currentWorkspace = await workspace();
+      const token = `${req.headers.authorization || ''}`.replace(/^Bearer\s+/i, '').trim();
+      if (!token) {
+        await registerResource();
+        challenge(res);
+        return res.status(401).json({ message: 'Not authorized' });
+      }
+
+      let user;
+      let roles;
+      const context = { $workspaceId: currentWorkspace._id };
+      if (token.startsWith('mcp_at_')) {
+        const result = await mothership.MCPOAuthToken.introspectMCPAccessToken({
+          apiKey: options.apiKey, token, resource
+        }, options);
+        user = result.user;
+        roles = result.permissions.roles;
+        context.maxTimeMS = result.permissions.maxTimeMS;
+        context.readPreference = result.permissions.readPreference;
+      } else {
+        const response = await fetch(`${mothershipUrl}/me`, {
+          method: 'POST',
+          body: JSON.stringify({ workspaceId: currentWorkspace._id }),
+          headers: { Authorization: token, 'Content-Type': 'application/json' }
+        });
+        if (!response.ok) {
+          return res.status(response.status).json({ message: 'Not authorized' });
+        }
+        ({ user, roles } = await response.json());
+      }
+      if (!user || !roles) {
+        return res.status(403).json({ message: 'Not authorized' });
+      }
+      req._internals = {
+        ...context,
+        authorization: token,
+        initiatedById: user._id,
+        initiatedBy: user,
+        userId: user._id,
+        roles
+      };
+      return mcp(backend)(req, res);
+    } catch (err) {
+      if (err.status === 401 || err.status === 403) {
+        challenge(res, err.message);
+        return res.status(401).json({ message: err.message });
+      }
+      return res.status(500).json({ message: err.message });
+    }
+  }
+
+  return { endpoint, metadata };
+};

package/backend/vercel/vercelMCPRouteHandler.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const Backend = require('../');
+const checkVercelBindIp = require('./checkBindIp');
+const vercelMCP = require('./vercelMCP');
+
+module.exports = function vercelMCPRouteHandler(conn, options) {
+  options = { ...options, mcp: true, _mcpPath: '/api/studio-mcp' };
+  const checkRequest = checkVercelBindIp(options);
+  const backend = Backend(conn, options.studioConnection, options);
+  const { endpoint } = vercelMCP(conn, options, backend);
+
+  return function wrappedVercelMCPRouteHandler(req, res) {
+    if (!checkRequest(req, res)) {
+      return;
+    }
+    return endpoint(req, res);
+  };
+};

package/docs/mcp-oauth.md

@@ -24,7 +24,7 @@ It publishes metadata that tells clients where the authorization server is, and
 8. On every MCP request, Studio asks the authorization server to resolve the access token, and runs the request under the policy it returns.
 
 Authorization Code with PKCE (`S256`) is required, and there are no client secrets: MCP clients are public clients.
-Access tokens live 15 minutes.
+Access tokens live 24 hours.
 Refresh tokens live 30 days and rotate on every use, so a user does not have to reconnect the client regularly.
 
 ## Authorization grants
@@ -84,17 +84,18 @@ They can only narrow what the host application already allows: `maxTimeMS` is ca
 
 ## Configuration
 
-The Mongoose Studio side needs a Pro API key and its own externally reachable URL, since the resource identifier is that URL.
-Set `publicUrl` to the URL where Mongoose Studio is mounted:
+MCP is disabled by default when Mongoose Studio has a Pro API key.
+To enable it, set `mcp: true` and set `publicUrl` to the externally reachable URL where Mongoose Studio is mounted:
 
 ```javascript
 app.use('/studio', await studio('/studio/api', mongoose, {
   apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  mcp: true,
   publicUrl: 'https://app.example.com/studio'
 }));
 ```
 
-Pass `mcp: false` to serve Studio without an MCP endpoint at all.
+Pass `mcp: false` to serve Mongoose Studio without an MCP endpoint at all.
 Neither the endpoint nor its protected resource metadata is then mounted, so there is nothing for an MCP client to discover.
 Without an API key, the MCP endpoint follows the normal localhost or `bindIp` restrictions and does not mount OAuth protected resource metadata.
 
@@ -102,5 +103,5 @@ Mongoose Studio registers that URL with the authorization server the first time
 It advertises the configured mothership's origin in `authorization_servers`, keeping authentication with the same service Mongoose Studio already uses.
 
 Browser based MCP clients, claude.ai among them, run discovery from the page rather than from a server.
-Studio therefore serves the MCP endpoint and its metadata with CORS, and exposes `WWW-Authenticate` via `Access-Control-Expose-Headers`.
+Mongoose Studio therefore serves the MCP endpoint and its metadata with CORS, and exposes `WWW-Authenticate` via `Access-Control-Expose-Headers`.
 Without that last header a browser hides the challenge from the client, and the client cannot find the authorization server at all.

package/express.js

@@ -17,10 +17,11 @@ const MCP_ACCESS_TOKEN_PREFIX = 'mcp_at_';
 module.exports = async function mongooseStudioExpressApp(apiUrl, conn, options) {
   const router = express.Router();
   options = options ? { changeStream: true, ...options } : { changeStream: true };
-  if (options.mcp !== false && options.apiKey && !options.publicUrl) {
+  options.mcp = options.mcp ?? !options.apiKey;
+  if (options.mcp && options.apiKey && !options.publicUrl) {
     throw new Error('Mongoose Studio requires the publicUrl option when MCP is enabled with an API key');
   }
-  const hasBindIpOption = Object.prototype.hasOwnProperty.call(options, 'bindIp');
+  const hasBindIpOption = options.bindIp != null;
   const bindIp = normalizeBindIPOption(options.bindIp);
 
   const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
@@ -124,10 +125,10 @@ module.exports = async function mongooseStudioExpressApp(apiUrl, conn, options)
   // issued by the mothership. Mongoose Studio is the protected resource: it publishes the
   // metadata that points clients at the authorization server, and resolves each
   // token to its current grant before handling the request.
-  const mcpEnabled = options.mcp !== false;
+  const mcpEnabled = options.mcp;
   const registeredMCPResources = new Set();
   const mcpAuthorizationServerUrl = new URL(mothershipUrl).origin;
-  const mcpResource = workspace ? canonicalize(`${options.publicUrl.replace(/\/+$/, '')}/mcp`) : null;
+  const mcpResource = mcpEnabled && workspace ? canonicalize(`${options.publicUrl.replace(/\/+$/, '')}/mcp`) : null;
 
   async function registerMCPResource(resource) {
     if (registeredMCPResources.has(resource)) {

package/frontend/index.js

@@ -5,6 +5,8 @@ const fs = require('fs');
 const path = require('path');
 const webpack = require('webpack');
 const { defaultMothershipURL } = require('../constants');
+const mothership = require('../backend/integrations/mothership');
+const vercelMCPConfig = require('../backend/vercel/mcpConfig');
 const webpackConfig = require('./webpack.config');
 const util = require('util');
 
@@ -33,11 +35,18 @@ module.exports = async function frontend(apiUrl, isLambda, options, workspace) {
 
   const { apiKey, ...workspaceData } = workspace || {};
   const workspaceBaseUrl = workspace?.baseUrl?.replace(/\/+$/, '');
+  const publicBaseUrl = options?.publicUrl?.replace(/\/+$/, '') || workspaceBaseUrl;
+  const mcpPath = options?._mcpPath || (isLambda && options?.mcp === true ? '/api/studio-mcp' : null);
+  const mcpEnabled = options?.mcp ?? !options?.apiKey;
   const config = {
     baseURL: apiUrl,
     isLambda,
-    mcp: options?.mcp !== false,
-    mcpUrl: workspaceBaseUrl ? `${workspaceBaseUrl}/mcp` : null,
+    mcp: mcpEnabled,
+    mcpUrl: mcpEnabled
+      ? mcpPath
+        ? publicBaseUrl ? new URL(mcpPath, `${publicBaseUrl}/`).toString() : mcpPath
+        : publicBaseUrl ? `${publicBaseUrl}/mcp` : null
+      : null,
     mothershipUrl: apiKey ? mothershipUrl : null,
     workspace: workspaceData
   };
@@ -45,6 +54,19 @@ module.exports = async function frontend(apiUrl, isLambda, options, workspace) {
   if (isLambda) {
     const configPath = path.join(__dirname, './public/config.js');
     fs.writeFileSync(configPath, `window.MONGOOSE_STUDIO_CONFIG = ${JSON.stringify(config, null, 2)};`);
+
+    // The caller copies frontend/public after this promise resolves. Put the
+    // protected resource document there so the same copy includes it.
+    const metadataPath = path.join(__dirname, 'public/.well-known/oauth-protected-resource');
+    if (options?.apiKey && options?.mcp === true) {
+      fs.rmSync(metadataPath, { force: true });
+      const mcpConfig = vercelMCPConfig({ ...options, _mcpPath: '/api/studio-mcp' });
+      await mothership.Workspace.registerMCPResource({ apiKey: options.apiKey, resource: mcpConfig.resource }, options);
+      fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
+      fs.writeFileSync(metadataPath, JSON.stringify(mcpConfig.metadata, null, 2));
+    } else {
+      fs.rmSync(metadataPath, { force: true });
+    }
   }
 
   if (options && options.__watch) {