✨

x402 ハンズオン手順書（MCP × Express × Base Sepolia）非Docker version

takupeso

2025/10/09に公開

0. 前提

👉 ハンズオン概要

このハンズオンでは、MCP（Model Context Protocol） を通じて天気情報 API を呼び出す際、x402 を利用して「暗号通貨での支払い」を行う仕組みを体験します。
無料 API を暗号通貨決済によって有料化するプロセスを、実際に手を動かしながら学びます。

Dockerを利用する方はこちらの手順書を参照ください。

🔁 ハンズオンの流れ

開発環境セットアップ: ハンズオンに必要なツール（Node.js、pnpm、git、AI Agent）、レポジトリの用意を行います。
無料 API を呼び出す: MCP 経由で天気 API をコールし、200 OK が返ることを確認します。
有料化設定を行う: x402 を利用して API を有料化し、支払いを行わない状態でコールした際に 200 が返らなくなることを確認します。
暗号通貨支払いでコール成功: API コール時に暗号通貨支払いを行うように設定し、再び 200 OK が返ることを確認します。

Note: このハンズオンでは pnpm を使用したローカル開発環境でのセットアップを行います。Docker を使用する場合は、別途 Docker 版の手順書を参照してください。

まずは開発環境をセットアップをしましょう！

1. ツールのセットアップ（Node.js / pnpm / git / AI Agent）

1-1. バージョン確認

$ node -v
v23.3.0

$ pnpm -v
10.7.0

$ git --version
git version 2.34.1以上

1-2. 未インストールの場合

macOS

# Homebrew 未インストールなら：https://brew.sh/ の手順で導入
brew install git

# Node.jsのインストール（nvmを使用）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# ターミナルを再起動後
nvm install 23.3.0
nvm use 23.3.0

# pnpmのインストール
npm install -g pnpm@10

Windows
1. Git for Windows を公式サイトからインストール
  - https://git-scm.com/download/win
2. Node.js をインストール
  - https://nodejs.org/ から LTS 版（v20 以上）をダウンロードしてインストール
3. pnpm をインストール
```
npm install -g pnpm@10
```

Linux

# Ubuntu/Debian の例
sudo apt update
sudo apt install git

# nvmのインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# ターミナルを再起動後
nvm install 20
nvm use 20

# pnpmのインストール
npm install -g pnpm@10

1-3. AI Agent が未インストールの場合

https://cursor.com/ja/downloads より Cursor をダウンロード

2. リポジトリ取得

git clone https://github.com/takupeso/x402-sample.git
cd x402-sample

3. 環境変数の設定（`.env-local` → `.env` へコピーして編集）

3-1. API サーバー（servers/express）

cd servers/express

# macOS/Linux
cp .env-local .env

# Windows（PowerShell）
copy .env-local .env

# リポジトリルートに戻る
cd ../..

servers/express/.env を開いて以下を設定：

FACILITATOR_URL=https://x402.org/facilitator
NETWORK=base-sepolia
ADDRESS=0x5083F1F60E240CcE4B194B71ED3A606656C51979 # ステーブルコインの送付先（MetaMaskのウォレットアドレス）

3-2. MCP サーバー（mcp）

cd mcp

# macOS/Linux
cp .env-local .env

# Windows（PowerShell）
copy .env-local .env

# リポジトリルートに戻る
cd ..

mcp/.env を開いて以下を設定：

RESOURCE_SERVER_URL=http://localhost:4021
ENDPOINT_PATH=/weather
PRIVATE_KEY=0xea62702203ba1aed571c4b04cb81a86b57b3bb9d3a3f8aa9792735294620d3ac  # ステーブルコインの送付元

重要: RESOURCE_SERVER_URL は http://localhost:4021 に設定してください。これはローカルで起動する Express サーバーのアドレスです。

以上で開発環境のセットアップは完了です！
これからAPIを有料化する開発の開始です！

4. まずはMCP経由で天気APIをコールし、HTTP 200 が返ることを確認

4-0. 依存関係のインストールとビルド

プロジェクトルートから以下のコマンドを実行：

# 依存関係のインストール
pnpm install

4-1. Express サーバーの起動

別のターミナルウィンドウを開いて、Express サーバーを起動します：

cd servers/express
pnpm dev

確認ポイント:

Server listening at http://localhost:4021 というログが表示されれば OK
このターミナルは開いたままにしておいてください

4-2. MCP サーバー設定

（Cursor の場合）

インストールした Cursor アプリを立ち上げ
Shift + Cmd + P（Windows: Shift + Ctrl + P）> mcp を入力し、「View: Open MCP Settings」をクリック
Add Custom MCP をクリック
mcp.json を以下のように修正：

{
  "mcpServers": {
    "weather": {
      "command": "pnpm",
      "args": ["--silent", "-C", "/Users/takumaabe/workspace/x402-sample/mcp", "dev"],
      "env": {
        "PRIVATE_KEY": "0xea62702203ba1aed571c4b04cb81a86b57b3bb9d3a3f8aa9792735294620d3ac",
        "RESOURCE_SERVER_URL": "http://localhost:4021",
        "ENDPOINT_PATH": "/weather"
      }
    }
  }
}

設定のポイント:

<YOUR_PROJECT_DIR_ABSOLUTE_PATH> は、x402-sample プロジェクトの絶対パスに置き換えてください
- macOS/Linux 例: /Users/username/workspace/x402-sample
- Windows 例: C:/Users/username/workspace/x402-sample
環境変数は env セクションで直接指定します

期待値：weather > 1 tools enabled

期待値通りになっていなければ、AI ツール（Cursor など）を再起動してください。

4-3. 200 を検証

AI Agent に天気情報を取得する命令を送る：

例）天気情報を取得して

期待値：HTTP/1.1 200（天気情報）

天気: 晴れ
気温: 70°F（約21°C）

5. x402コードをコメントインしてAPI を「有料化」して HTTP 402 を確認

5-1. x402有料化コードのコメントインと再起動

対象ファイル：servers/express/index.ts
x402 関連コードをコメントイン

import { paymentMiddleware, Resource } from "x402-express";
...
app.use(
  paymentMiddleware(
    payTo,
    {
      "GET /weather": {
        // USDC amount in dollars
        price: "$0.001",
        // network: "base" // uncomment for Base mainnet
        network: "base-sepolia",
      },
    },
    {
      url: facilitatorUrl,
    },
  ),
);

コード変更後、Express サーバーを再起動：

# Expressサーバーのターミナルで Ctrl+C を押してプロセスを終了
# その後、再度起動
cd servers/express
pnpm dev

確認ポイント:

Server listening at http://localhost:4021 というログが再度表示されれば OK

5-2. 402 を検証

AI Agent に天気情報を取得する命令を送る：

例）天気情報を取得して

期待値：HTTP/1.1 402 Payment Required（本文/ヘッダに支払い要件）。AI のレスポンス的に天気情報が取得できていないことがわかれば OK です。

6. MCP 側の「自動課金」を有効化

6-1. MCP サーバーのコメントイン

対象ファイル：mcp/index.ts
x402-axios のインターセプタをコメントイン

import { privateKeyToAccount } from "viem/accounts";
import { withPaymentInterceptor } from "x402-axios";
...
const account = privateKeyToAccount(privateKey);
const client = withPaymentInterceptor(axios.create({ baseURL }), account);
// const client = axios.create({ baseURL }); ← コメントアウトまたは削除

コード変更後、MCP 設定をリフレッシュ：

MCP 設定をリフレッシュ

Shift + Cmd + P（Windows: Shift + Ctrl + P）> reload を入力し、「Developer: Reload Window」をクリック

6-2. 200 を検証

AI Agent に天気情報を取得する命令を送る：

例）天気情報を取得して

期待値：HTTP/1.1 200（天気情報 + 自動支払い完了）

7. よくある詰まりどころ

症状	原因	対処
`402` にならない	x402 ミドルウェアが無効のまま	`servers/express/index.ts` のコメントインを確認。Express サーバーを再起動
支払い後も `402`	コード変更が反映されていない	Cursor ウィンドウをリロード（Shift + Cmd/Ctrl + P > reload）
`insufficient funds`	ガス or USDC 不足	Faucet で ETH/USDC を補充
`invalid signature`	鍵/署名不整合	`mcp.json` の `env.PRIVATE_KEY` を再設定
ポート競合（4021）	既存プロセスが使用中	`lsof -i :4021`（macOS/Linux）または`netstat -ano \| findstr :4021`（Windows）で確認して終了
ネットワークエラー（MCP→Express）	URL が間違っている	`mcp.json` の `env.RESOURCE_SERVER_URL` が `http://localhost:4021` になっているか確認
`pnpm: command not found`	pnpm がインストールされていない	`npm install -g pnpm@10` で pnpm をインストール
`node: command not found`	Node.js がインストールされていない	Node.js v20 以上をインストール
`Cannot find module`	依存関係がインストールされていない	プロジェクトルートで `pnpm install` を実行
MCP 接続エラー	Express サーバーが起動していない	`servers/express` で `pnpm dev` を実行してサーバーを起動

8. （興味があれば）ブロックチェーン上でトランザクションが実行されたことを確認する

Basescanで MetaMask ウォレットアドレス（0x5083F1F60E240CcE4B194B71ED3A606656C51979）をキーワードに検索
トランザクションが表示されていれば成功

Komlock labPublication

ブロックチェーンに特化したWeb3開発ラボ境界を取り除いて、世界を再定義するエンジニア積極採用中！

0. 前提

👉 ハンズオン概要

🔁 ハンズオンの流れ

1. ツールのセットアップ（Node.js / pnpm / git / AI Agent）

1-1. バージョン確認

1-2. 未インストールの場合

1-3. AI Agent が未インストールの場合

2. リポジトリ取得

3. 環境変数の設定（.env-local → .env へコピーして編集）

3-1. API サーバー（servers/express）

3-2. MCP サーバー（mcp）

4. まずはMCP経由で天気APIをコールし、HTTP 200 が返ることを確認

4-0. 依存関係のインストールとビルド

4-1. Express サーバーの起動

4-2. MCP サーバー設定

4-3. 200 を検証

5. x402コードをコメントインしてAPI を「有料化」して HTTP 402 を確認

5-1. x402有料化コードのコメントインと再起動

5-2. 402 を検証

6. MCP 側の「自動課金」を有効化

6-1. MCP サーバーのコメントイン

6-2. 200 を検証

7. よくある詰まりどころ

8. （興味があれば）ブロックチェーン上でトランザクションが実行されたことを確認する

Discussion

3. 環境変数の設定（`.env-local` → `.env` へコピーして編集）