2026.11.13 開発

FastAPI MCPの実装手順｜既存APIをfastapi-mcpでMCPツール化する方法と認証・公開範囲

Q: fastapi-mcpとFastMCPはどちらを使えばよいですか？

利用者本人のトークンで既存の認可をそのまま効かせたいならfastapi-mcpです。 Authorization を既定で転送するため、既存の Depends が利用者を判定できます。ただし最新版の0.4.0は2025年7月の公開で、mcpを1系に固定して使う前提です。長く保守する前提、またはサービスアカウント1つで足りるならFastMCPを選びます。FastMCPの4系の変更点は FastMCP 4の移行判断の記事 にまとめています。

Q: 既存のAPIと同じポートでMCPサーバーを動かせますか？

同じポートで動かすことが可能です。 mount_http() は既定で同じアプリの /mcp にマウントするので、APIもMCPも同じuvicornのプロセスで動きます。パスを変えたい場合は mount_http(router, mount_path="/my-http") のように指定する方法です。MCP側の負荷をAPIから切り離したい場合は、MCP用に別のプロセスを立てて、そちらから既存APIを呼ぶ構成も取れます。

Q: 後から追加したエンドポイントがツールに出てこないのはなぜですか？

ツールの一覧は FastApiMCP を作った時点のルートで組まれるためです。 include_router を FastApiMCP の生成より後に書いていないかを確かめます。どうしても後から足す構成なら、追加のあとに mcp.setup_server() を呼ぶことで反映が可能です。 include_tags で絞っている場合は、追加したルートにタグが付いているかも見ます。

Q: SSEにしか対応していないMCPクライアントからも接続できますか？

接続できます。 公式のMCP Transport のとおり、 mount_http() と並べて mount_sse() を呼ぶと、 /sse でSSEの接続も受けられます。0.4.0ではStreamable HTTPが推奨で、SSEは古いクライアントとの互換のために残された扱いです。新しく登録するクライアントは /mcp に向けます。

Q: ツールの呼び出しが10秒で失敗するのはなぜですか？

fastapi-mcpの既定のHTTPクライアントのタイムアウトが10秒だからです。エンドポイントの処理が10秒を超えると、ツールの呼び出しの結果は失敗です。 http_client 引数にASGIで同じアプリを呼ぶ httpx.AsyncClient を、長めのタイムアウトを付けて渡すと延ばせます。数分かかる処理なら、受付だけを即座に返し、結果を取るツールを別に用意する方が、エージェントの待ち時間も短く済みます。

FastAPI MCPの実装手順｜既存APIをfastapi-mcpでMCPツール化する方法と認証・公開範囲

手元で動いているFastAPIのエンドポイントを、Claude CodeやCursorから呼べるMCPツールに変える方法をまとめた記事です。中心はfastapi-mcp 0.4.0で、既存のアプリに数行足して/mcpを生やすところから、公開するツールの絞り込み、Authorizationヘッダーを使った利用者ごとの認可までをコードで確認します。2026年11月時点ではmcp（公式Python SDK）が2系に上がっており、fastapi-mcpをそのまま入れると動かない組み合わせになる点と、その回避策も扱います。FastMCPのfrom_fastapiへ移る場合の違いと、既存APIをそのままMCPにしない方がよい場面も書きました。

まとめ：既存FastAPIをMCPサーバー化する手段の選び方と結論

利用者ごとのトークンで認可している既存APIを、そのままエージェントに呼ばせたいならfastapi-mcpが近道です。クライアントが送ったAuthorizationヘッダーを既定で各エンドポイントへ渡すため、今あるDependsの認証がそのまま効きます。ただし0.4.0は2025年7月28日から新しい版が出ておらず、依存のmcpを1系に固定して使うことが前提です。

これから長く保守するMCPサーバーを作るなら、保守が続いているFastMCP（4.1.8）を選びます。FastMCPは受信したAuthorizationを転送しないので、利用者ごとの認可を引き継ぐ設計は自分で組む必要があります。

どちらを使う場合も、公開するエンドポイントは許可リストで選び、更新系は最初は出しません。ツール名はoperation_idで決まるため、ルートに明示的な名前を付けるところから始めます。

fastapi-mcp 0.4.0で既存FastAPIにMCPの入口を足す最小構成

fastapi-mcpは、FastAPIが自動生成するOpenAPIの定義を読んで、各エンドポイントをMCPのツールに変換するライブラリです。GitHubのtadata-org/fastapi_mcpで公開され、ライセンスはMITです。

mcp 1系に固定してfastapi-mcpを入れる検証環境の作り方

PyPIのfastapi-mcpの最新は0.4.0（2025年7月28日公開）で、動作要件はPython 3.10以上です。依存の指定はmcp>=1.12.0と下限だけなので、何も考えずに入れると2系のmcpが入ります。理由は後の章で説明するとして、ここでは1系に固定して入れます。FastAPI自体の導入がまだなら、FastAPIの最短の起動手順を先に済ませてください。

# 仮想環境を作り、mcpを1系に固定してfastapi-mcpを入れる
python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]==0.162.5" "fastapi-mcp==0.4.0" "mcp>=1.12,<2"

# 入った版を確かめる
pip show mcp fastapi-mcp | grep -E "^(Name|Version)"

pip showでmcpのVersionが1から始まっていれば準備完了です。

FastApiMCPとmount_httpで/mcpを生やす最小コード

注文の状況を返すAPIを例にします。末尾の3行がfastapi-mcpの追加分で、既存のエンドポイントには手を入れていません。

# main.py
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI(title="Order API")


@app.get("/orders/{order_id}", operation_id="get_order_status", tags=["mcp"])
def get_order_status(order_id: int):
    """注文IDを受け取り、配送状況を返す。"""
    return {"order_id": order_id, "status": "shipped"}


mcp = FastApiMCP(app, name="Order API MCP")
mcp.mount_http()  # 既定のパスは /mcp

fastapi dev main.pyで起動すると、通常のAPIに加えてhttp://127.0.0.1:8000/mcpがMCPのエンドポイントになります。CHANGELOGによると、0.4.0でStreamable HTTP用のmount_http()が加わり、それまでのmount()は非推奨になりました。古い解説記事のmcp.mount()は、この版ではmount_http()に書き換えます。SSEにしか対応していないクライアント向けにはmount_sse()が残っています。

Claude Codeから接続してツール一覧と呼び出しを確かめる手順

接続先には、Streamable HTTPに対応したクライアントならURLをそのまま登録できます。Claude Codeでは公式ドキュメントのMCPの章にある--transport httpで追加します。

# FastAPIを起動したまま、別の端末で登録する
claude mcp add --transport http orders http://127.0.0.1:8000/mcp

# Claude Code の中で /mcp を開き、orders が connected になっているか見る

接続できたら「注文1234の状況を教えて」と頼むと、get_order_statusツールが呼ばれます。ツールの説明文にはエンドポイントのdocstringが入るので、何を返すのかを1文で書いておくと、エージェントが呼ぶべき場面を取り違えにくくなります。

operation_idとinclude_tagsでMCPに出すツールを絞る設定手順

fastapi-mcpは、指定しなければ全エンドポイントをツールにします。管理用の削除APIまでエージェントから呼べる状態は避けたいので、名前と範囲を最初に決めます。

operation_id未指定で長いツール名が付く問題と命名の決め方

公式のTool Namingのとおり、ツール名はFastAPIのルートのoperation_idです。指定しないとFastAPIが自動で名前を作り、/users/{user_id}のGETならread_user_users__user_id__getのような名前になります。エージェントはツール名と説明文を手がかりに呼ぶツールを選ぶため、この形は避けます。

命名は「動詞＋対象」のスネークケースに揃えます。get_order_status、search_productsのように、名前だけで読み取りか更新かが分かる形です。operation_idはOpenAPIの定義にも載り、Swagger UIの表示にもそのまま出るので、人間向けのドキュメントの見やすさも同時に上がります。

include_tagsで許可リスト方式にするときの組み合わせ規則

絞り込みの引数は4つあります。公式のCustomizationに書かれた規則を表にします。

引数	指定する値	同時に使えない相手
include_operations	公開するoperation_id	exclude_operations
exclude_operations	除外するoperation_id	include_operations
include_tags	公開するタグ	exclude_tags
exclude_tags	除外するタグ	include_tags

同時指定は、server.pyのコンストラクタでValueErrorになります。操作による絞り込みとタグによる絞り込みは併用でき、その場合はどちらかに当てはまるものが公開される和集合です。

おすすめはinclude_tags=["mcp"]の許可リスト方式です。除外リスト方式だと、後から足した管理用エンドポイントがタグを付け忘れた瞬間に公開されます。許可リストなら、付け忘れたエンドポイントは出ないだけで済みます。

起動後に追加したエンドポイントをsetup_serverで反映する方法

FastApiMCP(app)を作った時点のルートでツール一覧が組まれます。プラグインの読み込みなどで、その後にエンドポイントを追加する構成では、公式のRefreshing the Serverにあるとおりmcp.setup_server()を呼んで作り直します。ルーターのinclude_routerを全部済ませてからFastApiMCPを作る順番にしておけば、この呼び出しは要りません。

Authorizationヘッダーの転送とDependsで利用者ごとに認可する実装

fastapi-mcpの一番の利点はここです。MCPの層で認証を作り直さず、既存のAPIの認証をそのまま使えます。

既定でauthorizationだけを転送する仕組みとheaders引数

ツールが呼ばれると、fastapi-mcpはHTTPを経由せず、ASGIで同じFastAPIアプリを直接呼びます。server.pyの既定値では、このときMCPクライアントから受け取ったヘッダーのうち転送するのはheaders=["authorization"]の許可リストだけです。大文字小文字は区別しません。

テナントIDをX-Tenant-Idで受けているAPIなら、FastApiMCP(app, headers=["authorization", "x-tenant-id"])のように足します。Cookieで認証しているAPIは、エージェントがブラウザのCookieを持たないため、この仕組みでは引き継げません。トークン方式の入口を別に用意します。

AuthConfigのdependenciesでトークンの無い接続を入口で断る

認証付きにした完成形が次のコードです。get_current_userは既存のAPIでも使う依存関数で、MCP側の入口と各エンドポイントの両方で同じものを使います。

# main.py（認証付き）
from typing import Annotated

from fastapi import Depends, FastAPI, Header, HTTPException
from fastapi_mcp import AuthConfig, FastApiMCP

app = FastAPI(title="Order API")

# 検証用のトークン表。本番ではJWTの署名検証やDB照会に置き換える
TOKENS = {"token-alice": "alice"}


def get_current_user(authorization: Annotated[str | None, Header()] = None):
    if not authorization or not authorization.startswith("Bearer "):
        raise HTTPException(401, "token required")
    user = TOKENS.get(authorization.removeprefix("Bearer "))
    if user is None:
        raise HTTPException(401, "invalid token")
    return user


UserDep = Annotated[str, Depends(get_current_user)]


@app.get("/orders/{order_id}", operation_id="get_order_status", tags=["mcp"])
def get_order_status(order_id: int, user: UserDep):
    """自分の注文の配送状況を返す。"""
    return {"order_id": order_id, "owner": user, "status": "shipped"}


@app.delete("/orders/{order_id}", operation_id="cancel_order", tags=["admin"])
def cancel_order(order_id: int, user: UserDep):
    """注文を取り消す。MCPには公開しない。"""
    return {"order_id": order_id, "canceled": True}


mcp = FastApiMCP(
    app,
    name="Order API MCP",
    include_tags=["mcp"],
    auth_config=AuthConfig(dependencies=[Depends(get_current_user)]),
)
mcp.mount_http()

公式のAuthentication & Authorizationでは、AuthConfigのdependenciesに依存関数を渡すと、トークンの無い接続をMCPの入口で拒否できると説明しています。クライアント側は、登録時にヘッダーを付けます。

claude mcp add --transport http orders http://127.0.0.1:8000/mcp \
  --header "Authorization: Bearer token-alice"

これでget_order_statusの中のuserにはaliceが入り、自分の注文だけを返す既存のロジックがそのまま働きます。Dependsの連鎖やテストでの差し替えはFastAPIのDependsの使い方で扱っています。トークンをJWTにする場合の検証は、JWTの構造と署名検証の仕組みを土台にした検証方法です。

OAuthのAuthConfigを使うのは社外の利用者に配る場合だけ

AuthConfigにはissuerやclient_idを渡してOAuthの認可フローを組む設定もあります。公式も「多くのOAuthプロバイダーはMCPクライアントと組み合わせるのに手直しが要る」として、setup_proxies=Trueで中継用のエンドポイントを作る方法を案内しています。社内の開発者が自分のAPIトークンを登録して使う用途なら、ここまでは要りません。社外の利用者にブラウザでログインさせて配る場合だけ、この設定を検討します。

mcp 2系の環境でfastapi-mcpが動かない原因とmcp 1系へ固定する判断

導入手順でmcpを1系に固定したのは、0.4.0のソースと公式SDKの変更が噛み合わないためです。

デコレーター登録のlowlevel Serverがmcp 2系で外れた経緯

fastapi-mcpのsetup_serverは、公式SDKの低水準APImcp.server.lowlevelのServerを作り、@mcp_server.list_tools()と@mcp_server.call_tool()のデコレーターでツール一覧と呼び出しの処理を登録しています。一方、公式のv1からv2への移行ガイドは、低水準のServerがデコレーター方式からコンストラクタのon_*引数方式に変わり、v1のままserver.list_toolsを参照するとAttributeErrorになると明記しています。

2026年11月13日時点でPyPIのmcpの最新は2.3.0です。fastapi-mcpの依存指定には上限が無いので、新しく作った環境ではこの2系が選ばれます。本記事では手元での実行による再現は確認できていません。ソースと移行ガイドの突き合わせから、1系に固定して使うのが安全と判断しました。

mcp<2の固定で使い続けてよい条件と移行を始める合図

固定で使い続けてよいのは、社内向けの小さなMCPサーバーで、MCPの新しい仕様の機能を当面使わない場合です。requirements.txtやpyproject.tomlにmcp<2を書き、Dependabotなどの自動更新で外れないようにします。

移行を始める合図は2つです。1つは、使っているMCPクライアントが新しいプロトコル版でしか接続しなくなったとき。仕様の変更点はMCP仕様2026-07-28版の解説にまとめています。もう1つは、mcp 1系やその依存にセキュリティ修正が必要になり、1系の範囲で直せないときです。どちらかが来たら、次の章のFastMCPへ移すか、公式SDK 2系で書き直します。SDK 2系への書き換え方はMCP Python SDK v2移行の手順で扱っています。

FastMCP.from_fastapiへ移す場合の書き方と認証ヘッダーの扱いの差

PyPIのFastMCPは2026年11月13日時点で4.1.8です。公式のFastAPI連携ガイドにあるFastMCP.from_fastapi()で、同じ既存アプリを変換できます。

RouteMapのEXCLUDEで更新系を外すfrom_fastapiのコード

FastMCPも既定では全エンドポイントをツールにします。OpenAPI連携のドキュメントにあるRouteMapで、更新系のメソッドを除外する設定です。route_mapsは上から順に評価され、最初に当てはまった規則が使われます。

# mcp_server.py
from fastmcp import FastMCP
from fastmcp.server.providers.openapi import MCPType, RouteMap

from main import app

mcp = FastMCP.from_fastapi(
    app=app,
    name="Order API MCP",
    route_maps=[
        # 更新系はMCPに出さない
        RouteMap(methods=["POST", "PUT", "PATCH", "DELETE"], pattern=r".*", mcp_type=MCPType.EXCLUDE),
    ],
    # FastAPIへ送るヘッダーは固定値になる
    httpx_client_kwargs={"headers": {"Authorization": "Bearer service-token"}},
)

if __name__ == "__main__":
    mcp.run()

既存のFastAPIと同じプロセスにhttp_app()でマウントする方法と、lifespanの渡し忘れで起きる不具合は、FastMCPでMCPサーバーを作る手順の記事のFastAPI連携の章で扱っています。

fastapi-mcpとFastMCPで利用者ごとの認可が引き継がれるかの違い

2つの一番大きな違いは、MCPクライアントが送ったAuthorizationの扱いです。FastMCPのOpenAPI連携のドキュメントは、受信したMCPリクエストのヘッダーを転送するとしつつ、Authorization、Cookie、Hostは対象外だと書いています。上のコードのようにサービス用の固定トークンを送る形になり、FastAPI側からはすべての呼び出しが同じ利用者に見えます。

比較項目	fastapi-mcp 0.4.0	FastMCP 4.1.8
Authorizationの転送	既定で転送	転送しない
APIの呼び方	ASGIで直接	httpxのクライアント経由
除外の指定	operation_id・タグ	RouteMap（メソッド・パス・タグ）
最新版の公開	2025年7月	2026年11月時点で更新中
mcp 2系への対応	1系固定が前提	独立した実装

判断はこうです。利用者ごとに見える範囲が違うAPIを、利用者本人のトークンで呼ばせたいならfastapi-mcp。読み取り専用の社内APIをサービスアカウント1つで公開する、あるいはMCPサーバーを長く育てる前提ならFastMCPを選びます。FastMCPで利用者ごとの認可が要る場合は、MCP側で認証してから、検証済みの利用者情報をFastAPIへ渡す経路を自分で設計することになります。

既存APIをそのままMCPツールにしない方がよい場面と設計し直す基準

FastMCPの公式ドキュメントも、FastAPIからの自動変換は立ち上げや試作向けで、複雑なAPIほど目的に合わせて選んだツールの方がLLMの成績が良いと書いています。変換できることと、変換したものが使いやすいことは別です。

既存の画面向けAPIを変換するとエージェントが迷う3つの兆候

次のどれかに当てはまるエンドポイントは、変換せずにMCP用の入口を別に書きます。

1つの目的に複数回の呼び出しが要る（一覧で内部IDを取り、詳細を引き、さらに別APIで在庫を見る）
引数に画面の都合の値が並ぶ（ソート列、表示件数、UI用のフラグ）
応答が大きい（画面の表示に使う全項目を返し、1回で数万字になる）

この場合は、「注文番号から配送状況と到着予定日だけを返す」のように、エージェントの1つの質問に1回で答えるエンドポイントを/mcp-api/の下に新しく作り、そこだけをinclude_tagsで公開します。既存のサービス層の関数を呼び直すだけなので、手間はエンドポイント1本につき数十行です。

更新系と時間のかかる処理をMCPツールとして公開する前に決めておくこと

削除や送金のような取り消せない操作は、最初の公開では出しません。出すなら、確認用の下書きを作るツールと確定するツールに分け、確定には人の承認を挟みます。エージェントは外部の文書に書かれた指示に引きずられることがあり、Claude Codeの公式ドキュメントも外部の内容を読み込むサーバーにはプロンプトインジェクションの危険があると注意しています。

時間のかかる処理にも注意します。fastapi-mcpの既定のHTTPクライアントはタイムアウトが10秒です。集計やファイル生成で10秒を超えるエンドポイントは、http_client引数にhttpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://apiserver", timeout=60.0)のように長めの設定を渡すか、ジョブの受付と結果の取得に分けます。

社内の業務APIをエージェントへ開放する設計を外部に任せる判断

公開するエンドポイントが数本で、利用者が社内の開発者に限られるなら、この記事の構成で十分に運用できる範囲です。基幹システムのAPIを営業や経理の担当者がエージェント経由で使う段階になると、ツールの粒度の設計、利用者ごとの権限、操作ログの保存、承認の挟み方を一緒に決める必要が出てきます。既存のFastAPI資産を生かしたまま、業務に合わせたエージェントとMCPサーバーを組む作業は、AIエージェント開発の受託で相談を受け付けています。

よくある質問

既存のFastAPIをMCPサーバー化するときに出てくることの多い質問に、2026年11月時点の版で答えます。

fastapi-mcpとFastMCPはどちらを使えばよいですか？

利用者本人のトークンで既存の認可をそのまま効かせたいならfastapi-mcpです。Authorizationを既定で転送するため、既存のDependsが利用者を判定できます。ただし最新版の0.4.0は2025年7月の公開で、mcpを1系に固定して使う前提です。長く保守する前提、またはサービスアカウント1つで足りるならFastMCPを選びます。FastMCPの4系の変更点はFastMCP 4の移行判断の記事にまとめています。

既存のAPIと同じポートでMCPサーバーを動かせますか？

同じポートで動かすことが可能です。mount_http()は既定で同じアプリの/mcpにマウントするので、APIもMCPも同じuvicornのプロセスで動きます。パスを変えたい場合はmount_http(router, mount_path="/my-http")のように指定する方法です。MCP側の負荷をAPIから切り離したい場合は、MCP用に別のプロセスを立てて、そちらから既存APIを呼ぶ構成も取れます。

後から追加したエンドポイントがツールに出てこないのはなぜですか？

ツールの一覧はFastApiMCPを作った時点のルートで組まれるためです。include_routerをFastApiMCPの生成より後に書いていないかを確かめます。どうしても後から足す構成なら、追加のあとにmcp.setup_server()を呼ぶことで反映が可能です。include_tagsで絞っている場合は、追加したルートにタグが付いているかも見ます。

SSEにしか対応していないMCPクライアントからも接続できますか？

接続できます。公式のMCP Transportのとおり、mount_http()と並べてmount_sse()を呼ぶと、/sseでSSEの接続も受けられます。0.4.0ではStreamable HTTPが推奨で、SSEは古いクライアントとの互換のために残された扱いです。新しく登録するクライアントは/mcpに向けます。

ツールの呼び出しが10秒で失敗するのはなぜですか？

fastapi-mcpの既定のHTTPクライアントのタイムアウトが10秒だからです。エンドポイントの処理が10秒を超えると、ツールの呼び出しの結果は失敗です。http_client引数にASGIで同じアプリを呼ぶhttpx.AsyncClientを、長めのタイムアウトを付けて渡すと延ばせます。数分かかる処理なら、受付だけを即座に返し、結果を取るツールを別に用意する方が、エージェントの待ち時間も短く済みます。