temp

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/ai/fragments/_mcp-introduction.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-prerequisites.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-sample-code.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 />

docs/use-cases/ai/fragments/_mcp-test-integration.mdx

@@ -3,35 +3,69 @@ sidebar_position: 2
 sidebar_label: Enable AI agent and third-party app access to MCP server
 ---
 
-import Introduction from './fragments/_mcp-introduction.mdx';
+import QuickStartsReference from '../../quick-starts/third-party/oidc/_quick-starts-reference.md';
+
+import thirdPartyAppPermissions from './assets/third-party-app-permissions.png';
 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 AI agent and third-party app access to your MCP server
 
 :::note
-The main difference between this guide and the previous one is that this guide will treat the MCP Inspector as a third-party app in Logto. If you want to integrate your MCP server with your own app, please refer to the [Enable auth for your MCP-powered apps with Logto](./mcp-server-add-auth) guide.
+If you want to integrate your MCP server with your own app, please refer to the [Enable auth for your MCP-powered apps with Logto](./mcp-server-add-auth) guide.
 :::
 
-<Introduction isThirdPartyApp />
+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.
+
+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 an AI agent or third-party app.
+
+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.
+
+<Prerequisites clientDescription="The AI agent or third-party app will be used as the client in this guide." />
+
+## Set up AI agent or third-party app
 
-<Prerequisites />
+To enable the AI agent or third-party app (client) to access your MCP server, you need to set up the following:
+
+1. The client should be able to make MCP requests to invoke the tools exposed by the MCP server.
+2. The client should be able to handle the 401 Unauthorized response. See [Authorization Flow Steps](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#2-5-authorization-flow-steps) for more details.
 
 ## Set up app in Logto
 
+### Self-registered flow
+
+### Manually create a third-party app
+
+You can manually create a third-party app in Logto Console for testing purposes or ad-hoc integrations. This is useful when you want to quickly test the integration without implementing a full client-registration flow.
+
 1. Sign in to your Logto Console.
 2. Go <CloudLink to="/applications">**Applications**</CloudLink> → **Create application** → **Third-party app** -> **OIDC**.
 3. Fill in the app name and other required fields, then click **Create application**.
 4. Click **Permissions** tab, in the **User** section, click "Add".
 5. In the opened dialog -> **User data** -> select **`profile`**, **`email`** permissions, then click **Save**.
-6. Go to **Settings** tab, save and copy the **App ID** and **Issuer endpoint**.
+6. In the third-party app, configure scopes to request `openid profile email` permissions.
+7. Configure the **redirect URI** of your third-party application accordingly. Remember to update the redirect URI in Logto as well.
+
+<img
+  src={thirdPartyAppPermissions}
+  alt="Third-party app permissions"
+  style={{ maxWidth: '800px', width: '100%' }}
+/>
+
+---
 
-![Third-party app permissions](./assets/third-party-app-permissions.png)
+<QuickStartsReference />
 
 <SetUpServer />
 
-<TestIntegration isThirdPartyApp />
+## Test the integration
 
 <SampleCode />

docs/use-cases/ai/mcp-server-add-auth.mdx

@@ -132,14 +132,14 @@ export const createCommonThemeConfig = (site: Site) => {
           label: 'Integrations',
         },
         {
-          to: buildUrl('/use-cases', 'main'),
+          to: new URL('https://openapi.logto.io', mainSiteUrl).href,
           position: 'left',
-          label: 'Use cases',
+          label: 'API',
         },
         {
-          to: new URL('https://openapi.logto.io', mainSiteUrl).href,
+          to: buildUrl('/use-cases', 'main'),
           position: 'left',
-          label: 'API',
+          label: 'Use cases',
         },
       ],
     },