Claude Media
ClaudeとMintlifyを連携する方法 — 古いドキュメントを検索して修正する
ClaudeMCPClaude連携チュートリアル

ClaudeとMintlifyを連携する方法 — 古いドキュメントを検索して修正する

MintlifyのadminMCPをClaudeにつなぐと、ドキュメントの検索・編集・差分確認・PR作成まで会話で進められます。接続手順、セッションの流れ、直接公開と設定変更のリスクを扱います。

読了目安 約10分

Claude Mintlify連携とは — 検索用MCPと何が違うか

Mintlify連携とは、Mintlifyが運営する管理用のMCPサーバー(adminMCP、https://mcp.mintlify.com)にClaudeをつなぎ、ドキュメントのページ編集・ナビゲーションの組み替え・docs.jsonの更新・プルリクエスト作成を会話から行えるようにする仕組みです。プロダクトの仕様が変わったあとに、古い記述のページを探して直す作業に向いています。

Mintlifyには似た名前のMCPサーバーが3種類あります。名前だけ見て接続すると、読むだけのつもりが書き込み権限を渡すことになりかねません。

adminMCP検索MCPIndexMCP
対象adminMCP自社チーム検索MCPサイトの読者IndexMCPすべての開発者とエージェント
できることadminMCP読み取り・編集・保存・設定変更検索MCP1サイトの公開ページの読み取りと検索IndexMCP全Mintlifyサイトの読み取りと検索
接続先adminMCPhttps://mcp.mintlify.com検索MCP自サイトの/mcpIndexMCPhttps://index.mintlify.com

この記事で扱うのは左端のadminMCPです。検索MCPは、自サイトのドキュメントを読者のAIツールに引かせるための仕組みで、編集はできません。公開リポジトリのドキュメントを読ませるだけなら、DeepWiki MCPをClaude Codeで使う方法のような読み取り専用の仕組みで足ります。構造化コンテンツのスキーマとドラフトを扱うならClaudeとSanityを連携する方法が別の選択肢です。

接続前に確認する3つの条件

adminMCPはOAuthログインで接続します。クライアントやマシン間トークンだけでは、一部の動作が変わります(後述)。

  • Mintlifyアカウント: 編集したいプロジェクトへのアクセス権が必要です。OAuthセッションはダッシュボードの権限を引き継ぐため、保護された設定の変更(update_configなど)には、プロジェクトの管理者ロールが要ります
  • Gitプロバイダー: GitHub・GitLab・Bitbucketの接続に、デプロイ用ブランチのリポジトリへの書き込み権限が必要です。saveは通常のデプロイと同じ連携でPRを開きます
  • MCPクライアント: Claude、Claude Code、ChatGPT、Cursor、Codexなどがあります

Claudeに接続する手順

claude.aiのコネクタ画面から追加する方法と、Claude Codeのコマンドで追加する方法があります。

手順

claude.aiで追加する流れ

  1. 1

    コネクタ画面を開く

    Claudeの設定にある「Connectors」ページを開き、「Add custom connector」を押します。

  2. 2

    名前とURLを入れる

    名前は「Admin MCP」、URLはhttps://mcp.mintlify.comです。

  3. 3

    OAuthログインを済ませる

    「Add」を押し、Mintlifyアカウントでログインします。

  4. 4

    会話で有効にする

    入力欄のプラスアイコンから、追加したadminMCPを選びます。

Claude Codeなら1行です。

claude mcp add --transport http mintlify https://mcp.mintlify.com

初回の利用時にブラウザーが開き、OAuthログインを求められます。認証後は同じセッションが再利用されます。

接続できる範囲は、ログイン時にどう許可したかで決まります。特定のプロジェクトに絞った接続は、そのプロジェクトだけをチェックアウトできます。組織全体で許可した接続は、組織内のどのプロジェクトでもチェックアウトできます。社内にドキュメントが複数あるなら、最初は対象を絞った許可のほうが誤操作の範囲を小さくできます。

1回の作業はブランチ単位で進む

adminMCPのセッションは、1つのGitブランチに紐づきます。Claudeが呼ぶツールの順序は次のとおりです。

手順

セッションの基本の流れ

  1. 1

    list_deployments

    複数のプロジェクトにアクセスできる場合だけ、チェックアウト可能なsubdomainを確認します。

  2. 2

    checkout

    最初に必須の呼び出しです。デプロイ用ブランチからadmin-mcp/で始まる新しいブランチを作り、ダッシュボードのエディターで進行を追えるeditorUrlを返します。既存のブランチ名を指定して、そこに接続することもできます。

  3. 3

    search / read / edit_page など

    ページの検索・読み取り・編集をします。編集はセッションのブランチに溜まり、この時点ではデプロイ用ブランチに触れません。

  4. 4

    diff

    デプロイ用ブランチとの差分を確認します。

  5. 5

    save

    ブランチをGitに反映します。既定ではPRが開きます。

checkoutのときにslugを渡すと、ブランチ名が読みやすくなります。渡さない場合、ブランチ名はセッショントークン由来で、リポジトリ上で見分けにくくなります。やり直したいときはdiscard_sessionでセッションの変更をすべて破棄し、ブランチを解放します。

古い記述を探して直す — 公式の例をもとにした進め方

プロダクト変更後のドキュメント修正は、「該当箇所の洗い出し」と「一括置換」と「確認」に分かれます。公式のプロンプト例には、廃止予定のlegacy_tokenフィールドを言及するページをすべて探し、例をapi_keyに直して「docs: replace legacy_token references」というタイトルのPRとして保存する指示があります。これを土台にすると、次のような依頼になります。

add-api-key-migration というスラッグでチェックアウトして。
legacy_token に触れているページをすべて検索し、一覧を先に見せて。
一覧に問題がなければ、例を api_key に直して diff を見せて。
PR のタイトルは「docs: replace legacy_token references」で保存して。

ここでの工夫は、検索結果を先に出させてから編集に進ませる点です。searchは部分文字列か正規表現に一致する行を全ページから探します。ヒットした行を人が見て、本当に直すべき記述か(移行の説明文としてlegacy_tokenを残すべき箇所ではないか)を確認してから、edit_pageに進ませます。

編集に使うツールは2つあります。

  • edit_page: ページへの的を絞った編集。一部の文だけを直すときに使います
  • write_page: ページのMDX全体を上書きします。構成ごと書き換えるときに限り、差分が大きくなるのでdiffで確認します

新規ページはcreate_nodeで作ります。ナビゲーションの組み替えはmove_nodeやupdate_node、設定の変更はupdate_configで行います。ナビゲーションが不正な状態になると、応答にnavigationErrorsが付きます。この状態だとMintlifyが無効なノードを公開ナビゲーションから外すことがあるため、saveの前に直す必要があります。

saveの3つのモードと、直接公開の落とし穴

saveはmodeで動きが変わります。

mode動き
auto(既定)動きPRを開く。プロジェクトの設定がmainへの直接pushで、デプロイ用ブランチが保護されていなければ、PRがその場でマージされる
pr動き常にPRを開き、レビュー待ちで残す
commit動き既存のPRブランチへ直接pushし、新しいPRは開かない

既定のautoは、ダッシュボードの管理用MCP設定にある「Push directly to your deploy branch」の切り替えに従います。オフならPRが開き、オンならマージまで進みます。この切り替えは、Slackやダッシュボードのエージェントが使うレビュー設定と共通なので、変えるとそちらの動きも変わります。

切り替えが操作できない場合が3つあります。

  • デプロイ用ブランチがPRを必須にしている(ブランチ保護や承認ルール)と、設定にかかわらず常にPRになります
  • Mintlifyがホストするプロジェクトでは、MCP経由の変更は直接pushされます。ただしブランチ保護でPRが必須なら、PRになります
  • 管理者ロールがないと変更できません。編集者と閲覧者には操作不可の表示が出ます

レビューを必ず挟みたいなら、saveのたびにmode: "pr"を明示するよう指示しておくと、設定に左右されません。

デプロイ用ブランチを直接編集するとき

checkoutのbranchにデプロイ用ブランチ(たとえばmain)を渡すと、admin-mcp/のセッションブランチもPRも作られず、ダッシュボードエディターの「Publish」と同じ形で編集します。注意点が3つあります。

  • 編集は同じブランチを開いている共同編集者にリアルタイムで見えます
  • saveは自分の変更だけをデプロイ用ブランチに直接コミットします。モードは無視されます。ダッシュボードエディターで自分が公開していなかった編集も一緒に公開されます
  • Mintlifyは変更をページ単位で追うため、同じページを別の人も編集していると、そのページ全体が公開されたり、discard_sessionで元に戻ったりします

ブランチ保護でPRが必須の場合や、ダッシュボードの設定で直接公開が無効な場合、あるいはOAuthではなくクライアントトークンで接続した場合は、自動でセッションブランチに切り替わります。checkoutが返すnoteに理由が書かれます。

プロジェクト管理系のツールはPRを経由せず即時反映される

adminMCPはページ編集だけでなく、プロジェクト管理系のツールも持ちます。ワークフローの作成と実行、カスタムドメイン、Gitソース、サイトの認証、メンバーとロール、アナリティクスの閲覧などです。

種類ツール備考
読み取りツールget_deployment_settings / get_analytics_report / get_workflows / list_repos_and_prs備考subdomainsで最大25プロジェクトをまとめて読める
書き込みツールupdate_deployment_settings / manage_custom_domain / manage_git_source / manage_access_auth / manage_workflow / manage_members_sharing備考checkoutは不要。ブランチもPRも作らず即座に反映

書き込み系の応答には更新後の状態がstateとして入るため、Claudeは追加の呼び出しなしで反映結果を確かめられます。権限のない操作にはinsufficient_scopeのようなエラーが返ります。

ドキュメントの修正だけが目的なら、会話の冒頭で「設定やワークフローには触らず、ページの検索と編集と保存だけを使う」と範囲を宣言しておくと、意図しない変更を減らせます。

運用のコツと後始末

公式のベストプラクティスから、ドキュメント修正の運用に効く点を挙げます。

  • 1つのセッションは1つの変更に絞ります。PRが読みやすくなり、エージェントの文脈も節約できます。別の作業に移るときはdiscard_sessionのあとにcheckoutし直します
  • 数百ページを1回で書き換えられるだけの力があります。マージ前にPRの差分を読み、レンダリングされたプレビューも流し見します
  • セッションを保存も破棄もせず放置すると、次のcheckoutが上書きするまでブランチが残ります。古いadmin-mcp/ブランチはときどき掃除します

接続を切るには、Mintlifyダッシュボードの「Settings → Security & access → Connected apps」で該当のアプリを取り消します。取り消すとアクセストークンは30秒以内に無効になります。Claude側では、Claudeの「Settings → Connectors」で該当のコネクタを削除するか、Claude Codeならclaude mcp remove mintlifyを実行します。取り消しても、すでに開いたPRには影響しません。取り消したい変更は、Gitプロバイダー上でPRを閉じるか差し戻します。

まとめ

adminMCPは「ブランチで編集し、diffで確認し、PRで確定する」流れが標準で、Gitの運用に素直に乗ります。例外は2つです。直接公開の設定がオンだとPRがその場でマージされること、プロジェクト管理系のツールはPRを経由せず即座に反映されることです。この2点をあらかじめ把握し、mode: "pr"の明示と範囲の宣言を習慣にすると、古いページの一括修正を安全に任せられます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude をもっと見る →