FastAPI MCP Server + LangChain Client Example

FastAPI MCP サーバー + LangChain クライアントの例

fastapi-mcp を使用して FastAPI エンドポイントを Model Context Protocol（MCP）ツールとして公開する方法を示すサンプルプロジェクトです。langchain-mcp-adapters を使用して、HTTP/SSE 経由でローカルの FastAPI サーバーに接続し、公開されたツールを見つけて利用する基本的な LangChain エージェント（langchain_client.py）も含まれています。

前提条件

始める前に、以下がインストールされていることを確認してください。

• Python： バージョン 3.10 以上を推奨します。
• uv： このプロジェクトで使用する Python パッケージマネージャーです。（インストール手順）
• Node.js と npm： npx（オプションの MCP Inspector の実行に使用）に必要です。npm が含まれる Node.js は nodejs.org からダウンロードできます。
• Git： リポジトリのクローンに使用します。
• OpenAI API Key： LangChain クライアントの例に必要です。.env ファイルに設定する必要があります。

このプロジェクトでは、基本的な FastAPI アプリケーションを設定し、fastapi-mcp ライブラリを使用してそのエンドポイントを Model Context Protocol（MCP）ツールとして公開する方法を示します。また、これらのツールに接続して利用する LangChain エージェントクライアントも含まれており、Cursor を接続するための設定方法も説明します。

はじめに／実行方法

1. リポジトリをクローンします：

   git clone <your-repo-url>
   cd <repo-directory>
   

2. uv をインストールします： まだインストールしていない場合は、uv パッケージマネージャーをインストールしてください（コマンドについては、以下のプロジェクトのセットアップを参照してください）。

3. 環境を設定し、依存関係をインストールします：

   uv init # If pyproject.toml doesn't exist
   uv venv # Create virtual environment (.venv)
   # Install all project dependencies
   uv pip install fastapi "uvicorn[standard]" fastapi-mcp langchain-mcp-adapters langgraph langchain-openai python-dotenv
   

4. .env ファイルを作成します： プロジェクトのルートディレクトリに .env という名前のファイルを作成し、OpenAI API キーを追加します。

   OPENAI_API_KEY=your_openai_api_key_here
   

5. FastAPI MCP サーバーを実行します： ターミナルを開いて、次のコマンドを実行します。

   uvicorn main:app --reload --port 8000
   

   このターミナルは開いたままにしてください。 (別の方法として、VS Code／Cursor 内の .vscode/launch.json に定義されている Python: FastAPI MCP デバッグ構成を使用すると、デバッガーを接続した状態でサーバーを実行できます。)

6. LangChain クライアントを実行します： 2 つ目の ターミナルを開いて、次のコマンドを実行します。

   uv run python langchain_client.py
   

   クライアントがサーバーに接続し、ツールを検出して、エージェントを使ったクエリを実行します。

7. （オプション）MCP Inspector でサーバーをテストします： LangChain クライアントを実行する前、またはより直接的にテストする場合は、公式の MCP Inspector ツールを使用できます。

   • FastAPI サーバーが実行中であることを確認します（手順 5）。
   • 別のターミナルを開いて、npx @modelcontextprotocol/inspector を実行します。 （npx は Node.js/npm に付属しています。このコマンドが失敗する場合は、Node.js がインストールされ、PATH からアクセスできることを確認してください。）
   • Inspector の UI で、サーバー URL http://127.0.0.1:8000/mcp に接続します。
   • 「Tools」に移動し、「List Tools」をクリックして read_root__get と greet_user_greet__name__get を確認します。
   • ツールを選択し、パラメーター（例：greet_user の name）を入力して、「Run Tool」をクリックします。

8. （オプション）LangChain クライアントで greet_user をテストします： greet_user エンドポイントと、langchain_client.py 内の対応するテストクエリ（query2）は現在有効です。LangChain クライアントを実行するだけで（手順 6）、実行の後半でユーザー「LangChain」に挨拶しようとする処理を確認できます。

   • (このテストを無効にする場合は、main.py の @app.get("/greet/{name}") エンドポイントと、langchain_client.py の query2 セクションをコメントアウトしてください。)

目標

学習およびテストを目的として、MCP 機能を備えたシンプルな FastAPI サーバーを構築します。ローカルで実行でき、Cursor エディターのエージェントなどの MCP クライアントから接続できます。

プロジェクトのセットアップ

1. パッケージマネージャー： Rust で書かれた高速な Python パッケージインストーラー兼リゾルバーである uv を使用しました。
   • インストール（Windows PowerShell）：irm https://astral.sh/uv/install.ps1 | iex
   • プロジェクトの初期化：uv init（pyproject.toml を作成します）
   • 仮想環境：uv venv（.venv を作成・管理します）
2. 依存関係： uv を使ってインストールしました。

   # 開発時に使用した個別のコマンド（「はじめに」に記載の一括インストールで実行できます）：
   # uv pip install fastapi "uvicorn[standard]" fastapi-mcp
   # uv pip install langchain-mcp-adapters langgraph langchain-openai python-dotenv
   

   これにより、FastAPI、Uvicorn ASGI サーバー、fastapi-mcp、LangChain コンポーネント、および python-dotenv が .venv 仮想環境にインストールされます。

アプリケーション（main.py）

次のエンドポイントを持つシンプルな FastAPI アプリを作成しました。

• /：ウェルカムメッセージを返します。
• /greet/{name}：個別の挨拶を返します（現在はコメントアウトされています）。

重要なのは、fastapi-mcp の統合を FastAPI のルート定義の後に行うことです。

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI(...)

# --- Define FastAPI routes (@app.get, @app.post, etc.) ---
@app.get("/")
async def read_root():
    # ... endpoint logic ...

# --- Initialize and mount fastapi-mcp AFTER routes ---
mcp = FastApiMCP(app)
mcp.mount() # Exposes tools under /mcp by default

サーバーの実行

• 直接実行： uvicorn main:app --reload --port 8000
• デバッガーを使用（Cursor/VS Code）： デバッガーをアタッチしてアプリを実行するため、.vscode に launch.json ファイルを作成しました。

LangChain クライアント（langchain_client.py）

• .env ファイルから OPENAI_API_KEY を読み込みます。
• langchain-mcp-adapters（MultiServerMCPClient）を使い、SSE 経由で実行中の FastAPI サーバー（http://127.0.0.1:8000/mcp）に接続します。
• MCP サーバーが公開するツールを自動的に検出します。
• 検出したツールと OpenAI LLM を使って、LangGraph ReAct エージェントを作成します。
• エージェントを通してサンプルクエリを実行します。

Cursor との統合（MCP クライアント）

1. 設定： プロジェクトのルートに .cursor/mcp.json ファイルを作成しました。

   {
     "mcpServers": {
       "local-fastapi-mcp": {
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

2. 有効化： Cursor の設定でサーバーを有効にする必要があります（Ctrl+, を押して「Cursor Settings」を検索し、「MCP」タブを開きます）。
3. 使用方法： その後、チャットパネル内の Cursor エージェントに、検出されたツールを使うよう依頼できます。

主な学び

• uv の基本： uv init、uv venv、uv pip install を使うと、Python プロジェクト環境をすばやくセットアップできます。
• fastapi-mcp の初期化順序： ツールとして公開する FastAPI ルート（@app.get など）を定義した_後_に、FastApiMCP(app) インスタンスを作成し、mcp.mount() を呼び出す必要があります。そうしないと、ツールが検出されません。
• ポートの競合： バックグラウンドプロセス（uvicorn など）がポートを占有することがあります。Windows では、netstat -ano | findstr "<PORT>" でプロセス ID（PID）を特定し、taskkill /F /PID <PID> で終了できます。OS がポートを完全に解放するまで、少し待つか IDE を再起動する必要がある場合もあります。
• Cursor MCP の設定： .cursor/mcp.json で url キーを使用すると、Cursor を HTTP ベースの MCP サーバー（fastapi-mcp が提供するサーバーなど）に接続できます。
• エージェントによるツールの呼び出し： Cursor の一般的なエージェント環境では設定済みの MCP サーバーが使用されますが、特定のペアプログラミング AI アシスタントは、汎用のツール呼び出し関数ではなく、自動生成された内部名（例：mcp_local-fastapi-mcp_read_root__get）を使ってツールとやり取りします。接続が確立され、ツールが検出されていれば、チャットでエージェントに「ツールを使って」と明示的に依頼できます。

さらに詳しく調べる機能と特徴（fastapi-mcp のドキュメントより）

このセクションでは、まだ実装していませんが知っておくと便利な、fastapi-mcp のドキュメントに記載された機能や概念をまとめます。

認証と認可

fastapi-mcp は、認証に FastAPI の依存関係を使用できるほか、OAuth 2 にも対応しています。

基本的なトークンの受け渡し：

• 最初に特別なサーバー設定を行う必要はありません。

• MCP クライアントは Authorization ヘッダーを送信する必要があります。多くの場合、mcp-remote などのブリッジを介して送信できます：

  {
    "mcpServers": {
      "remote-example": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "http://localhost:8000/mcp",
          "--header",
          "Authorization:${AUTH_HEADER}"
        ]
      },
      "env": {
        "AUTH_HEADER": "Bearer <your-token>"
      }
    }
  }
  

• MCP サーバー側で認証を_必須にする_には、AuthConfig に依存関係を追加します：

  from fastapi import Depends
  from fastapi_mcp import FastApiMCP, AuthConfig
  
  # Assuming verify_auth is your FastAPI dependency that checks the token
  mcp = FastApiMCP(
      app,
      auth_config=AuthConfig(
          dependencies=[Depends(verify_auth)],
      ),
  )
  

OAuth 2 フロー：

• OAuth 2 を全面的にサポートしています（MCP Spec 2025-03-26）。
• プロバイダーの詳細（発行者、URL、クライアント ID／シークレット）を指定して AuthConfig を設定する必要があります。
• 標準的な OAuth プロバイダーと MCP クライアントの想定との互換性の問題（動的登録の欠如、スコープの処理など）に対処するため、setup_proxies=True が必要になることがよくあります。

  mcp = FastApiMCP(
      app,
      auth_config=AuthConfig(
          issuer=f"https://auth.example.com/",
          authorize_url=f"https://auth.example.com/authorize",
          oauth_metadata_url=f"https://auth.example.com/.well-known/oauth-authorization-server",
          audience="my-audience",
          client_id="my-client-id",
          client_secret="my-client-secret",
          dependencies=[Depends(verify_auth)],
          setup_proxies=True, # Creates compatibility endpoints
      ),
  )
  

• mcp-remote を使用する場合、OAuth プロバイダーでコールバック URL（http://127.0.0.1:8080/oauth/callback）を設定できるよう、固定ポート（mcp-remote ... 8080）の指定が必要になることがよくあります。

ツールの命名

• MCP ツール名は、FastAPI ルートの operation_id から生成されます。
• 指定されていない場合、FastAPI が自動生成します（例：read_user_users__user_id__get）。
• MCP ツール名をわかりやすくするため、FastAPI ルートに明示的な operation_id を設定することを推奨します：

  @app.get("/users/{user_id}", operation_id="get_user_info")
  async def read_user(user_id: int):
      # ...
  

ツールの更新

• mcp.mount() の呼び出し後に FastAPI ルートを追加しても、自動的には含まれません。

• 解決方法：新しいルートを定義した後、再度 mcp.setup_server() を呼び出します。

  app = FastAPI()
  mcp = FastApiMCP(app)
  mcp.mount()
  
  @app.get("/new/endpoint", operation_id="new_tool")
  async def new_endpoint(): ...
  
  # Refresh the tools
  mcp.setup_server()
  

テスト

• MCP サーバーのテストには、@modelcontextprotocol/inspector ツールを使用できます：

  # Run the inspector
  npx @modelcontextprotocol/inspector
  # Connect to your server URL (e.g., http://127.0.0.1:8000/mcp)
  # Use the UI to list and run tools.
  

デプロイ

• ある FastAPI アプリ（api_app）から作成した MCP サーバーを、別の FastAPI アプリ（mcp_app）にマウントして、個別にデプロイできます：

  api_app = FastAPI()
  # ... define API endpoints ...
  
  mcp_app = FastAPI()
  mcp = FastApiMCP(api_app) # Create from api_app
  mcp.mount(mcp_app) # Mount onto mcp_app
  
  # Run separately:
  # uvicorn main:api_app --port 8001
  # uvicorn main:mcp_app --port 8000
  

カスタマイズ

• サーバー名と説明は、FastApiMCP の初期化時に設定できます：

  mcp = FastApiMCP(
      app,
      name="My Custom MCP Name",
      description="Description for the server."
  )
  

• ツールやスキーマの説明はカスタマイズできます（例：考えられるすべてのレスポンスを含める）：

  mcp = FastApiMCP(
      app,
      describe_all_responses=True,
      describe_full_response_schema=True
  )
  

• FastApiMCP の初期化時に include_operations、exclude_operations、include_tags、exclude_tags を指定して、公開するエンドポイントを絞り込めます。

謝辞

このプロジェクトは、Cursor に統合された Google の Gemini モデルを含む AI ペアプログラミングツール、および調査とドキュメントの取得における OpenAI の ChatGPT の支援を受けて開発されました。これらの貢献は、開発プロセス全体を通じて非常に貴重なものでした。