docs: update AI use cases for MCP SDK v2 and mcp-auth 1.0 (#1492)

Author: xiaoyijun

docs/use-cases/ai/README.mdx

@@ -5,7 +5,10 @@ description: Explore how Logto can help you build secure, AI-enabled experiences
 ---
 
 import Catalog from './fragments/_catalog.mdx';
+import ExploreAiSolutions from './fragments/_explore-ai-solutions.mdx';
 
 # AI integration use cases with Logto
 
+<ExploreAiSolutions />
+
 <Catalog />

docs/use-cases/ai/connect-your-agent-to-third-party-apis.mdx

@@ -3,8 +3,12 @@ sidebar_position: 4
 sidebar_label: Connect your agent to third-party APIs
 ---
 
+import ExploreAiSolutions from './fragments/_explore-ai-solutions.mdx';
+
 # Connect your AI agent to third-party APIs
 
+<ExploreAiSolutions />
+
 This guide walks you through enabling your AI agent to access third-party APIs (e.g., Google Calendar, GitHub, etc.) on behalf of users. By leveraging Logto's social connectors and Secret Vault, you can securely store and manage access tokens, allowing your agent to perform automated tasks without repeatedly asking users to re-authenticate.
 
 You'll learn how to:

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

@@ -4,9 +4,12 @@ sidebar_label: Enable third-party AI agent access to app
 ---
 
 import ConfigureThirdPartyAiAgent from './fragments/_configure-third-party-ai-agent.mdx';
+import ExploreAiSolutions from './fragments/_explore-ai-solutions.mdx';
 
 # Enable third-party AI agent access to your app
 
+<ExploreAiSolutions />
+
 This guide walks you through integrating Logto with your service and enabling AI agents to access it.
 
 You'll learn how to:

docs/use-cases/ai/fragments/_configure-third-party-ai-agent.mdx

@@ -59,13 +59,17 @@ You can manually create a third-party app in Logto Console for testing purposes
 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. In the third-party app, configure scopes to request `openid profile email` permissions (scopes).
+4. Click the **Permissions** tab to grant [permissions](/integrate-logto/third-party-applications/permission-management) to the app:
 
-   **Note**: `openid` is required for OIDC, and `profile` and `email` are the permissions you added in the previous step.
+   - **User** section: user data permissions such as **`profile`** and **`email`**, for basic identity claims.
+   - **API resource** section: permissions (scopes) of the [API resources](/authorization/global-api-resources) you've defined in Logto, e.g., the API resource that represents your {props.serviceName ?? 'service'}.
+   - **Organization** section: organization permissions, if you use Logto organizations.
 
-7. Configure the **redirect URI** of your third-party application accordingly. Remember to update the redirect URI in Logto as well.
+5. In the third-party app, configure scopes to request the permissions you granted, e.g., `openid profile email` plus the API resource scopes.
+
+   **Note**: `openid` is required for OIDC. To receive an access token bound to an API resource, the app must also include the `resource` parameter in the authorization request. MCP clients that follow the latest MCP specification do this automatically based on the protected resource metadata.
+
+6. Configure the **redirect URI** of your third-party application accordingly. Remember to update the redirect URI in Logto as well.
 
 <img
   src="/img/assets/third-party-app-permissions.png"

docs/use-cases/ai/fragments/_explore-ai-solutions.mdx

@@ -0,0 +1,3 @@
+:::tip
+Explore [Logto's AI solutions](https://logto.io/ai): authentication and authorization for MCP servers, AI agents, and apps.
+:::

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

@@ -3,38 +3,35 @@ import Mermaid from '@theme/Mermaid';
 ## Prerequisites \{#prerequisites}
 
 - A [Logto Cloud](https://cloud.logto.io) (or self-hosted) tenant
-- Node.js or Python environment
+- Node.js >= 20 environment
 
 ### Understanding the architecture \{#understanding-the-architecture}
 
-- **MCP server**: The server that exposes tools and resources to MCP clients.
-- **MCP client**: A client used to initiate the authentication flow and test the integration. {<b>{props.isThirdParty ? 'The third-party AI agent will be used as the client in this guide.' : "We'll use the MCP Inspector as the client in this guide."}</b>}
-- **Logto**: Serves as the OpenID Connect provider (authorization server) and manages user identities.
+- **MCP server**: The server that exposes tools and resources to MCP clients. Following the [latest MCP specification](https://modelcontextprotocol.io/specification/latest/basic/authorization), it acts as an OAuth 2.0 resource server that validates access tokens issued by Logto.
+- **MCP client**: A client used to initiate the authentication flow and test the integration. {<b>{props.isThirdParty ? 'The third-party AI agent will be used as the client in this guide.' : "We'll use VS Code (with built-in MCP support) as the client in this guide."}</b>}
+- **Logto**: Serves as the OpenID Connect provider (authorization server), manages user identities, and issues audience-bound JWT access tokens for your MCP server.
 
 A non-normative sequence diagram illustrates the overall flow of the process:
 
 <Mermaid value={`sequenceDiagram
-    participant Client as MCP Client<br/>${props.isThirdParty ? '(third-party AI agent)' : '(MCP Inspector)'}
-    participant Server as MCP Server
-    participant Logto
-
-    Server->>Logto: Request OpenID Connect configuration
-    Logto->>Server: Return configuration
-    Note over Server: Cache the configuration
-    Client->>Server: Request access to a tool
-    Server->>Client: Not authenticated (401 Unauthorized)
-    Client->>Server: Request OAuth 2.0 Authorization Server Metadata
-    Note over Server: In this context, “OpenID Connect configuration” and<br/>“OAuth 2.0 Authorization Server Metadata”<br/>refer to the same thing.
-    Server->>Client: Return OpenID Connect configuration retrieved from Logto
+    participant Client as MCP Client<br/>${props.isThirdParty ? '(third-party AI agent)' : '(VS Code)'}
+    participant Server as MCP Server<br/>(resource server)
+    participant Logto as Logto<br/>(authorization server)
+
+    Client->>Server: MCP request (no token)
+    Server->>Client: 401 Unauthorized (WWW-Authenticate)
+    Client->>Server: Fetch protected resource metadata<br/>(/.well-known/oauth-protected-resource)
+    Server->>Client: Return metadata with authorization server info
+    Client->>Logto: Fetch authorization server metadata
+    Logto->>Client: Return OpenID Connect configuration
     Client->>Logto: Redirect to Logto for authentication
     Logto->>Logto: User authenticates
-    ${props.isThirdParty ? 'Logto->>Logto: User authorizes (consents) scopes<br/>to the third-party app' : ''}
-    Logto->>Client: Redirect back to MCP server with authorization code
-    Client->>Logto: Request access token using authorization code
-    Logto->>Client: Return access token
-    Client->>Server: Request tool with access token
-    Server->>Logto: Request user info using access token
-    Logto->>Server: Return user info
+    ${props.isThirdParty ? 'Logto->>Logto: User authorizes (consents) scopes<br/>to the third-party AI agent' : ''}
+    Logto->>Client: Redirect back with authorization code
+    Client->>Logto: Exchange code for access token<br/>(with the resource parameter)
+    Logto->>Client: Return access token (JWT, audience-bound)
+    Client->>Server: MCP request with access token
+    Server->>Server: Verify access token against Logto's JWKS<br/>(signature, issuer, audience, expiration)
     Server->>Client: Return tool response`}
 
 />

docs/use-cases/ai/fragments/_mcp-sample-code.mdx

@@ -1,15 +1,7 @@
-import TabItem from '@theme/TabItem';
-import Tabs from '@theme/Tabs';
+:::info[Sample code]
+The complete, runnable sample code for this guide can be found in the [mcp-auth/js](https://github.com/mcp-auth/js/tree/master/packages/sample-servers) repository:
 
-<Tabs groupId="sdk">
-<TabItem value="python" label="Python">
+- [`whoami-express`](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/whoami-express): the "whoami" server in this guide, on Node.js with Express.
+- [`whoami`](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/whoami): the same server built fetch-native (web-standard `Request` / `Response` with [Hono](https://hono.dev)), deployable to Cloudflare Workers.
 
-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 MCP server code can be found in the [mcp-auth/js](https://github.com/mcp-auth/js) repository.
-
-</TabItem>
-</Tabs>
+:::