docs: add provider guides and simplify tutorial

docs/provider-guides/README.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_label: Overview
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Provider Guides
+
+This section contains configuration guides for various OAuth 2.0 and OpenID Connect providers.
+
+<DocCardList />
+
+:::info Want to contribute?
+If your provider is not listed, feel free to create a pull request in [mcp-auth/docs](https://github.com/mcp-auth/docs).
+:::

docs/provider-guides/generic.mdx

@@ -0,0 +1,104 @@
+---
+sidebar_position: 100
+sidebar_label: Generic OAuth 2.0 / OIDC
+---
+
+# Generic OAuth 2.0 / OIDC
+
+This guide covers general configuration steps for OAuth 2.0 and OpenID Connect providers. Since OIDC is built on top of OAuth 2.0, both follow similar steps.
+
+:::tip
+Check our [Provider List](/provider-list) to see if your specific provider has been tested with MCP Auth.
+:::
+
+## Get issuer URL {#get-issuer-url}
+
+The issuer URL (also called authorization server URL or base URL) is required for MCP Auth configuration. To find it:
+
+1. Check your provider's documentation for the authorization server URL
+2. Some providers expose this at `https://{your-domain}/.well-known/oauth-authorization-server`
+3. For OIDC providers, try `https://{your-domain}/.well-known/openid-configuration`
+4. Look in your provider's admin console under OAuth/API settings
+
+## Configure scopes {#configure-scopes}
+
+You'll need to define scopes in your authorization server that represent the permissions your MCP server needs:
+
+1. **Define scopes** in your authorization server, e.g.:
+   - `create:todos`
+   - `read:todos`
+   - `delete:todos`
+
+2. **Assign scopes to users** using your provider's interface
+   - Some providers support role-based management
+   - Others use direct scope assignments
+
+Check your provider's documentation for specific instructions on scope management.
+
+## Retrieving user identity {#retrieving-user-identity}
+
+### OIDC providers
+
+Most OpenID Connect providers support the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information.
+
+Check your provider's documentation to see if it supports this endpoint. If your provider supports [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), you can also check if the `userinfo_endpoint` is included in the discovery document (response from the `.well-known/openid-configuration` endpoint).
+
+To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. Check your provider's documentation to see the mapping of scopes to user identity claims.
+
+### OAuth 2.0 providers
+
+While OAuth 2.0 does not define a standard way to retrieve user identity information, many providers implement their own endpoints to do so. Check your provider's documentation to see how to retrieve user identity information using an access token and what parameters are required to fetch such access token when invoking the authorization flow.
+
+## Token request parameters {#token-request-parameters}
+
+Different authorization servers use various approaches for specifying the target resource:
+
+### Resource indicator based
+
+Uses the `resource` parameter ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)):
+
+```json
+{
+  "resource": "http://localhost:3001/",
+  "scope": "create:todos read:todos"
+}
+```
+
+### Audience based
+
+Uses the `audience` parameter:
+
+```json
+{
+  "audience": "todo-api",
+  "scope": "create:todos read:todos"
+}
+```
+
+### Pure scope based
+
+Relies solely on scopes (traditional OAuth 2.0):
+
+```json
+{
+  "scope": "todo-api:create todo-api:read openid profile"
+}
+```
+
+Check your provider's documentation for supported parameters.
+
+## Register MCP client {#register-mcp-client}
+
+If your provider supports [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) or [OAuth Client ID Metadata Document](https://www.ietf.org/archive/id/draft-parecki-oauth-client-id-metadata-document-00.html), you may skip manual registration. Otherwise:
+
+1. Sign in to your provider's console
+2. Navigate to "Applications" or "Clients" section
+3. Create a new application/client
+4. Select "Native App" or "Public client" if required
+5. Configure the redirect URIs. For VS Code:
+   ```
+   http://127.0.0.1
+   https://vscode.dev/redirect
+   ```
+6. Configure the required scopes/permissions
+7. Copy the "Client ID" or "Application ID" for use in your MCP client

docs/provider-guides/keycloak.mdx

@@ -0,0 +1,87 @@
+---
+sidebar_position: 2
+sidebar_label: Keycloak
+---
+
+# Keycloak
+
+[Keycloak](https://www.keycloak.org) is an open-source identity and access management solution that supports multiple protocols, including OpenID Connect (OIDC). As an OIDC provider, it implements the standard userinfo endpoint to retrieve user identity information.
+
+## Prerequisites {#prerequisites}
+
+:::note
+Although Keycloak can be installed in [various ways](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), for this guide, we'll use Docker for a quick and straightforward setup.
+:::
+
+Run a Keycloak instance using Docker following the [official documentation](https://www.keycloak.org/getting-started/getting-started-docker):
+
+```bash
+docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev
+```
+
+## Get issuer URL {#get-issuer-url}
+
+1. Access the Keycloak Admin Console (http://localhost:8080/admin) and log in with these credentials:
+   - Username: `admin`
+   - Password: `admin`
+2. Navigate to "Realm settings" in the left menu
+3. Click "Endpoints" then "OpenID Endpoint Configuration"
+4. The `issuer` field in the JSON document will contain your issuer URL
+
+For a realm named `mcp-realm`, the issuer URL should look like:
+
+```
+http://localhost:8080/realms/mcp-realm
+```
+
+## Create a realm and test user {#create-realm-and-user}
+
+1. Create a new Realm:
+   - Click "Create Realm" in the top-left corner
+   - Enter a name in the "Realm name" field (e.g., `mcp-realm`)
+   - Click "Create"
+
+2. Create a test user:
+   - Click "Users" in the left menu
+   - Click "Create new user"
+   - Fill in the user details:
+     - Username: e.g., `testuser`
+     - First name and Last name can be any values
+   - Click "Create"
+   - In the "Credentials" tab, set a password and uncheck "Temporary"
+
+## Configure scopes {#configure-scopes}
+
+If your MCP server requires custom scopes (e.g., for RBAC):
+
+1. In the Keycloak Admin Console, navigate to "Client scopes"
+2. Click "Create client scope"
+3. Define the scope name (e.g., `create:todos`, `read:todos`, `delete:todos`)
+4. Assign these scopes to clients or roles as needed
+
+## Retrieving user identity {#retrieving-user-identity}
+
+As an OIDC provider, Keycloak exposes a standard [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) that allows applications to retrieve claims about the authenticated user.
+
+To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`.
+
+## Register MCP client {#register-mcp-client}
+
+While Keycloak supports dynamic client registration, its client registration endpoint does not support CORS, preventing most MCP clients from registering directly. Therefore, you'll need to manually register your client.
+
+### Register a client for VS Code
+
+1. In the Keycloak Admin Console, click "Clients" in the left menu
+2. Click "Create client"
+3. Fill in the client details:
+   - Client type: Select "OpenID Connect"
+   - Client ID: Enter a name (e.g., `vscode`)
+   - Click "Next"
+4. On the "Capability config" page:
+   - Ensure "Standard flow" is enabled
+   - Click "Next"
+5. On the "Login settings" page:
+   - Add `http://127.0.0.1/*` to "Valid redirect URIs"
+   - Add `https://vscode.dev/redirect` to "Valid redirect URIs"
+   - Click "Save"
+6. Copy the "Client ID" for later use

docs/provider-guides/logto.mdx

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+sidebar_label: Logto
+---
+
+# Logto
+
+[Logto](https://logto.io) is an open-source identity platform that provides OpenID Connect authentication with built-in RBAC support through API resources and roles.
+
+## Get issuer URL {#get-issuer-url}
+
+You can find the issuer URL on your application details page within Logto Console, under the "Endpoints & Credentials / Issuer endpoint" section. It should look like:
+
+```
+https://my-project.logto.app/oidc
+```
+
+## Create API resource and scopes {#create-api-resource-and-scopes}
+
+1. Sign in to [Logto Console](https://cloud.logto.io) (or your self-hosted Logto Console)
+2. Go to "API Resources"
+3. Create a new API resource:
+   - **Name**: e.g., "Todo Manager"
+   - **Resource indicator**: Your MCP server URL, e.g., `http://localhost:3001/`
+     - The resource indicator must match your MCP server's URL.
+4. Add the scopes your MCP server needs, e.g.:
+   - `create:todos`: "Create new todo items"
+   - `read:todos`: "Read all todo items"
+   - `delete:todos`: "Delete any todo item"
+
+:::note[Trailing slash in resource indicator]
+Always include a trailing slash (`/`) in the resource indicator. Due to a current bug in the MCP official SDK, clients using the SDK will automatically append a trailing slash to resource identifiers when initiating auth requests.
+:::
+
+## Create roles {#create-roles}
+
+Roles make it easier to manage permissions for groups of users:
+
+1. Go to "Roles"
+2. Create roles with appropriate scopes, e.g.:
+   - **Admin**: Assign all scopes
+   - **User**: Assign limited scopes
+3. (Optional) Set a default role for new users in the role's "General" tab.
+
+## Assign permissions to users {#assign-permissions-to-users}
+
+1. Go to "User management"
+2. Select a user
+3. In the "Roles" tab, assign the appropriate roles
+
+:::tip Programmatic Role Management
+You can use Logto's [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) to programmatically manage user roles.
+:::
+
+## Retrieving user identity {#retrieving-user-identity}
+
+Logto is an OpenID Connect provider that supports the standard [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information.
+
+To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`.
+
+## Register MCP client {#register-mcp-client}
+
+Since Logto does not support Dynamic Client Registration yet, you need to manually register your MCP client in Logto Console.
+
+### Third-party vs. first-party applications
+
+Before creating the application, you need to understand the difference:
+
+- **Third-party application**: Use this when the MCP client is developed by someone else (e.g., VS Code, Cursor, or other community tools). These clients need to access your users' data, but are not under your control. Users will see a consent screen asking them to authorize the MCP client to access their information.
+- **First-party application**: Use this when you are building your own MCP client (e.g., an AI assistant embedded in your own product). In this case, both the MCP client and MCP server are managed by you, and the users are your own users. No consent screen is needed.
+
+### Application type
+
+Choose the application type based on how the MCP client runs:
+
+| MCP Client | Application Type |
+| ---------- | ---------------- |
+| VS Code, Cursor (desktop apps) | Native App |
+| MCP Inspector (browser-based) | Single Page App (SPA) |
+
+### Register a third-party app
+
+Take VS Code as an example:
+
+1. Navigate to **Applications > Third-party apps** and click "Create application".
+2. Select **Native App** as the application type (since VS Code is a desktop application).
+3. Fill in the application name (e.g., "VS Code") and description.
+4. Set the **Redirect URIs** (check the MCP client's documentation for the required URIs):
+   ```
+   http://127.0.0.1
+   https://vscode.dev/redirect
+   ```
+5. Click "Save changes".
+6. Go to the app's **Permissions** tab, under **User** section, add the required permissions from your API resource (e.g., `create:todos`, `read:todos`, `delete:todos`).
+7. Copy the "App ID" value for use in VS Code.
+
+### Register a first-party app
+
+If you are building your own MCP client:
+
+1. Navigate to **Applications** and click "Create application".
+2. Select the appropriate application type based on your client (Native App, SPA, etc.).
+3. Complete the setup following the in-app guide.
+4. Copy the "App ID" (and "App Secret" if applicable) for use in your MCP client.