refactor: add use case catelogs

Author: gao-sun

docs/quick-starts/third-party/oidc/README.mdx

@@ -6,6 +6,8 @@ sidebar_custom_props:
   logoFilename: 'oidc.svg'
 ---
 
+import QuickStartsReference from './_quick-starts-reference.md';
+
 # Integrate third-party app with OIDC / OAuth
 
 Use Logto as your identity provider (IdP) to integrate third-party apps via OpenID Connect (OIDC) or OAuth 2.0 protocol.
@@ -35,9 +37,12 @@ In order to set up Logto as an IdP for your third-party applications, you need t
 3. Retrieve the **authorization endpoint** and **token endpoint** from Logto application details page and provide them to your service provider.
 
    - If your service provider supports OIDC discovery, you can simply copy the **discovery endpoint** from Logto application details page and provide it to your service provider. The service provider will be able to retrieve all the up to date OIDC authentication information from the discovery endpoint automatically.
-
    - Otherwise, click on the **Show endpoint details** button to view all the OIDC authentication endpoints.
 
+---
+
+<QuickStartsReference />
+
 ## Manage your third-party applications \{#manage-your-third-party-applications}
 
 All third-party applications will be catalogued on the **Applications** page, specifically under the **Third-party apps** tab. This arrangement distinguishes them from first-party applications for you, ensuring easy management.

docs/quick-starts/third-party/oidc/_quick-starts-reference.md

@@ -0,0 +1,11 @@
+Under the hood, a third-party app is just a standard OAuth 2.0 / OIDC client. This means you (or the third-party developer) can use any OAuth 2.0 / OIDC library or framework to integrate with Logto.
+
+If you're not familiar with OAuth 2.0 or OIDC, you can start by following one of our “Traditional web” quick start guides.
+
+A few things to keep in mind:
+
+1. Logto currently requires third-party apps to be “Traditional web” apps. In other words, the app needs a backend server (or backend-for-frontend) to securely store the client secret.
+2. Most our quick start guides are written for first-party apps, but you can still use them as a reference for third-party app integration.
+3. The main difference is that third-party apps will show a consent screen, asking users for explicit permission to access their data.
+
+You can find more information in our [quick start guides](https://docs.logto.io/quick-starts).

docs/use-cases/README.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+---
+
+import AiCatalog from './ai/fragments/_catalog.mdx';
+import AuthorizationCatalog from './authorization/fragments/_catalog.mdx';
+import MultiTenancyCatalog from './multi-tenancy/fragments/_catalog.mdx';
+
+# Logto use cases
+
+Logto is a powerful auth infrastructure and identity and access management (IAM) solution that can be used in various scenarios. We have created a series of use cases to help you understand how to leverage Logto in different contexts.
+
+## Authorization
+
+<AuthorizationCatalog headingLevel={3} />
+
+## Multi-tenancy
+
+<MultiTenancyCatalog headingLevel={3} />
+
+## AI
+
+<AiCatalog headingLevel={3} />

docs/use-cases/README.mdx

@@ -1,55 +1,11 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
 sidebar_label: AI use cases
 description: Explore how Logto can help you build secure, AI-enabled experiences.
 ---
 
-import AuthorizationIcon from '@site/src/assets/authorization.svg';
+import Catalog from './fragments/_catalog.mdx';
 
 # AI integration use cases with Logto
 
-Explore how Logto empowers you to build secure, AI-enabled experiences. Whether you’re implementing the Model Context Protocol (MCP) or integrating AI agents into your app, Logto offers developer-friendly authentication and authorization solutions.
-
-## Build your MCP server
-
-<DocCardList
-  items={[
-    {
-      type: 'link',
-      label: 'Enable auth for your MCP-powered apps',
-      href: '/use-cases/ai/mcp-server-add-auth',
-      description:
-        'Learn how to integrate authentication and authorization into your MCP server, allowing secure access for your own apps and services.',
-      customProps: {
-        icon: <AuthorizationIcon />,
-      },
-    },
-    {
-      type: 'link',
-      label: 'Enable AI agent and third-party app access to your MCP server',
-      href: '/use-cases/ai/mcp-server-enable-ai-agent-and-third-party-access',
-      description:
-        'Find out how to enable authentication and authorization for AI agents and third-party apps connecting to your MCP server.',
-      customProps: {
-        icon: <AuthorizationIcon />,
-      },
-    },
-  ]}
-/>
-
-## AI-ready auth for your app
-
-<DocCardList
-  items={[
-    {
-      type: 'link',
-      label: 'Enable AI agent access to your app',
-      href: '/use-cases/ai/enable-ai-agent-access',
-      description:
-        'Discover how to add authentication and authorization for AI agents accessing your app, ensuring security and control across AI-driven workflows.',
-      customProps: {
-        icon: <AuthorizationIcon />,
-      },
-    },
-  ]}
-/>
+<Catalog />

docs/use-cases/ai/README.mdx

@@ -4,3 +4,26 @@ sidebar_label: Enable AI agent access to app
 ---
 
 # Enable AI agent access to your app
+
+:::caution
+👷 This tutorial is still in progress. Please check back later for updates. 🚧
+:::
+
+This guide walks you through integrating Logto with your service and enabling AI agents to access it.
+
+You'll learn how to:
+
+- Configure Logto as the authorization server for your service.
+- Obtain an access token for the AI agent to access your service.
+- Test the flow with an AI agent.
+
+## Prerequisites
+
+- A [Logto Cloud](https://cloud.logto.io) (or self-hosted) tenant
+- A service that exposes API endpoints to be accessed by the AI agent
+
+### Understanding the flow
+
+- **Service**: The service you want to expose to the AI agent.
+- **AI agent**: The AI agent that will access your service.
+- **Logto**: Serves as the OpenID Connect provider (authorization server) and manages user identities.

docs/use-cases/ai/enable-ai-agent-access.mdx

@@ -0,0 +1,50 @@
+import FlaskIcon from '@site/src/assets/flask.svg';
+import RobotIcon from '@site/src/assets/robot.svg';
+import SecurityIcon from '@site/src/assets/security.svg';
+import DynamicHeading from '@site/src/components/DynamicHeading';
+
+Explore how Logto empowers you to build secure, AI-enabled experiences. Whether you’re implementing the Model Context Protocol (MCP) or integrating AI agents into your app, Logto offers developer-friendly authentication and authorization solutions.
+
+<DynamicHeading level={props.headingLevel ?? 2}>Build your MCP server</DynamicHeading>
+
+<DocCardList
+  items={[
+    {
+      type: 'link',
+      label: 'Enable auth for your MCP-powered apps',
+      href: '/use-cases/ai/mcp-server-add-auth',
+      description:
+        'Learn how to integrate authentication and authorization into your MCP server, allowing secure access for your own apps and services.',
+      customProps: {
+        icon: <SecurityIcon />,
+      },
+    },
+    {
+      type: 'link',
+      label: 'Enable AI agent and third-party app access to your MCP server',
+      href: '/use-cases/ai/mcp-server-enable-ai-agent-and-third-party-access',
+      description:
+        'Find out how to enable authentication and authorization for AI agents and third-party apps connecting to your MCP server.',
+      customProps: {
+        icon: <FlaskIcon />,
+      },
+    },
+  ]}
+/>
+
+<DynamicHeading level={props.headingLevel ?? 2}>AI-ready auth for your app</DynamicHeading>
+
+<DocCardList
+  items={[
+    {
+      type: 'link',
+      label: 'Enable AI agent access to your app',
+      href: '/use-cases/ai/enable-ai-agent-access',
+      description:
+        'Discover how to add authentication and authorization for AI agents accessing your app, ensuring security and control across AI-driven workflows.',
+      customProps: {
+        icon: <RobotIcon />,
+      },
+    },
+  ]}
+/>

docs/use-cases/ai/fragments/_catalog.mdx

@@ -6,14 +6,14 @@
 ### Understanding the architecture
 
 - **MCP server**: The server that exposes tools and resources to MCP clients.
-- **MCP Inspector**: A MCP client used to initiate the authentication flow and test the integration.
+- **MCP client**: A client used to initiate the authentication flow and test the integration. {props.clientDescription && <b>{props.clientDescription}</b>}
 - **Logto**: Serves as the OpenID Connect provider (authorization server) and manages user identities.
 
 A non-normative sequence diagram illustrates the overall flow of the process:
 
 ```mermaid
 sequenceDiagram
-    participant Client as MCP Inspector
+    participant Client as Client
     participant Server as MCP Server
     participant Logto
 

docs/use-cases/ai/fragments/_mcp-introduction.mdx

@@ -4,12 +4,12 @@ import Tabs from '@theme/Tabs';
 <Tabs groupId="sdk">
 <TabItem value="python" label="Python">
 
-The full code can be found in the [mcp-auth/python](https://github.com/mcp-auth/python) repository.
+The full MCP server code can be found in the [mcp-auth/python](https://github.com/mcp-auth/python) repository.
 
 </TabItem>
 <TabItem value="node" label="Node.js">
 
-The full code can be found in the [mcp-auth/js](https://github.com/mcp-auth/js) repository.
+The full MCP server code can be found in the [mcp-auth/js](https://github.com/mcp-auth/js) repository.
 
 </TabItem>
 </Tabs>

docs/use-cases/ai/fragments/_mcp-prerequisites.mdx

@@ -3,17 +3,28 @@ sidebar_position: 1
 sidebar_label: Enable auth for MCP-powered apps
 ---
 
-import Introduction from './fragments/_mcp-introduction.mdx';
 import Prerequisites from './fragments/_mcp-prerequisites.mdx';
 import SampleCode from './fragments/_mcp-sample-code.mdx';
 import SetUpServer from './fragments/_mcp-set-up-server.mdx';
-import TestIntegration from './fragments/_mcp-test-integration.mdx';
 
 # Enable auth for your MCP-powered apps with Logto
 
-<Introduction />
+This guide walks you through integrating Logto with your MCP server using [mcp-auth](https://mcp-auth.dev), allowing you to authenticate users and securely retrieve their identity information using the standard OpenID Connect flow.
 
-<Prerequisites />
+You'll learn how to:
+
+- Configure Logto as the authorization server for your MCP server.
+- Set up a “whoami” tool to return the current user's identity claims.
+- Test the flow with the MCP Inspector.
+
+After this tutorial, your MCP server will:
+
+- Authenticate users in your Logto tenant.
+- Return identity claims (`sub`, `username`, `name`, `email`, etc.) for the "whoami" tool invocation.
+
+Once the integration is complete, you can replace the MCP Inspector with your own MCP client, such as a web app, to access the tools and resources exposed by your MCP server.
+
+<Prerequisites clientDescription="We'll use the MCP Inspector as the client in this guide." />
 
 ## Set up app in Logto
 
@@ -25,6 +36,44 @@ import TestIntegration from './fragments/_mcp-test-integration.mdx';
 
 <SetUpServer />
 
-<TestIntegration />
+## Test the integration
+
+1. Start the MCP server
+2. Start the MCP Inspector.
+
+   Due to the limit of the current MCP Inspector implementation, we need to use the forked version from mcp-auth:
+
+   ```bash
+   git clone https://github.com/mcp-auth/inspector.git
+   cd inspector
+   npm install
+   npm run dev
+   ```
+
+   Then, open the URL shown in the terminal.
+
+3. In the MCP Inspector:
+
+   - **Transport Type**: `SSE`
+   - **URL**: `http://localhost:3001/sse`
+   - **OAuth Client ID**: Paste your Logto App ID
+   - **Auth Params**: `{"scope": "openid profile email"}`
+   - **Redirect URI**: This URL should be auto-populated. Copy it.
+
+4. Find the application you created earlier in the Logto Console, open the details page, and paste the redirect URI into the **Settings** / **Redirect URIs** section. Save the changes.
+5. Back in the MCP Inspector, click **Connect**. This should redirect you to the Logto sign-in experience.
+
+After completing sign-in, you should be redirected back to the MCP Inspector. Go to **Tools** -> **List Tools** -> **whoami** -> **Run Tool**.
+
+You should see user claims, such as:
+
+```json
+{
+  "sub": "user_XXXX",
+  "username": "alice",
+  "name": "Alice Smith",
+  "email": "alice@example.com"
+}
+```
 
 <SampleCode />