ユーザーに代わってファーストパーティAPIを呼び出す

Auth0はOn-Behalf-Of (OBO) token exchange (RFC 8693) を実装しています。これにより、MCPサーバーはダウンストリームAPIを呼び出す際に、ユーザーのアイデンティティと権限を保持できます。OBO token exchangeのフローにおいて、MCPサーバーは2つの役割を担います。クライアントからリクエストを受け取るときはリソースサーバーとして、ユーザーに代わってダウンストリームAPIを呼び出すときはクライアントとして機能します。ユーザーに代わってファーストパーティAPIを呼び出すには、MCPサーバーがMCPクライアントから受け取ったAuth0アクセストークンを、オーディエンスの異なる新しいアクセストークンと交換する必要があります。元のトークンのオーディエンスはMCPサーバーですが、新しいトークンのオーディエンスはダウンストリームAPIです。

このクイックスタートを終えると、次のものが完成します。

OBO token exchangeを使用し、認証済みユーザーに代わって保護されたAPIを呼び出すMCPサーバー
@auth0/auth0-api-jsライブラリ (JavaScript) またはauth0-api-pythonライブラリ (Python) によるトークンの検証と交換
クライアントからMCPサーバー、そしてダウンストリームAPIに至るまで、エンドツーエンドのOBO token exchangeフローを実際に確認できる動作例

Prerequisites

1. Create or log in to your Auth0 account

To continue with this quickstart, you need to have an Auth0 account.

2. Enable the Resource Parameter Compatibility Profile and Include Issuer in Authorization Responses

To use the resource parameter in your access tokens and the iss claim to identify your authorization server, you need to enable two toggles in the Auth0 Dashboard:

Navigate to Settings on the left sidebar.
Select Advanced in the top right corner.
Scroll down to the Settings section and enable the following toggles:
- Resource Parameter Compatibility Profile: Enables support for the resource parameter in authorization requests, allowing access tokens to be scoped to a specific API.
- Include Issuer in Authorization Responses: Includes the iss parameter identifying the authorization server in authorization responses, helping clients defend against mix-up attacks.

3. Install the Auth0 CLI

This guide uses Auth0 CLI to configure an Auth0 tenant for secure MCP tool access.

Follow the Auth0 CLI installation instructions.
Log in to your account with the Auth0 CLI:

auth0 login --scopes "read:client_grants,create:client_grants,delete:client_grants,read:clients,create:clients,update:clients,read:resource_servers,create:resource_servers,update:resource_servers,read:roles,create:roles,update:roles,update:tenant_settings,read:connections,update:connections"

Confirm you are in the correct tenant by double-checking the tenant domain in the terminal, or run the command below:

auth0 tenants list

If more than one tenant is configured, the default tenant will be indicated by an arrow.

4. Install jq

To simplify the process of interacting with the Auth0 CLI, we recommend installing jq. This will allow you to easily parse JSON responses from the CLI.

macOS
Linux
Windows

brew install jq

sudo apt-get install jq

choco install jq

テナント設定を構成する

1. Promote the connection to a domain-level connection

To allow third-party clients like MCP Inspector to use a connection such as a username-and-password database or a social connection, you need to promote the connection to a domain-level connection. Learn more about configuring third-party applications.

List Your Connection

List your connections to get their IDs

auth0 api get connections

Choose Your Connections

From the list, identify which connections you want to use for the MCP server and copy the ID.

For the username-and-password database, look for the connection with the strategy auth0.
For the Google social connection, look for the connection with the strategy google-oauth2.

Upgrade the Connection to Domain-Level

For each of those specific connection IDs, run the following command to mark it as a domain-level connection. Replace YOUR_CONNECTION_ID with the actual ID (e.g., con_XXXXXXXXXXXXXXXX).

auth0 api patch connections/YOUR_CONNECTION_ID --data '{"is_domain_connection": true}'

2. Create roles

The sample application in this quickstart is prepared to show different tools depending on the role of a given user. For example, a Tool Administrator will have access to different tools than a Tool User.Let’s create roles that allow you to control which users can access which tools.For each role you need (e.g., “Tool Administrator”, “Tool User”), run the create command as below.

# Example for an admin role
auth0 roles create --name "Tool Administrator" --description "Grants access to all MCP tools"

# Example for a basic user role
auth0 roles create --name "Tool User" --description "Grants access to basic MCP tools"

Save the IDs from the output (they start with rol_), as you’ll need them in a later step to assign permissions and users to these roles.

3. Assign roles to users

Find users and assign them to the roles. You can search by their email address:

auth0 users search --query "email:\"example@google.com\""

Copy the user ID (USERID) from the last command’s output, then assign the role to the user:

auth0 users roles assign "USER_ID_HERE" --roles "YOUR_ROLE_ID_HERE"

Auth0アプリケーションとAPIをセットアップする

MCPサーバーは2つの役割を担うため、Auth0で2つの設定が必要です。

リソースサーバーとして：MCPクライアントから呼び出されるAPI
クライアントとして：トークンを交換してダウンストリームAPIを呼び出すアプリケーション

それでは、両方の設定を行いましょう。

MCPサーバーを表すAPIを作成する

An MCP server is treated just like any other API in your Auth0 tenant, which means you can use the same access control, scoping, and authorization features. The API (also known as a Resource Server) represents your protected MCP Server. Run the following command to create an API in Auth0:

auth0 api post resource-servers --data '{
  "identifier": "http://localhost:3001/",
  "name": "MCP Tools API",
  "signing_alg": "RS256",
  "token_dialect": "rfc9068_profile_authz",
  "enforce_policies": true,
  "scopes": [
    {"value": "tool:whoami", "description": "Access the WhoAmI tool"},
    {"value": "tool:greet", "description": "Access the Greeting tool"}
  ]
}'

Note that rfc9068_profile_authz is used as the token dialect to include the permissions claim in the access token, which can be useful for the API to check user permissions without making additional calls. For more details on protecting APIs with Auth0, check our quickstarts.

Assign permissions to roles

After creating the API and roles, assign the API permissions to the roles.

# Example for admin role (all scopes)
auth0 roles permissions add YOUR_ADMIN_ROLE_ID --api-id "http://localhost:3001/" --permissions "tool:whoami,tool:greet"

# Example for user role (one scope)
auth0 roles permissions add YOUR_USER_ROLE_ID --api-id "http://localhost:3001/" --permissions "tool:whoami"

Replace YOUR_ADMIN_ROLE_ID and YOUR_USER_ROLE_ID with the role IDs you saved when creating the roles.

MCPサーバー用のアプリケーションを作成する

MCPサーバーがOBO token exchangeのクライアントとして動作できるよう、アプリケーションを作成します。このアプリケーションは、次の要件を満たす必要があります。

MCPサーバーのAPIと同じ識別子 (resource_server_identifier) を持つこと
app_type: resource_serverを使用してMCPサーバーにリンクすること
token_exchange設定でOBO token exchangeを有効にすること

次のコマンドを実行すると、MCPサーバーにリンクされ、OBO token exchangeが有効になったアプリケーションが作成されます。

auth0 api post clients --data '{
  "name": "MCP Server Client",
  "app_type": "resource_server",
  "oidc_conformant": true,
  "resource_server_identifier": "http://localhost:3001/",
  "token_exchange": {
    "allow_any_profile_of_type": ["on_behalf_of_token_exchange"]
  }
}' | jq -c '{client_id, client_secret}' > auth0-app-details.json

出力に表示される client_id と client_secret を控えておいてください。MCPサーバーの環境を設定する際に必要になります。

ダウンストリームAPIを作成する

MCPサーバーがユーザーに代わって呼び出す、保護されたAPIを作成します。このAPIは、ビジネスロジックを担うAPI (カレンダーAPIやドキュメントAPIなど) に相当します。次のコマンドを実行すると、以下の設定でAPIが作成されます。

クライアントグラント：このAPIへのユーザー委任アクセスとクライアントアクセスをMCPサーバーに付与します
スコープの適用：特定の権限 (read:private) を必須とします
ファーストパーティ扱い：自社のアプリケーションではユーザーの同意をスキップします

auth0 api post resource-servers --data '{
  "identifier": "http://localhost:8787/",
  "name": "Protected Downstream API",
  "signing_alg": "RS256",
  "enforce_policies": true,
  "scopes": [
    {"value": "read:private", "description": "Private scope"}
  ],
  "subject_type_authorization": {
    "user": {
        "policy": "require_client_grant"
    },
    "client": {
        "policy": "require_client_grant"
    }
  },
  "skip_consent_for_verifiable_first_party_clients": false
}'

出力に表示される API 識別子 (オーディエンス) を控えておいてください。この値は後で環境変数 API_AUTH0_AUDIENCE に設定します。

Assign permissions to roles

After creating the downstream API and roles, assign the read:private permission to the roles.

# Example for admin role
auth0 roles permissions add YOUR_ADMIN_ROLE_ID --api-id "http://localhost:8787/" --permissions "read:private"

# Example for user role
auth0 roles permissions add YOUR_USER_ROLE_ID --api-id "http://localhost:8787/" --permissions "read:private"

Replace YOUR_ADMIN_ROLE_ID and YOUR_USER_ROLE_ID with the role IDs you saved when creating the roles.

サンプルアプリ

Javascript
Python

サンプルアプリを使用する（推奨）
GitHubリポジトリをクローンする

まず、このクイックスタート用のサンプルアプリをダウンロードします。サンプルには、Auth0と統合されたFastMCP MCPサーバーと、 Fastifyで構築された保護されたAPIが含まれています。ダウンロードしたらファイルを展開し、お好みのIDEでプロジェクトを開きます。

リポジトリをクローンし、サンプルアプリのフォルダーに移動します。このフォルダーには、Auth0と統合されたFastMCP MCPサーバーと、 Fastifyで構築された保護されたAPIが含まれています。

git clone https://github.com/auth0-samples/auth0-ai-samples.git
cd auth0-ai-samples/auth-for-mcp/fastmcp-mcp-on-behalf-of-tokenexchange-js

クローンしたら、お好みのIDEでプロジェクトを開きます。

このサンプルアプリでは、greetツールを使ってOBOフロー全体を実演します。このツールは次の処理を行います。

MCPクライアントから認証済みのリクエストを受け取る
トークンを交換して、ダウンストリームAPIへのアクセス権を取得する
ユーザーに代わって保護されたAPIを呼び出す
結果を返す

パッケージをインストールする

npmがインストールされていることを確認してください。次に、fastmcp-mcp-on-behalf-of-tokenexchange-jsディレクトリで必要なパッケージをインストールします。

npm install

環境ファイルを作成する

From the root of your sample app directory, run the following command to create a new .env file populated with all the required environment variables:

CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) \
&& CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) \
&& DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') \
&& touch .env \
&& echo "AUTH0_DOMAIN=${DOMAIN}" > .env \
&& echo "AUTH0_AUDIENCE=http://localhost:3001/" >> .env \
&& echo "PORT=3001" >> .env \
&& echo "MCP_SERVER_URL=http://localhost:3001/" >> .env \
&& echo "MCP_AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env \
&& echo "MCP_AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env \
&& echo "MCP_AUTH0_EXCHANGE_SCOPE=read:private" >> .env \
&& echo "API_AUTH0_AUDIENCE=http://localhost:8787/" >> .env \
&& echo "API_BASE_URL=http://localhost:8787" >> .env \
&& rm auth0-app-details.json \
&& echo ".env file created with your Auth0 details:" \
&& cat .env

MCPサーバーとAPIを実行する

Run this command to start your server:

npm run start

And in a separate window run this command to start the API:

npm run start:api

アクセストークンを交換する

To call your APIs on a user’s behalf, the MCP server uses the OBO token exchange to exchange the Auth0 access token it received from the MCP client (with the audience set to the MCP server itself) for a new Auth0 access token with the audience set to your API.

Token exchange implementation

The MCP server exchanges tokens in two steps:

1. Wrapper function: `bearerForUpstream()`

This function safely handles the token exchange process and error handling:

async function bearerForUpstream(accessToken: string) {
  if (!accessToken) return { token: null, scopes: null };

  try {
    const result = await exchangeTokenOnBehalfOf(accessToken);
    return {
      token: result.accessToken,
      scopes: result.scope,
    }
  } catch (err) {
    console.error('Error during token exchange:', err);
    throw err;
  }
}

bearerForUpstream() calls exchangeTokenOnBehalfOf() and, upon a successful exchange, returns the new accessToken and its associated scope. If the exchange fails, it logs the error and re-throws it to be handled upstream.

2. Exchange function: `exchangeTokenOnBehalfOf()`

This function, located in src/auth0.ts, calls Auth0’s OBO token exchange endpoint using the SDK.First, initialize the ApiClient with the credentials of the MCP server application:

const apiClient = new ApiClient({
  domain: AUTH0_DOMAIN,
  audience: AUTH0_AUDIENCE,
  clientId: MCP_AUTH0_CLIENT_ID,
  clientSecret: MCP_AUTH0_CLIENT_SECRET,
});

Once you’ve configured the MCP server application, the exchangeTokenOnBehalfOf() function uses the client’s getTokenOnBehalfOf() method to perform the token exchange.getTokenOnBehalfOf() implements the OBO token exchange flow, which allows the MCP server to obtain a new token to call the downstream API while preserving the user’s identity. It takes in the accessToken, audience, and scope parameters.

export async function exchangeTokenOnBehalfOf(accessToken: string) {
    return await apiClient.getTokenOnBehalfOf(accessToken, {
      audience: API_AUTH0_AUDIENCE,
      ...(MCP_AUTH0_EXCHANGE_SCOPE && { scope: MCP_AUTH0_EXCHANGE_SCOPE }),
    });
}

サンプルアプリを使用する（推奨）
GitHubリポジトリをクローンする

まず、このクイックスタート用のサンプルアプリをダウンロードします。サンプルには、Auth0と統合されたFastMCP MCPサーバーと、Starletteベースの保護されたAPIが含まれています。ダウンロードしたらファイルを展開し、お好みのIDEでプロジェクトを開きます。

リポジトリをクローンし、サンプルアプリのフォルダーに移動します。このフォルダーには、Auth0と統合されたFastMCP MCPサーバーと、Starletteベースの保護されたAPIが含まれています。

git clone https://github.com/auth0-samples/auth0-ai-samples.git
cd auth0-ai-samples/auth-for-mcp/fastmcp-mcp-on-behalf-of-tokenexchange-python

クローンしたら、お好みのIDEでプロジェクトを開きます。

このサンプルアプリでは、greetツールを使ってOBOフロー全体を実演します。このツールは次の処理を行います。

MCPクライアントから認証済みのリクエストを受け取る
トークンを交換して、ダウンストリームAPIへのアクセス権を取得する
ユーザーに代わって保護されたAPIを呼び出す
結果を返す

パッケージをインストールする

poetryがインストールされていることを確認してください。次に、fastmcp-mcp-on-behalf-of-tokenexchange-pythonディレクトリで必要なパッケージをインストールします。

poetry install

環境ファイルを作成する

From the root of your sample app directory, run the following command to create a new .env file populated with all the required environment variables:

CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) \
&& CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) \
&& DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') \
&& touch .env \
&& echo "AUTH0_DOMAIN=${DOMAIN}" > .env \
&& echo "AUTH0_AUDIENCE=http://localhost:3001/" >> .env \
&& echo "PORT=3001" >> .env \
&& echo "MCP_SERVER_URL=http://localhost:3001/" >> .env \
&& echo "MCP_AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env \
&& echo "MCP_AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env \
&& echo "MCP_AUTH0_EXCHANGE_SCOPE=read:private" >> .env \
&& echo "API_AUTH0_AUDIENCE=http://localhost:8787/" >> .env \
&& echo "API_BASE_URL=http://localhost:8787" >> .env \
&& rm auth0-app-details.json \
&& echo ".env file created with your Auth0 details:" \
&& cat .env

MCPサーバーとAPIを実行する

Run this command to start your server:

poetry run python -m src.server

And in a separate window run this command to start the API:

poetry run python -m src.api.server

アクセストークンを交換する

How tools use token exchange

Here’s how the greet tool performs the token exchange and calls the upstream API:

@mcp.tool(name="greet")
@require_scopes(["tool:greet"])
async def greet(name: str, ctx: Context) -> str:
    user_name = name.strip() if name else "there"
    auth_info = ctx.request_context.request.state.auth
    user_id = auth_info.get("extra", {}).get("sub")

    logger.info(f"Greet tool invoked for user: {user_id}")

    # Exchange token and call upstream API
    exchange_result = await exchange_token_on_behalf_of(
        ctx.request_context.request.state.api_client,
        auth_info["token"]
    )

    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"{config.api_base_url}/api/private-scope",
            headers={"authorization": f"Bearer {exchange_result['token']}"}
        )
        upstream_result = response.json()

    return f"Hello, {user_name} ({user_id})!\nUpstream API Response: {json.dumps(upstream_result, indent=2)}"

The core logic: `exchange_token_on_behalf_of()`

The Python implementation uses the exchange_token_on_behalf_of() function that handles the token exchange:

async def exchange_token_on_behalf_of(api_client, access_token: str) -> dict:
    """Exchange access token for downstream API token via On-Behalf-Of Token Exchange."""
    result = await api_client.get_token_on_behalf_of(
        access_token=access_token,
        audience=config.api_auth0_audience,
        scope=config.mcp_auth0_exchange_scope or None
    )
    return {"token": result["access_token"], "scopes": result.get("scope", "")}

exchange_token_on_behalf_of() uses the get_token_on_behalf_of() method of ApiClient from the auth0-api-python SDK. It takes in the access_token, audience, and optional scope parameters, and upon a successful exchange, returns the new access token and its associated scopes.

Client configuration

The ApiClient is initialized in the Auth0Middleware (located in src/auth0/middleware.py) with the credentials of the MCP server application:

src/auth0/middleware.py

self.client = ApiClient(ApiClientOptions(
    domain=domain, # AUTH0_DOMAIN env var
    audience=audience, # AUTH0_AUDIENCE env var
    client_id=client_id, # MCP_AUTH0_CLIENT_ID env var
    client_secret=client_secret # MCP_AUTH0_CLIENT_SECRET env var
))

The configured client is then attached to the request context during middleware processing, making it available to all tools:

src/auth0/middleware.py

# In the Auth0Middleware dispatch method
request.state.api_client = self.client

Testing your MCP server

Now that your MCP server is up and running, you can test it by using tools like MCP Inspector.

Learn how to test your Auth0-powered MCP server

次のステップ

MCPサーバーの認可をセットアップするには、クイックスタート「Authorization for Your MCP Server」を実施してください。

はじめに

ガイド

サンプルアプリ

ユーザーに代わってファーストパーティAPIを呼び出す

Prerequisites

テナント設定を構成する

Auth0アプリケーションとAPIをセットアップする

MCPサーバーを表すAPIを作成する

MCPサーバー用のアプリケーションを作成する

ダウンストリームAPIを作成する

サンプルアプリ

パッケージをインストールする

環境ファイルを作成する

MCPサーバーとAPIを実行する

アクセストークンを交換する

Token exchange implementation

1. Wrapper function: `bearerForUpstream()`

2. Exchange function: `exchangeTokenOnBehalfOf()`

パッケージをインストールする

環境ファイルを作成する

MCPサーバーとAPIを実行する

アクセストークンを交換する

How tools use token exchange

The core logic: `exchange_token_on_behalf_of()`

Client configuration

Testing your MCP server

Learn how to test your Auth0-powered MCP server

次のステップ

​Prerequisites

​テナント設定を構成する

​Auth0アプリケーションとAPIをセットアップする

​MCPサーバーを表すAPIを作成する

​MCPサーバー用のアプリケーションを作成する

​ダウンストリームAPIを作成する

​サンプルアプリ

​パッケージをインストールする

​環境ファイルを作成する

​MCPサーバーとAPIを実行する

​アクセストークンを交換する

​Token exchange implementation

​1. Wrapper function: bearerForUpstream()

​2. Exchange function: exchangeTokenOnBehalfOf()

​パッケージをインストールする

​環境ファイルを作成する

​MCPサーバーとAPIを実行する

​アクセストークンを交換する

​How tools use token exchange

​The core logic: exchange_token_on_behalf_of()

​Client configuration

​Testing your MCP server

Learn how to test your Auth0-powered MCP server

​次のステップ

Prerequisites

テナント設定を構成する

Auth0アプリケーションとAPIをセットアップする

MCPサーバーを表すAPIを作成する

MCPサーバー用のアプリケーションを作成する

ダウンストリームAPIを作成する

サンプルアプリ

パッケージをインストールする

環境ファイルを作成する

MCPサーバーとAPIを実行する

アクセストークンを交換する

Token exchange implementation

1. Wrapper function: `bearerForUpstream()`

2. Exchange function: `exchangeTokenOnBehalfOf()`

パッケージをインストールする

環境ファイルを作成する

MCPサーバーとAPIを実行する

アクセストークンを交換する

How tools use token exchange

The core logic: `exchange_token_on_behalf_of()`

Client configuration

Testing your MCP server

次のステップ