🌊 HTTP + SSE MCP Server w/ OAuth

🌊 OAuth を使用する HTTP + SSE MCP サーバー

はじめに

このリポジトリには、MCP 仕様に基づく OAuth 認証に対応し、ストリーミング可能な HTTP および SSE トランスポートをサポートするリモート MCP サーバーの作成に向けた、リファレンス実装が含まれています。

このリポジトリの MCP サーバーは、レポートの SSE および HTTP トランスポートを処理するアプリケーション、および OAuth とは論理的に分離されている点にご注意ください。

そのため、このリポジトリを簡単にフォークし、独自の MCP サーバーと OAuth 認証情報を組み合わせることで、独自の機能を備えた SSE／HTTP + OAuth 対応 MCP サーバーを構築できます。

それはなぜですか？

よい質問です！MCP 仕様には、2025 年 3 月 25 日に OAuth に基づく認可仕様が追加されました。2025 年 5 月 1 日現在の状況は次のとおりです。

• TypeScript SDK には、ストリーミング可能な HTTP を使用する OAuth 認証済み MCP サーバーの構築に必要な部品が多数含まれていますが、そのようなサーバーの構築方法を説明するドキュメントやチュートリアルはありません
• Python SDK には、ストリーミング可能な HTTP トランスポートの実装も、TypeScript SDK に含まれている OAuth の部品の実装もありません
• Cursor や Claude デスクトップなどの MCP ホストアプリケーションでは、ストリーミング可能な HTTP トランスポートは広くサポートされていません。ただし、JS/TS SDK の StreamableHttpClientTransport クラスを使用して、JavaScript で作成したエージェントに直接組み込むことはできます

Naptha AI では、ストリーミング可能な HTTP トランスポートを使用する OAuth 認証済み MCP サーバーをぜひ構築したいと考えていましたが、リファレンス実装が見つからなかったため、自分たちで作ることにしました！

依存関係

Bun は、高速でオールインワンの JavaScript ランタイムです。このリポジトリでは、推奨されるランタイムおよびパッケージマネージャーです。npm + tsc との互換性テストは限定的に実施されています。

概要

このリポジトリでは、次のものを提供します。

1. 独自のものに簡単に置き換えられる MCP サーバー
2. SSE とストリーミング可能な HTTP の両方のトランスポート、および OAuth 認可を管理する Express.js アプリケーション

この Express アプリケーションに、認証情報と MCP サーバーを組み込みます。

この Express アプリは、/authorize や Authorization Server Metadata エンドポイント（RFC8414）など、必要な OAuth エンドポイントを実装していますが、OAuth 認可サーバーは実装していません！

この例では、動的クライアント登録（RFC7591）をサポートする上流の OAuth サーバーに OAuth をプロキシします。この例を使用するには、認可サーバーを各自で用意する必要があります。Auth0 の使用をおすすめします。詳しくは、以下の「OAuth の設定」セクションをご覧ください。

サーバーの設定

OAuth と動的クライアント登録に関する注意事項

この例を使用するには、OAuth 認可サーバーが必要です。ご自身で実装しないでください！ デモの作成には Auth0 を使用しました。Auth0 は優れた選択肢ですが、ほかにも多くの選択肢があります。

MCP 仕様では、一般的ではない OAuth 機能、具体的には RFC7591 の動的クライアント登録への対応が必須です。MCP 仕様では、MCP クライアントとサーバーが動的クライアント登録プロトコルに対応することが推奨されています。これにより、MCP クライアント（クライアントのトランスポートがどこで動作していても）は、ユーザー登録なしでクライアント ID を取得できます。新しいクライアント（エージェント、アプリなど）が、新しいサーバーに自動的に登録できるようになります。詳細はMCP 仕様の認可に関するセクションをご覧ください。ただし、残念ながら、動的クライアント登録に対応していない Google や GitHub のようなプロバイダーに、直接プロキシすることはできません（これらのプロバイダーでは、UI 上でクライアントを登録する必要があります）。

選択肢は次の 2 つです。

1. 認証に Google や GitHub などの OIDC IDP を使用でき、動的クライアント登録にも対応している Auth0 のような上流 OAuth プロバイダーを選ぶ。
2. 動的クライアント登録をアプリケーション側で実装する（つまり、Express アプリケーションを単なる OAuth プロキシではなく、完全または部分的な OAuth サーバーにする）。Cloudflare は、Workers OAuth MCP サーバー向けにこれに似たものを実装しており、後日このプロジェクトに拡張として追加する可能性があります。詳細はこちらをご覧ください。

簡単にするため、今回は Auth0 を使用する前者の方法を選びました。

メモ

この実装では上流 OAuth サーバーにプロキシするため、OAuth サーバーからのアクセストークンをクライアントに転送する標準的な方法では、ユーザーの上流アクセストークンが下流のクライアントと MCP ホストに公開されてしまいます。この方法は多くのユースケースに適さないため、この実装では @modelcontextprotocol/typescript-sdk の一部のクラスを再実装し、この問題を解決しています。

上流の認可サーバーにはプロキシしますが、エンドユーザーの認証トークンを MCP クライアント／ホストに返すことはありません。代わりに独自のトークンを発行し、クライアント／ホストがそのトークンを使ってこのサーバーに対する認可を行えるようにします。これにより、悪意のあるクライアントやホストによるトークンの悪用や、トークンが漏えいした場合の悪用を防ぎます。

Auth0 での OAuth の設定

Auth0 を使い始めるには、次の手順に従います。

1. Auth0.com で Auth0 アカウントを作成します。
2. Google や GitHub などの IDP への接続を 1 つ以上作成します。設定方法はこちらをご覧ください。
3. 接続を_ドメインレベルの接続_に昇格させます。MCP クライアントごとに新しい OAuth クライアントが登録されるため、IDP 接続をアプリケーション／クライアントごとに設定することはできません。つまり、ドメイン内のすべてのアプリで接続を利用できるようにする必要があります。設定方法はこちらをご覧ください。
4. 動的クライアント登録を有効にします（Auth0 では「動的アプリケーション登録」とも呼ばれます）。設定方法はこちらをご覧ください。

すべて設定したら、次の情報が必要になります。

• Auth0 のクライアント ID
• Auth0 のクライアントシークレット
• Auth0 のテナントドメイン

これらの情報を .env に記入してください。.env.template をコピーし、値を設定とシークレットに合わせて更新します。

サーバーの実行

このリポジトリには、独立したサーバーが 2 種類含まれています。

• src/app.stateless.ts にある、ストリーミング可能な HTTP サーバーのステートレスな実装です。ストリーミング可能な HTTP トランスポートのみをサポートし、理論上はサーバーレス環境へのデプロイに適しています。
• src/app.stateful.ts にある、SSE とストリーミング可能な HTTP の両方に対応するステートフルな実装です。このアプリは両方のトランスポートを提供しますが、redis ストレージ戦略を使用する場合もインメモリ状態を維持します（接続をインメモリに保持する必要があります）。そのため、サーバーレス環境へのデプロイや、単純な水平スケーリングには適していません。

どちらも bun で実行できます。

bun run src/app.stateless.ts
# or,
bun run src/app.stateful.ts

すべてをまとめる

ストリーミング可能な HTTP と OAuth に対応した MCP サーバーをテストするには、いくつかの方法があります。

前述のとおり、Python MCP SDK はこれらの機能をサポートしていません。そのため現時点では、リモートサーバーを Cursor や Claude Desktop などの MCP ホストに接続するか、TypeScript／JavaScript アプリケーションに直接接続できますが、Python アプリケーションには接続できません。

サーバーを MCP ホスト（Cursor／Claude）に接続する

ほとんどの MCP ホストは、ストリーミング可能な HTTP（さまざまな点で SSE より優れています）も OAuth もサポートしていないため、OAuth 認証を処理し、リモートトランスポートをホスト向けの STDIO トランスポートにブリッジする mcp-remote npm パッケージの使用をおすすめします。

コマンドは次のようになります。

bunx mcp-remote --transport http-first https://some-domain.server.com/mcp
# or,
npx mcp-remote --transport http-first https://some-domain.server.com/mcp

--transport オプションには、いくつかの選択肢があります。

• http-first（デフォルト）：まず HTTP トランスポートを試し、HTTP が 404 エラーで失敗した場合は SSE に切り替えます。
• sse-first：まず SSE トランスポートを試し、SSE が 405 エラーで失敗した場合は HTTP に切り替えます。
• http-only：HTTP トランスポートのみを使用します。サーバーが対応していない場合は失敗します。
• sse-only：SSE トランスポートのみを使用します。サーバーが対応していない場合は失敗します。

メモ

src/app.stateless.ts を使ってサーバーの ステートレス 版を起動した場合、SSE トランスポートは利用できないため、--transport http-only を使用してください。このエントリーポイントでは、SSE トランスポートが動作することは想定されていません。

サーバーをエージェントに接続する

StreamableHTTPClientTransport を使うと、ストリーミング可能な HTTP サーバーを JS／TS のエージェントに接続できます。ただし、これは OAuth で保護されたサーバーでは動作しません。代わりに、クライアント側で Authorization ヘッダーを使用し、サーバー側で有効なアクセストークンを使ってください。

クライアントクレデンシャル、API キーなどを使って実装できます。このパターンはこのリポジトリではサポートされていませんが、Vercel AI SDK を使うと次のようになります。

import { openai } from '@ai-sdk/openai';
import { experimental_createMCPClient as createMcpClient, generateText } from 'ai';
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const mcpClient = await createMcpClient({
  transport: new StreamableHTTPClientTransport(
    new URL("http://localhost:5050/mcp"), {
      requestInit: {
        headers: {
          Authorization: "Bearer YOUR TOKEN HERE",
      }, 
    },
    // TODO add OAuth client provider if you want
    authProvider: undefined,
  }),
});

const tools = await mcpClient.tools();
await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello, world!",
  tools: {
    ...(await mcpClient.tools())
  }
});