ClaudeとSwaggerを連携する方法 — API設計の検証とポータル公開を会話で扱う
SmartBearのSwagger MCPサーバーをClaudeにつなぐ手順です。OAuthログインだけで済む認証、Studioとポータルの2系統のツール、公開や削除を任せる前の確認点をまとめます。
Claude Swagger連携とは何か
Swagger連携は、SmartBearが提供するリモートMCPサーバーをClaudeに接続し、APIの設計・検証・ドキュメント公開を会話から操作する仕組みです。サーバーURLは https://swagger.mcp.smartbear.com/mcp で、ローカルへのインストールは要りません。
Connectorsディレクトリの掲載名は「Swagger」で、開発元はSmartBear、表示は「Anthropic verified」です。カテゴリはDeveloper tools、追加時期は2026年5月、サインインは必須です。説明文は「Build, govern, and document APIs」の一言で、中身は次の2系統に分かれます。
- Swagger Studio:APIとドメインの定義をレジストリで管理し、組織の規約で検査する
- Swagger Portal:ポータルとプロダクト、ドキュメントページ、目次を作って公開する
OpenAPIの検証そのものはローカルでも回せます。手元のリポジトリで編集のたびにlintを走らせる構成はClaude CodeでOpenAPIをSpectralでlintする設定が詳しいです。Swagger連携が効くのは、検査ルールや定義がSwaggerHub側(Studio)に集約されていて、組織共通の規約をそのまま当てたい場面です。
Connector全般の仕組みはClaude Connectorsの解説にあります。
接続手順:OAuthログインだけで済む
提供元のドキュメントは、リモート版の認証を「初回接続時にブラウザが開き、SmartBearのOAuthログインを行う」と説明しています。APIトークンも環境変数も要りません。
ClaudeのWeb・Desktopから追加する
ディレクトリの「Add to Claude」から追加するのが最短です。ドキュメントには、カスタムコネクタとして追加する導線も用意されています。
カスタムコネクタでSwaggerを追加する流れ
- 1
コネクタの追加画面を開く
ClaudeのConnectors設定で「Add custom connector」を選びます。
- 2
名前とURLを入れる
名前は
Swaggerなどにし、URLにhttps://swagger.mcp.smartbear.com/mcpを入れます。 - 3
SmartBearでログインして承認する
追加するとブラウザでSmartBearのOAuthログイン画面が開きます。ログインして接続を承認します。
- 4
有効になっているか確かめる
Claudeに戻り、Swaggerのコネクタが有効で、ツールが一覧に出ていることを見ます。
Claude Desktopには、設定ファイル claude_desktop_config.json に書く方式と、ドキュメント上の「Add to Claude」ボタンから入れる方式が案内されています。画面に出る方を使えば足ります。
Claude Codeから追加する
Claude Codeには、コマンド1本で登録する例が載っています。
claude mcp add --transport http smartbear-swagger \
https://swagger.mcp.smartbear.com/mcp登録後にClaude Codeを起動し、/mcp でswaggerのサーバーを選ぶと、ブラウザでOAuthログインが始まります。コマンドの書式やJSONでの登録はclaude mcp add-jsonの手順で扱っています。
同じドキュメントには、Cursor、VS Code(GitHub Copilot)、Kiroへの追加例もあります。URLはどれも共通です。
認証と権限:リモート版とローカル版で違う
認証まわりで押さえる点は3つです。
| 項目 | リモート版(本記事の接続) | ローカル版のMCPサーバー |
|---|---|---|
| 認証方式 | リモート版(本記事の接続)SmartBearのOAuthログイン | ローカル版のMCPサーバーSwagger APIトークンを環境変数で渡す |
| 事前準備 | リモート版(本記事の接続)なし | ローカル版のMCPサーバートークンの発行と設定 |
| オンプレミス | リモート版(本記事の接続)ページに記載なし | ローカル版のMCPサーバー環境変数でAPIの基準パスを差し替える |
ローカル版を使う場合、StudioとPortalのページでは、Swagger APIトークンを環境変数に設定する手順が案内されています。オンプレミスのSwagger Studioでは、SWAGGER_UI_BASE_PATH、SWAGGER_REGISTRY_BASE_PATH、SWAGGER_PORTAL_BASE_PATH で各APIの基準パスを指定します。
OAuthで付与される権限の範囲(スコープ)の一覧は、リモート版のページに載っていません。実際に何ができるかは、ログインしたアカウントがSwagger側で持つ組織・ポータルへのアクセス権に左右される、と考えるのが無難です。最初は読み取り中心の依頼で動きを見る進め方が取れます。
使えるツール:Studio系とPortal系
Connectorsディレクトリには22個のツールが並びます。役割で分けると次のとおりです。
Swagger Studio系(API・ドメインの管理)
| ツール | できること |
|---|---|
search_apis_and_domains | できることAPIとドメインを名前や説明の自由検索で探す |
get_api_definition | できること所有者・API名・バージョンを指定して定義を取得する |
create_or_update_api | できることOpenAPI/AsyncAPIの定義を新規作成、または同名APIを更新する |
create_api_from_prompt | できること自然文の説明からAPIを生成して保存する |
scan_api_standardization | できること渡した定義を組織の規約で検査する |
standardize_api | できること規約違反をAIで直し、結果を保存する |
流れは「作る → 検査する → 直す」です。ドキュメントは、create_api_from_prompt で試作したAPIを、検査と自動修正で組織の基準に合わせる使い方を挙げています。
Swagger Portal系(ポータルとドキュメント)
| 対象 | ツール |
|---|---|
| ポータル | ツールlist_portals / get_portal / create_portal / update_portal |
| プロダクト | ツールlist_portal_products / get_portal_product / create_portal_product / update_portal_product / delete_portal_product / publish_portal_product |
| 構成 | ツールlist_portal_product_sections / create_table_of_contents / list_table_of_contents / delete_table_of_contents |
| 本文 | ツールget_document / update_document |
ポータルは製品ドキュメントのサイトで、その中に「プロダクト」(APIごとの単位)、さらにセクションと目次、ページが入ります。上の表は、ディレクトリの一覧をこの階層で並べ直したものです。
提供元ドキュメントにあってディレクトリ一覧に無いツール
提供元のStudio・Portalのページには、ディレクトリの22個に入っていない名前が出てきます。
- Studio側:
validate_api(構造の検証)、patch_api(定義の一部だけ書き換え)、scan_api_standardization_from_registry(レジストリ上のAPIを名前で指定して検査)、list_organizations - Portal側:
create_documentation_page(1回の呼び出しでページを追加)、resolve_organization_portal
ディレクトリの一覧と提供元ドキュメントで、ツールの数と名前がずれている状態です。ずれの理由は両方の資料に書かれていません。Claude上で実際に使えるツールは、接続後のツール一覧で確かめてください。
書き込み系を任せる前に知っておく挙動
このコネクタは読むだけではありません。作成、更新、削除、公開まで通ります。ドキュメントに書かれた挙動のうち、事故につながりやすいものを挙げます。
動かす前に見ておく挙動
公開の既定はライブ
publish_portal_productは、プレビューか本番かを選ぶパラメータの既定がライブ公開です。試すときはpreviewをtrueにするよう依頼文で明示します。新規APIは非公開・1.0.0で作られる
create_or_update_apiで新規作成すると、バージョン1.0.0・非公開・モックなしの固定値になります。既存APIの更新では、既存の公開設定が保たれます。修正結果はレジストリに保存される
standardize_apiは、規約違反をAIで直した定義を保存し直す仕様です。検査だけしたいならscan_api_standardizationを使います。目次の削除は連鎖する
delete_table_of_contentsはソフト削除で、子の項目まで再帰的に消せます。対応するページの本文も、目次の項目と一緒に取り除かれます。
もう一つ、create_api_from_prompt は、同じAPI名・バージョンがすでにあると競合エラーで失敗します。上書きする道具ではないので、更新したいときは create_or_update_api に切り替えます。
プロダクトの公開範囲(update_portal_product)にも注意が要ります。公開フラグをtrueにすると全訪問者に見え、falseなら役割を持つ認証済みユーザーに限られます。説明文の上限は110文字、プロダクト名は3〜40文字、スラッグは3〜22文字といった制約もあり、長い名前を頼むとエラーで返ります。
変更前に確認させる規約の例
Claude CodeならCLAUDE.mdに、変更系の扱いを書いておけます。次は一例で、文言は運用に合わせて調整してください。
## Swagger MCPの扱い
- 検索・取得・検査(scan)は、確認なしで実行してよい
- 作成・更新・standardize・削除の前に、対象のowner/API名/バージョンと
変更内容を示し、承認を待つ
- ポータルの公開は、先にpreviewで行い、URLを報告してから本番に進む業務での使いどころ
組織共通のルールがSwagger Studioにあり、APIが複数チームで増えていく環境ほど効果が出ます。
新しいAPIを規約付きで立ち上げる
自然文で「注文を作成・取得するREST API」と頼み、create_api_from_prompt で下書きを作ります。作成時に組織の規約が適用されると説明されているため、ゼロから書くより規約違反が少ない状態で始められます。その後に scan_api_standardization で指摘を確認します。
既存APIの規約違反をまとめて洗う
古い定義を引き継いだチームでは、search_apis_and_domains で対象を絞り、get_api_definition で中身を見て、scan_api_standardization で指摘の数と重大度別の件数を出せます。直す前に件数を確かめ、そのうえで standardize_api に進む順序が安全です。
変更したAPIのドキュメントを同期する
APIを更新したあと、ポータルのページ本文を get_document で読み、差分に合わせて update_document で書き換える流れが取れます。ただし、一部の文書種別はAPIから編集できない旨がドキュメントに明記されています。UIで管理されているページは、先に編集可能かを確かめます。
依頼文の一例を挙げます。読み取りと変更を分けて頼むと、途中で止めやすくなります。
orderチームのAPIを検索して、一覧を出してください。
その中から order-service の最新バージョンを検査し、
規約違反を重大度別に集計してください。
定義の保存や修正は、私が指示するまで行わないでください。よくあるつまずき
- ログイン画面が出ない:クライアントがOAuthに対応していないか、カスタムコネクタの追加が途中で止まっています。Claude Codeなら
/mcpで状態を見て、再接続を試します。 - ツールの数が資料と合わない:ディレクトリの22個と提供元ドキュメントの一覧は一致しません。接続後のツール一覧を基準にします。
- ページ作成がエラーになる:タイトルは3〜255文字、スラッグは小文字英数字とハイフン・アンダースコア・ドットなどの範囲で、条件を満たさないと失敗します。内容の形式(HTMLかMarkdown)の組み合わせにも制限があります。
まとめ
Swagger連携の入口は軽く、URLを登録してOAuthでログインすれば始められます。重いのは入口ではなく、その先の書き込み系です。ポータルの公開は既定がライブで、standardize_api は直した定義を保存します。読み取りの依頼で慣れ、変更の前に対象と内容を示させる運用を先に決めておくと、組織共通の規約を会話から使いこなせます。