CodeQR

CodeQR リモート MCP サーバー

OAuth 2.0 認証を備えたCodeQRのリモート MCP サーバーです。ChatGPT、OpenAI Agents SDK、Grok（xAI）、および Streamable HTTP トランスポートに対応するすべての MCP クライアントと互換性があります。

仕組み

┌──────────┐      ┌─────────────────────┐      ┌──────────┐
│  ChatGPT │      │  CodeQR MCP Remote  │      │ CodeQR   │
│  or any  │─────▶│                     │─────▶│ API      │
│  MCP     │◀─────│  OAuth 2.0 + MCP    │◀─────│          │
│  client  │      │  Streamable HTTP    │      │          │
└──────────┘      └─────────────────────┘      └──────────┘

1. クライアントは /.well-known/oauth-protected-resource を通じて認証エンドポイントを検出します
2. クライアントは POST /oauth/register を通じて動的に登録します
3. GET /oauth/authorize には、このサーバーの同意画面が表示されます。アプリが自己申告した名前が表示され、正確なリダイレクト URI が src/oauth/verified-clients.ts に記載されていない場合は未検証として示されます。また、そのリダイレクト URI の遷移先ホストも表示されます。承認すると、ユーザーは CodeQR に移動し、ログインして、アクセスを許可するプロジェクトを選択して承認します。API キーが扱われることはありません。コールバックを完了できるのは、承認したブラウザーだけです。
4. CodeQR はユーザーを GET /oauth/callback に戻し、そこでコードをアクセストークンとリフレッシュトークンのペアに交換します
5. クライアントは認証コードをアクセストークンと交換します（PKCE）
6. クライアントは Bearer トークンを使って、POST /mcp に MCP ツール呼び出しを送信します

CodeQR のアクセストークンの有効期間は 7 日で、自動的に更新されます。更新のたびにセッションの有効期間はさらに 120 日延長されるため、使用中の接続は決まった日に期限切れになりません。アイドル状態の接続は最後の更新から 120 日後に終了し、作成から 1 年を超えて有効な接続はありません（クライアントに渡される expires_in）。

クイックスタート

# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your SERVER_URL

# Development
npm run dev

# Production
npm run build
npm start

デプロイ

Vercel（推奨）

このプロジェクトは Vercel のサーバーレス関数向けに設定されています。

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set environment variables in Vercel dashboard:
# - SERVER_URL — Your public server URL (e.g., https://mcp.codeqr.io)
# - UPSTASH_REDIS_REST_URL — From your Upstash Redis database (REST API)
# - UPSTASH_REDIS_REST_TOKEN — From your Upstash Redis database
# - CODEQR_OAUTH_CLIENT_ID — client_id of the OAuth app registered in CodeQR
# - CODEQR_OAUTH_CLIENT_SECRET — its client_secret
# - CODEQR_APP_URL — Dashboard origin (default: https://app.codeqr.io)
# - MCP_UI_ENABLED — Set to 1 to show the item card in hosts that render MCP Apps (off when unset)
# - STAINLESS_API_KEY — Optional Stainless API key
# - LOG_LEVEL — Log level (default: info)

アプリは https://your-project.vercel.app で利用できます。すべてのルートは api/server.ts のサーバーレス関数で処理されます。

OAuth のストレージ： 認証コード、アクセストークン、登録済みクライアントをサーバーレス関数の呼び出し間で保持するには、Upstash Redis（UPSTASH_REDIS_REST_URL と UPSTASH_REDIS_REST_TOKEN）を設定してください。これらの変数を省略すると、サーバーはメモリー内ストアにフォールバックします（ローカル開発のみでの使用に適しています）。

Docker

docker build -t codeqr-mcp-remote .
docker run -p 3000:3000 -e SERVER_URL=https://mcp.codeqr.io codeqr-mcp-remote

Railway / Render / Fly.io

環境変数を設定します。

• SERVER_URL — サーバーの公開 URL（例：https://mcp.codeqr.io）
• UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN — 複数インスタンスの使用時や再起動に備えて設定することを推奨します
• PORT — ポート（通常、プラットフォームによって自動設定されます）

ChatGPT に接続する

1. このサーバーを公開 URL にデプロイします
2. ChatGPT で 設定 > 詳細設定 > 開発者モード に移動します
3. コネクタータブに移動します
4. コネクターを追加をクリックします
5. サーバー URL を入力します（例：https://mcp.codeqr.io/mcp）
6. ChatGPT が OAuth エンドポイントを自動検出し、認証を求めます

OpenAI Agents SDK に接続する

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "codeqr",
        "server_url": "https://mcp.codeqr.io/mcp",
        "require_approval": "never",
    }],
    input="Create a short link for https://codeqr.io",
)

利用可能なツール

ツール	説明
create_link	短縮リンクを作成します
list_links	すべての短縮リンクを一覧表示します
get_link_info	リンクの詳細を取得します
update_link	リンクを更新します
delete_link	リンクを削除します
create_qrcode	URL、Wi-Fi 認証情報、連絡先カード、WhatsApp、メール、SMS、電話番号、テキスト、または暗号資産のリクエストを埋め込んだ動的 QR コードを作成します
list_qrcodes	すべての QR コードを一覧表示します
update_qrcode	既存の QR コードの遷移先を変更します。再印刷は不要です
delete_qrcode	QR コードを削除します。印刷済みのものも解決されなくなります
get_analytics	クリック分析データを照会します
list_domains	カスタムドメインを一覧表示します
list_tags	タグを一覧表示します
create_tag	タグを作成します
get_workspace	認証済みワークスペースの名前、スラッグ、プランを読み取ります

コンバージョンイベントのツールは提供していません。track_lead と track_sale には conversions.write スコープが必要ですが、CodeQR はこのスコープをワークスペースの所有者にのみ付与します。このスコープを要求すると、それ以外のユーザーについて CodeQR が認証全体を拒否します。リンクごとの trackConversion 切り替えは links.write のフィールドであり、create_link／update_link で公開されています（コンバージョントラッキングを含むプランのみ）。 スマートルールは create_link／update_link の rules で指定します。APIが実装する12個の属性のいずれかによる条件付きルーティングと、2〜4個の宛先へのトラフィック分割に対応しており、A/Bテストは条件なしの1つのルールと split で表現します。ワークスペースでスマートルールが有効になっていない場合、APIは呼び出し全体を拒否します。作成または更新はそのまま失敗するため、指定したルールなしでリンクやQRコードが作成されることはありません。また、サーバーはその拒否内容をそのまま転送せず、このワークスペースではスマートルールが有効になっていないことを、詳細へのリンクとともに通知します。 src/plan-limit-message.ts は、把握しているプラン関連の文言を認識します。この例のような機能制限は「このワークスペースでは有効になっていません」となり、クォータ超過は「上限 N … に達しました」となります。認識できないものは変更せず、そのまま返します。この機能の不変条件のうち4つは JSON Schema では表現できません（重みの合計が100であること、url と split のどちらか一方であること、条件がすべて指定されているか一切指定されていないこと、無条件のルールが最後にあること）。そのため、リクエスト送信前に src/smart-rules.ts で検証します。これにより、往復通信を省けるうえ、SDKが返すシリアライズされたエラー本文ではなく、簡潔な文で回答できます。

知っておくべき落とし穴は、value がリクエストに含まれる値と、文字列全体で大文字と小文字を区別せずに比較される点です。3つの属性では、名前から想像されるより対象が限定されています。device はオペレーティングシステム（iOS、Android、Windows、Mac OS、Linux。mobile ではありません）、language は2文字のコード、referrer はドメインのみです。値が誤っていても、どこでもエラーにはなりません。APIは任意の文字列を受け付け、ルールは一致しないまま何も通知されません。

create_qrcode／update_qrcode では、title と walletPass も指定できます。title はQRコードの表示タイトルを設定し、そのコードから保存した Google／Apple Wallet パスに大きな文字で印字されます（「QR Code」の代わりに表示されます）。 walletPass 内では、name と logo がパスに表示されるワークスペース名とロゴを上書きし、barcodeText はQRコードの下に表示されるテキスト（会員名やカード番号など）を設定します。これが指定されていない場合、CodeQRはその行にテキストを送信しません。タイトルがそこに繰り返し表示されることはありません。カスタムブランディングを利用できるのは、その機能を含むプランのみで、トライアル中は利用できません。新しい非 null の walletPass は、それ以外のプランまたはトライアル中に指定すると403で拒否されますが、null（クリア）は常に受け付けられます。これらのプラン以外、またはトライアル中は、パスの生成時に保存済みの値が無視されるため、ワークスペース名とロゴが使用されます。logo は https URL です。APIがこれをダウンロードして独自のコピーを保存するため、レスポンスには送信したURLではなく、そのコピーのURLが返されます。barcodeText はトリミング後に1〜40文字である必要があります。update_qrcode では、オブジェクトを指定すると保存済みの値全体が置き換わります（オブジェクトに含まれないフィールドはマージされず、クリアされます）。3つすべてを保持するには、name、logo、barcodeText をまとめて送信してください。null は上書きをクリアしてワークスペースのブランディングに戻します。これは、実行中のスマートルールテストを終了する rules: null と同じです。

インタラクティブカード（MCP Apps）

MCP_UI_ENABLED=1 を設定すると、MCP Apps を表示するホスト（ChatGPT、Claude）では、create_qrcode、update_qrcode、create_link、update_link、get_link_info が返す QR コードまたは短縮リンクのカードが表示されます。カードには、画像、コピーボタン付きの短縮リンク、それが動的かどうか、リンク先、スキャン数またはクリック数のほか、CodeQR ダッシュボードで開くボタンと、スキャン数またはクリック数を尋ねるボタンが含まれます。

• ツールの _meta.ui.resourceUri は ui://codeqr/item-card.v1.html を指し、resources/read（src/widgets/）を通じて提供されます。読み取りのたびに mcp.resource_read としてログに記録されます。
• 結果には structuredContent（許可リストにあるフィールド。ホストはこれもモデルに表示します）と _meta["io.codeqr/card"]（カード専用の画像 URL とダッシュボード URL）が含まれます。UI のないクライアント向けに、content は変更されません。
• get_analytics は分析カード（ui://codeqr/analytics.v1.html）を表示します。カードには、集計対象と期間、合計、推移線または上位 5 行、ダッシュボードで分析を開くボタンが含まれます。24h／7d／30d のチップを使うと、ホストが対応可能と示している場合に限り、かつすべてのプランで読み取り可能な期間に限り、ホスト経由でカード内から呼び出し（tools/call）を再実行します。
• ページは web/item-card/ と web/analytics/ にあり、ホストとのブリッジは web/shared/ にあります。yarn widgets:build で src/widgets/generated/ にバンドルされ、このファイルはコミット対象です。古い状態だと yarn verify は失敗します。ブラウザーで確認するには、node scripts/build-widgets.mjs --html を実行し、web/dev/ をサーブして、harness.html?fixture=qr&theme=dark&locale=pt-BR&width=375 または harness.html?widget=analytics&fixture=countries&interval=30d を開きます。

設定を解除した場合、ツールの一覧、リソースの一覧、すべての結果は以前と同じです。

API エンドポイント

メソッド	パス	認証	説明
GET	/health	なし	ヘルスチェック
GET	/.well-known/oauth-protected-resource	なし	OAuth リソースメタデータ（RFC 9728）
GET	/.well-known/oauth-authorization-server	なし	OAuth サーバーメタデータ（RFC 8414）
POST	/oauth/register	なし	動的クライアント登録（RFC 7591）
GET	/oauth/authorize	なし	同意画面：どのアプリか、アクセス先はどこか
POST	/oauth/authorize	なし	同意の決定。承認時は CodeQR にリダイレクト
GET	/oauth/callback	なし	CodeQR からの戻り処理
POST	/oauth/token	なし	トークン交換
POST	/mcp	Bearer	MCP Streamable HTTP エンドポイント

アーキテクチャ

src/
├── index.ts              # Express app & server startup
├── config.ts             # Environment configuration
├── oauth/
│   ├── store.ts          # OAuth state: Upstash Redis or in-memory fallback
│   └── pkce.ts           # PKCE S256 verification
├── middleware/
│   └── auth.ts           # Bearer token validation middleware
└── routes/
    ├── well-known.ts     # OAuth discovery metadata endpoints
    ├── oauth.ts          # Authorization & token endpoints
    └── mcp.ts            # MCP tool definitions & handlers

本番環境での考慮事項

• OAuth の永続化： サーバーレスおよび複数インスタンスのデプロイでは、Upstash Redis（.env.example を参照）を設定してください。設定しない場合は、メモリ内ストアが使用されます（単一プロセスのみ）。
• OAuth と MCP のエンドポイントにレート制限を追加します
• HTTPS を追加します（通常はリバースプロキシ／プラットフォームで処理されます）
• 監視を追加します（/health エンドポイントはプローブに対応済みです）
• 長時間有効なセッションでは、トークンのローテーションを検討します

MCP Registry への公開

このサーバーは公式レジストリに io.codeqr/codeqr として登録されています。レジストリに保存されるのは server.json 内のメタデータのみで、コードは保存されません。

公開の承認には DNS を使用します。codeqr.io の apex にある TXT レコードに、Ed25519 キーペアの公開鍵が格納されています。セレクターではなく apex を使用します。MCP の DNS 認証では SPF 方式の配置に従うため、_mcp-auth. の下にレコードを置くと、原因を示さない汎用署名エラーが発生します。

# 1. Bump the version in package.json, src/config.ts and server.json together.
#    `yarn test` fails if they drift — the registry refuses to republish a
#    version it already has.
#
#    Then bump it in the CodeQR app too: the Server Card at
#    app/.well-known/mcp/server-card.json/route.ts advertises this server's
#    version, and no test can reach across repos to check. It already drifted
#    once, to a release that never existed.

# 2. Authenticate with the private key (kept outside this repo).
PRIVATE_KEY="$(openssl pkey -in /path/to/codeqr-io.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')"
mcp-publisher login dns --domain codeqr.io --private-key "$PRIVATE_KEY"

# 3. Publish, then confirm the entry is live.
mcp-publisher publish
curl "https://registry.modelcontextprotocol.io/v0/servers?search=codeqr"

鍵をローテーションする場合は、古い TXT レコードを削除してください。古いレコードが先に試され、検証に失敗します。

ディレクトリ一覧

アグリゲーターはエコシステムをクロールし、誰かが所有権を申請しているかどうかにかかわらずサーバーを掲載します。そのため、未申請のエントリーも、ボットがこのサーバーの機能を推測したものとして存在します。所有権を申請するとその推測が置き換わり、読者に表示される名前と説明を編集できるようになります。これらはいずれもファイルのマージでは行われず、それぞれのアグリゲーターのサイト上で一度だけ操作します。

ディレクトリ	所有権の申請方法	状態
Official MCP Registry	上記のとおり、mcp-publisher + DNS	掲載済み
Glama	このリポジトリ内の glama.json を用意し、maintainers に記載されたアカウントから申請フローを一度実行	リポジトリ内にファイルあり。申請待ち
Smithery	smithery mcp publish https://mcp.codeqr.io/mcp -n <org>/<name>	保留中
PulseMCP	サイト上での手動審査付きの申請	保留中
mcp.so	申請フォーム / GitHub Issue	保留中

Glama が提供する GitHub OAuth 経由の方法では、個人アカウントのリポジトリしか関連付けられません。このリポジトリは個人アカウントではなく、codeqr-io 組織に属しているため、ファイルを使用しています。

ライセンス

MIT — CodeQR