zuplo 6.67.32 → 6.68.0

package/docs/articles/configuring-auth0-for-mcp-auth.mdx

@@ -0,0 +1,186 @@
+---
+title: Setting up Auth0 as an Authentication Server for MCP OAuth Authentication
+sidebar_label: "Auth0 Setup"
+description:
+  Learn how to configure Auth0 as an Authorization Server for use with the MCP
+  Server handler and OAuth authentication.
+tags:
+  - authentication
+  - integrations
+---
+
+In this guide, you'll learn how to configure Auth0 as an Authorization Server
+for use with the MCP Server handler. See the
+[MCP Server Handler docs](../handlers/mcp-server.mdx#oauth-authentication) for
+instructions on how to configure your Zuplo gateway to support OAuth
+authentication for your MCP Server.
+
+This guide will assume that you already have a working Auth0 account and tenant.
+
+### Create an Auth0 API
+
+First, you will need to create an Auth0 API. This API will be used to represent
+your MCP Server.
+
+1. In the Auth0 dashboard, navigate to the _Applications > APIs_ section and
+   click **Create API**.
+2. Set the **Name** to something like "MCP Server" and the **Identifier** to the
+   canonical URL of your MCP Server. For example, if your MCP Server is hosted
+   at `https://my-gateway.zuplo.dev/mcp`, then the identifier would be
+   `https://my-gateway.zuplo.dev/mcp`. **The trailing slash isn't required.**
+3. Leave the **Signing Algorithm** as `RS256` and click **Create**.
+
+### Enable Dynamic Client Registration
+
+Next, you will need to enable Dynamic Client Registration for the API you just
+created.
+
+1. In the Auth0 dashboard, navigate to the tenant settings in **Settings** on
+   the left hand sidebar.
+2. Navigate to the **Advanced** tab.
+3. Scroll down to the **Settings** section and check the toggle for **OIDC
+   Dynamic Application Registration**. Also ensure that the **Enable Application
+   Connections** toggle is checked.
+
+### Configure the Connection
+
+Next, you will need to configure an Auth0 Connection for your API.
+
+1. Click the **Authentication** tab in the left hand sidebar.
+
+2. Click the type of Authentication connection you would like to use. For this
+   tutorial, we will use the default Database
+   **Username-Password-Authentication** connection. If you aren't using the
+   default database connection, then create a new connection of the type you
+   want to use and configure it with your desired settings. Click the **Try
+   Connection** button to make sure that it's working. Note the Identifier of
+   the connection. You will need this in one of the next steps.
+
+3. Promote the connection that you would like to use for your MCP Client
+   authentication to be a domain level connection. To do this, you will need to
+   use the Auth0 management API. You will need to create an Auth0 Management API
+   token with the `update:connections` scope. You can obtain one by following
+   this
+   [Auth0 doc](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing).
+
+4. Follow the
+   [Promote Connections to Domain Level](https://auth0.com/docs/authenticate/identity-providers/promote-connections-to-domain-level)
+   Auth0 doc to promote your connection to a domain level connection. You will
+   need the connection ID from step 2, as well as the Auth0 Management API token
+   from step 3.
+
+   For example using curl:
+
+   ```sh
+   curl --request PATCH \
+   --url 'https://your-auth0-domain.us.auth0.com/api/v2/connections/CONNECTION_ID' \
+   --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
+   --header 'cache-control: no-cache' \
+   --header 'content-type: application/json' \
+   --data '{ "is_domain_connection": true }'
+   ```
+
+5. Configure a Default Audience by clicking on Settings > General. Then in the
+   API Authorization Settings, modify the Default Audience. See the Auth0 doc on
+   [API Authorization Settings](https://auth0.com/docs/get-started/tenant-settings#api-authorization-settings)
+   for more information on how to configure a default audience. The audience
+   should be the identifier of the API you created in
+   [Create an Auth0 API](#create-an-auth0-api).
+
+### Configure OAuth on Zuplo
+
+To set up your gateway to support OAuth authentication for your MCP Server, you
+will need to do the following:
+
+1. Create an OAuth policy on your MCP Server route. This policy will need to
+   have the option `"oAuthResourceMetadataEnabled": true`, for example:
+   ```json
+   {
+     "name": "mcp-oauth-inbound",
+     "policyType": "oauth-inbound",
+     "handler": {
+       "export": "Auth0JwtInboundPolicy",
+       "module": "$import(@zuplo/runtime)",
+       "options": {
+         "auth0Domain": "my-auth0-domain.us.auth0.com",
+         "audience": "https://my-mcp-audience",
+         "oAuthResourceMetadataEnabled": true
+       }
+     }
+   }
+   ```
+2. Add the OAuth policy to the MCP Server route. For example:
+
+   ```json
+   "paths": {
+     "/mcp": {
+       "post": {
+         "x-zuplo-route": {
+           // etc. etc.
+           // other properties and route handlers for MCP
+
+           "policies": {
+             "inbound": [
+               "mcp-oauth-inbound"
+             ]
+           }
+         }
+       }
+     }
+   }
+   ```
+
+3. Add the `OAuthProtectedResourcePlugin` to your `runtimeInit` function in the
+   `zuplo.runtime.ts` file:
+
+   ```ts
+   import {
+     RuntimeExtensions,
+     OAuthProtectedResourcePlugin,
+   } from "@zuplo/runtime";
+
+   export function runtimeInit(runtime: RuntimeExtensions) {
+     runtime.addPlugin(
+       new OAuthProtectedResourcePlugin({
+         authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
+         resourceName: "My MCP OAuth Resource",
+       }),
+     );
+   }
+   ```
+
+   See the
+   [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin)
+   for more details.
+
+See the
+[MCP Server Handler docs](../handlers/mcp-server.mdx#oauth-authentication) for
+more details.
+
+### Testing
+
+Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), a
+developer focused tool for building MCP servers, to quickly and easily test out
+your MCP server:
+
+```sh
+npx @modelcontextprotocol/inspector
+```
+
+To connect to your remote Zuplo MCP server in the Inspector UI:
+
+1. Set the **Transport Type** to "Streamable HTTP"
+2. Set the **URL** to your Zuplo gateway with the route used by the MCP Server
+   Handler (that is, `https://my-gateway.zuplo.dev/mcp`)
+3. You will need to login using the OAuth flow using the **Open Auth Settings**
+   button.
+4. Hit **Connect**.
+
+For debugging your OAuth configuration, hit the **Open Auth Settings** button in
+the Inspector UI to start the OAuth flow. When first setting up the OAuth flow,
+it's recommmended to use the **Guided OAuth Flow** which you will see when you
+open the OAuth settings. This will allow you to debug the flow step by step.
+
+You should be able to hit the **Continue** button in the Inspector UI at each
+step of the flow successfully. If you need more help debugging, see
+[Testing OAuth on Zuplo](../handlers/mcp-server.mdx#oauth-testing).

package/docs/articles/configuring-okta-for-mcp-auth.mdx

@@ -0,0 +1,208 @@
+---
+title: Setting up Okta as an Authentication Server for MCP OAuth Authentication
+sidebar_label: "Okta Setup"
+description:
+  Learn how to configure Okta as an authorization server for OAuth
+  authentication with MCP Server handler.
+tags:
+  - authentication
+  - integrations
+---
+
+<!-- vale Vale.Spelling["URIs"] = NO -->
+
+In this guide, you'll learn how to configure Okta as an authorization server for
+use with the MCP Server handler. See the
+[MCP Server Handler docs](../handlers/mcp-server.mdx#oauth-authentication) for
+instructions on how to configure your Zuplo gateway to support OAuth
+authentication for your MCP Server.
+
+This guide will assume that you already have a working Okta account and
+organization.
+
+## Create an Auth Server
+
+First, you will need to create an Okta authorization server. This server will be
+used to authorize requests to your MCP Server per
+[the Model Context Protocol authorization specification.](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
+
+1. In the Okta Admin Console, navigate to **Security > API** in the left
+   sidebar.
+2. Click **Add Authorization Server**.
+3. Set the **Name** to something like "MCP Server Authorization".
+4. Set the **Audience** to the canonical URL of your MCP Server. For example, if
+   your MCP Server is hosted at `https://my-gateway.zuplo.dev/mcp`, then the
+   audience would be `https://my-gateway.zuplo.dev/mcp`. **The trailing slash is
+   not required.**
+5. Add a **Description** and click **Save**.
+
+Note the **Issuer Metadata URI** shown in the authorization server details.
+You'll need this for your Zuplo configuration.
+
+## Configure Scopes
+
+Next, you'll need to configure the scopes for your authorization server.
+
+1. In your authorization server settings, click the **Scopes** tab.
+2. Click **Add Scope**.
+3. Set the **Name** to something like `mcp:access`.
+4. Add a **Display phrase** and **Description** (like "Access to MCP Server
+   tools").
+5. Check **Set as a default scope** and click **Create**.
+
+## Create an OAuth Client Application
+
+Next, you'll need to create an OAuth client application for your MCP server.
+
+:::note
+
+Okta requires an admin API key for to dynamically register clients. This may not
+be well supported by MCP clients. However, MCP clients should also support an
+alternative way to obtain a client ID and client credential. This document
+assumes an MCP client can set these fields without having to dynamically
+register a client.
+
+:::
+
+1. In the Okta Admin Console, navigate to **Applications > Applications** in the
+   left sidebar.
+2. Click **Create App Integration**.
+3. Select **OIDC - OpenID Connect** as the sign-in method.
+4. Select **Web Application** as the application type and click **Next**.
+5. Set the **App integration name** to something like "MCP Client Application".
+6. For **Grant types**, check **Authorization Code** and **Refresh Token**.
+7. For **Sign-in redirect URIs**, leave this empty or set to a placeholder like
+   `http://localhost:3000/callback`.
+8. For **Controlled access**, select **Allow everyone in your organization to
+   access**.
+9. Click **Save**.
+
+After creating the application, note the **Client ID** and **Client Secret**
+from the application's **General** tab. You'll need these for your MCP client
+configuration.
+
+## Create a Default Policy and Rule
+
+You'll need to create an access policy for your authorization server.
+
+1. In your authorization server settings (found in **Security > API**) click the
+   **Access Policies** tab.
+2. Click **Add New Access Policy**.
+3. Set the **Name** to something like "MCP Client Access Policy".
+4. Add a **Description** and assign it to **All clients**.
+5. Click **Create Policy**.
+
+Now create a rule for this policy:
+
+1. Click **Add Rule** within your new policy.
+2. Set the **Rule Name** to something like "Allow MCP Access".
+3. In the **IF AND** section:
+   - **Grant type is**: Select the grant type. For the widest grant for all MCP
+     clients, select **Client Credentials**, **Authorization Code**, and
+     **Device Authorization**
+   - **User is**: Select **Any user assigned the app**
+   - **Scopes requested**: Select **The following scopes** and choose the scope
+     you created for the authorization server (that is, `mcp:access`)
+4. In the **THEN AND** section:
+   - **Use this inline hook**: None (disabled)
+   - **Access token lifetime is**: Set to desired value (for example, 1 hour)
+   - **Refresh token lifetime is**: Set to desired value (for example, 90 days)
+5. Click **Create Rule**.
+
+## Configure OAuth on Zuplo
+
+To set up your gateway to support OAuth authentication for your MCP Server, you
+will need to do the following:
+
+1. Create an Okta JWT Auth inbound policy on your MCP Server route. This policy
+   will need to have the option `"oAuthResourceMetadataEnabled": true` to enable
+   authorization resource metadata discovery.
+
+   ```json
+   {
+     "name": "mcp-okta-oauth-inbound",
+     "policyType": "okta-jwt-auth-inbound",
+     "handler": {
+       "export": "OktaJwtInboundPolicy",
+       "module": "$import(@zuplo/runtime)",
+       "options": {
+         "oAuthResourceMetadataEnabled": true,
+         "audience": "https://my-gateway.zuplo.dev/mcp",
+         "issuer": "https://your-okta-domain.okta.com/oauth2/your-auth-server-id"
+       }
+     }
+   }
+   ```
+
+   - Replace `my-gateway.zuplo.dev/mcp` with the audience you defined in your
+     authorization server.
+   - Replace `your-okta-domain` in the `issuer` field with your actual Okta
+     domain.
+   - Replace `your-auth-server-id` in the `issuer` field with the actual ID of
+     your Okta authorization server.
+
+2. Add the OAuth policy to the MCP Server route. For example:
+
+   ```json
+   "paths": {
+     "/mcp": {
+       "post": {
+         "x-zuplo-route": {
+
+           // etc. etc.
+           // other properties for the MCP server route handler
+
+           "policies": {
+             "inbound": [
+               "mcp-oauth-inbound"
+             ]
+           }
+         }
+       }
+     }
+   }
+   ```
+
+3. Add the `OAuthProtectedResourcePlugin` to your `runtimeInit` function in the
+   `modules/zuplo.runtime.ts` file:
+
+   ```ts
+   import {
+     RuntimeExtensions,
+     OAuthProtectedResourcePlugin,
+   } from "@zuplo/runtime";
+
+   export function runtimeInit(runtime: RuntimeExtensions) {
+     runtime.addPlugin(
+       new OAuthProtectedResourcePlugin({
+         authorizationServers: [
+           "https://your-okta-domain.okta.com/oauth2/your-auth-server-id",
+         ],
+         resourceName: "My MCP OAuth Resource",
+       }),
+     );
+   }
+   ```
+
+   - Replace `your-okta-domain` in the `issuer` field with your actual Okta
+     domain.
+   - Replace `your-auth-server-id` in the `issuer` field with the actual ID of
+     your Okta authorization server.
+
+   This plugin populates the `.well-known` routes for the MCP server auth
+   metadata discovery. This enables MCP clients to automatically discover the
+   authorization issuer endpoint. See the
+   [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin)
+   for more details on this runtime plugin.
+
+## Testing
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) doesn't
+currently support setting an initial access token or presenting a UI for setting
+the client ID or secret.
+
+Refer to the [Manual OAuth MCP Testing](./manual-mcp-oauth-testing) guide for
+further instructions on testing your MCP server with `curl`.
+
+If you need more help debugging, see
+[Testing OAuth on Zuplo](../handlers/mcp-server.mdx#oauth-testing).

package/docs/articles/convert-urls-to-openapi.mdx

@@ -0,0 +1,62 @@
+---
+title: Script to Convert URL Params to OpenAPI Format
+sidebar_label: "Convert URLs to OpenAPI"
+description:
+  Learn how to convert Zuplo URL parameters to standard OpenAPI format using
+  this JavaScript conversion script.
+tags:
+  - openapi
+  - deployment
+---
+
+This is an example script that shows how to convert URLs in your Zuplo OpenAPI
+files to OpenAPI formatted parameters.
+
+```js
+import fs from "fs/promises";
+import kabab from "kebab-case";
+import path from "path";
+import { pathToRegexp } from "path-to-regexp";
+import prettier from "prettier";
+
+const files = await fs.readdir(path.join(process.cwd(), "config"));
+await Promise.all(
+  files.map(async (file) => {
+    if (file.endsWith(".oas.json")) {
+      const specPath = path.join(process.cwd(), "config", file);
+      const content = await fs.readFile(specPath, "utf-8").then(JSON.parse);
+      const newPaths = {};
+      Object.entries(content.paths).forEach(([path, entry]) => {
+        delete entry["x-zuplo-path"];
+        const keys = [];
+        pathToRegexp(path, keys);
+        let newPath = path;
+        keys.forEach((key) => {
+          newPath = newPath.replace(`:${key.name}`, `{${kababCase(key.name)}}`);
+        });
+        Object.entries(entry).forEach(([method, methodEntry]) => {
+          if (entry[method].parameters) {
+            entry[method].parameters.forEach((param) => {
+              if (param.in === "path") {
+                param.name = kababCase(param.name);
+              }
+            });
+          }
+        });
+        newPaths[newPath] = entry;
+      });
+
+      content.paths = newPaths;
+
+      const json = JSON.stringify(content, null, 2);
+      const output = prettier.format(json, { parser: "json" });
+
+      await fs.writeFile(specPath, output, "utf-8");
+    }
+  }),
+);
+
+function kababCase(str) {
+  return kabab(str).replaceAll("-u-r-l", "-url").replaceAll("-a-p-i", "-api");
+}
+```