概要
- OpenAPI(Swagger)の定義ファイルを渡すだけで、その API を MCP サーバーとして公開する .NET 製 CLI ツールを作りました。
- コードの自動生成も、API を繋ぎこむコードを書くことも不要です。Claude Desktop / Claude Code などの MCP クライアントから、既存の REST API をそのまま呼べます。
- GitHub REST API(1,200 以上のオペレーション)のような巨大な仕様でも破綻しないよう、ツール一覧を畳む仕組みが用意されています
NuGet で公開中です。
dotnet tool install --global McpSense.Tool
背景
REST API を LLM に触らせたいとき、その API に対応した MCP サーバーがあればいちばん楽です。ただ、GitHub のような一部のサービスを除けば、たいていは用意されていません。
そういうとき実際によくやるのは、API のドキュメントや OpenAPI 仕様を LLM に読ませて、リクエスト(curl など)を組み立てさせるやり方だと思います。手軽ですが、気になる点もあります。
- リクエストの組み立てをモデル任せにするので、パスやパラメータを取り違えることがある
- 認証トークンをプロンプトやコマンドに載せることになりがち
- 仕様が大きいと全部は読ませられず、関係しそうな部分だけ切り貼りすることになる
もう少しきちんとやるなら、その REST API をラップした MCP サーバーを書く方法があります。ツールとして形が決まり、認証もサーバー側に隠せる。ただし API ごとに書く手間がかかるので、そこまでするケースはそれほど多くない印象です。
一方で、ラップする MCP サーバーに必要な情報——パス・パラメータ・リクエストボディ・認証方式——は、OpenAPI 仕様にすでに全部書かれています。なら仕様を実行時に読んで、そのまま MCP ツールとして公開すればいいのでは、というのが McpSense の出発点です。
中心に据えた 2 つの機能
正直に言うと、仕様を読んで 1 オペレーション = 1 ツールに変換すること自体は難しくありません。難しいのは、それを実在の API に対して使ったときに出てくる問題のほうです。McpSense はこの 2 点を製品の軸にしています。
1. 大きな仕様でも使えること
数百〜千を超えるオペレーションを持つ API では、全部をツールとして並べると、それだけでモデルのコンテキストを食い尽くします。
GitHub REST API が極端な例です。全オペレーションをそのまま公開すると、ツール一覧(tools/list)は JSON でおよそ 1.8 MB。多くのコンテキストウィンドウに入りません。
McpSense は、オペレーション数が一定(既定 30)を超えると meta-tool モードに切り替わります。個々のツールの代わりに、次の 3 つだけを公開します。
-
search_operations— 自然言語でオペレーションを検索 -
describe_operation— 選んだオペレーションの引数スキーマを取得 -
call_operation— 実際に呼び出す
さらに、仕様がもともと持っているタグを「目次」として提示します。これで GitHub API も、ツール一覧は 約 3 KB(およそ 1/600)に収まります。
モデルからは、こんな 3 ステップに見えます。
search_operations { "query": "認証中ユーザーのリポジトリ一覧", "tag": "repos" }
-> repos_list-for-authenticated-user (GET /user/repos)
repos_list-for-user (GET /users/{username}/repos)
... 他 8 件
describe_operation { "operation": "repos_list-for-authenticated-user" }
-> GET /user/repos と、引数の JSON Schema
call_operation { "operation": "repos_list-for-authenticated-user",
"arguments": { "sort": "updated", "per_page": 2 } }
-> [{ "name": "mcp-sense", "full_name": "pierre3/mcp-sense", ... }]
オペレーション名を前もって全部渡さなくても、「検索 → 詳細 → 呼び出し」でどこにでも辿り着けます。
2. LLMフレンドリー
AIによる名前と説明の書き換え
仕様の名前や説明は、ドキュメントを併読する開発者向けに書かれていて、モデルには不親切なことが多いです。GitHub の仕様には activity_list-repos-starred-by-authenticated-user のような名前が並びます。
McpSenseでは任意のチャットモデルを使ってツール名・説明・パラメータの説明を「何をする操作か・いつ使うか」に書き換えられます。
この機能はオプトインで、モデルを指定しなければ仕様の原文をそのまま使い、AI なしで動きます。
埋め込みモデルによるベクトル検索
ツールの検索は既定では、単語の一致で動きます。listPets を "list" と "pets" に分け、各オペレーションの名前・パス・タグ・説明と照合し、珍しい単語や名前での一致を高く評価する、という素朴な仕組みです。そのため、仕様に書かれている語句に近いことばで検索しないとヒットしない恐れがあります。
埋め込みモデルを指定すると、ここがベクトルの近さによる意味検索に差し替わり、言葉が重ならなくても見つかるようになります(「誰かに画像を送る」で pushImageMessage に届く、といった具合)。
使ってみる
インストール
.NET 10 SDK が必要です。
dotnet tool install --global McpSense.Tool
まず仕様を覗く
dump-operations で、仕様から抽出されたオペレーションを確認できます。引数はローカルファイルでも URL でも、JSON でも YAML でも構いません。
mcpsense dump-operations https://example.com/openapi.yaml
dump-tools を使えば、MCP クライアントが実際に受け取るツール(スキーマ込み)を、サーバーを起動せずに確認できます。モデルが変な引数で呼んでくるときの調査に便利です。
GitHub API で試してみる
仕様を取得します(13 MB あるのでローカル保存推奨)。
curl -sL -o api.github.com.json \
https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
どう解釈されるか見てみます。
mcpsense dump-tools ./api.github.com.json
mode: MetaTool
operations: 1239
advertised: 3
groups: actions (199), activity (34), agents (30), apps (37), billing (13), ...
閾値を超えているので meta-tool モード。あとは fine-grained の personal access token を用意し、MCP クライアント(ここでは Claude Code)に登録するだけです。
{
"mcpServers": {
"github": {
"command": "mcpsense",
"args": [
"mcp",
"C:/path/to/api.github.com.json",
"--bearer-token", "github_pat_...",
"--header", "X-GitHub-Api-Version: 2022-11-28"
]
}
}
}
ベース URL は仕様の servers から取るので指定不要。トークンにできることが、そのままツールでできることになります。権限は絞って渡すのが安全です。
これで「自分のリポジトリの最近の issue を一覧して」「この PR をマージして」といった依頼を、Claude が GitHub API 経由で実行できます。実際に issue 作成・PR 作成・(OAuth 経由での)プライベートリポジトリ参照まで動くことを確認しています。
必要な範囲だけに絞る
issue と PR しか使わない用途なら、範囲を絞って直接公開したほうが快適です。
mcpsense dump-tools ./api.github.com.json --tag issues,pulls --allow "*list*,*get*" --mode direct
--allow で書き込み系を除外すれば、読み取り専用トークンと二重の歯止めになります。
認証まわり
静的なトークンやヘッダ(--bearer-token / --api-key / --header)に加えて、OAuth 2.0 認可コードフロー(PKCE 付き) に対応しています。アクセストークンは自動で更新されるので、PAT の手動更新から解放されます。
ポイントは、認可(ブラウザでの同意)を mcpsense login で事前に一度だけ行うこと。MCP サーバーは stdin/stdout をプロトコルに占有されていてブラウザを開けないので、サーバー自身は保存済みトークンを読んで裏で更新するだけ、という役割分担にしています。
mcpsense login \
--oauth-authorization-endpoint https://github.com/login/oauth/authorize \
--oauth-token-endpoint https://github.com/login/oauth/access_token \
--oauth-client-id <client-id> \
--oauth-scope repo \
--oauth-redirect-port 8765
トークンは Windows では DPAPI で暗号化して保存します。
実装上のポイント
毎回 LLM を叩かないためのキャッシュ
説明の書き換えはバッチ処理し(既定 10 件/リクエスト)、結果をディスクにキャッシュします。仕様が変わらなければ 2 回目以降の起動ではモデルを一切呼びません。CLI は実行のたびにプロセスが終わるので、メモリキャッシュでは意味がなく、ファイルベースにしています。
スキーマは自己完結させる
MCP クライアントは OpenAPI ドキュメントを持ちません。なのでツールのスキーマに $ref が残っていると解決できない。McpSense は公開前にローカル参照をすべて展開します(自己参照するスキーマでも止まります)。
仕様はそのまま受け取る
実際に運用されている仕様は、提供元が公開しているものでも、厳密な OpenAPI 検証には引っかかることが珍しくありません。提供元より厳しくてはプロキシとして使い物にならないので、McpSense はドキュメントがまったく生成できないときだけ失敗とし、それ以外の指摘は「非致命の問題」として報告したうえで動かします。
まとめ
McpSense は、
- OpenAPI 仕様を渡すだけで MCP サーバーになる(コード生成なし)
- 巨大な仕様でもツール一覧を畳んで扱える(meta-tool モード)
- AIを利用した仕様の要約とベクトル化による、ツール選択性能の向上
- PAT および OAuth(自動更新)に対応
というツールです。「手元のあの API を Claude から触りたい」と思ったときに、その API に OpenAPI 仕様さえあれば、その場で試せます。
現在、v1.0.0 としてリリースされています。フィードバックや Issue を歓迎します。
このアプリは .NET tool として動作します。 dotnet tool install して MCP クライアントに登録するだけでお試しいただけます。
おまけ
「OpenAPI 仕様を起点にする」という発想は同じで、性格の違うline-openapi-dotnet というプロジェクトも作っています。
- C# クラスライブラリ。プログラムに組み込んで使う、型付きのライブラリです
- Kiota による自動生成で、LINE の OpenAPI 仕様から C# のクライアントコードを生成しています
本ライブラリを使ったプロジェクトでCLIとしても、MCPとしても動作するツールLine.OpenApi.Tools も公開しています。