CH 12 · MCP エコシステムへの接続
この章の目標
dsh の組み込みツール(ファイル読み、コマンド実行、ウェブ検索)は日常利用には十分ですが、外の世界には散らばったツールがたくさんあります —— GitHub、データベース、メモリ、ブラウザ、さまざまな SaaS —— それらは自動であなたの Agent に入りません。この章では MCP エコシステム を接続します:まず MCP とは何か、なぜ dsh では「プラグイン」で接続するのかを説明し、それから Firecrawl MCP サーバーを実操作でマウントし、モデルがそのツールをネイティブツールのように呼べるようにします。
まず理解する:MCP とは何か
MCP(Model Context Protocol) は「AI アプリが外部ツールサーバーにどう接続するか」という一般問題を解くオープンプロトコルです。MCP はツール界の USB-C と思ってください:標準インタフェース、デバイスを何でも挿せる。
MCP エコシステムにはすでに大量の既製 MCP サーバーがあります:
| MCP サーバー | 機能 |
|---|---|
| ファイルシステム | サブディレクトリの読み書き(ローカルディレクトリを Agent に公開) |
| GitHub | Issue 作成、PR 発行、リポジトリ検索 |
| データベース | 各種データベースへのクエリ |
| Memory | 長期メモリへのアクセス(CH 14 で再登場) |
| Browser | ブラウザ制御、ページスクレイピング |
dsh に MCP を接続する方法はその作風にぴったり合っています —— 1 つのプラグイン: @deepseek-ai/dsh-mcp-client。この公式プラグインの役割はシンプルで、あなたが宣言したすべての MCP サーバーに接続し、それらが提供するツールを ctx.tools(CH 11 で触れたツールレジストリ)に登録すること。だからモデルの目には、それらはネイティブツールと区別がつきません。これも CH 08 の「すべてはプラグイン」を改めて裏付けます —— MCP 統合も例外ではない。
前もって知っておきたいポイント:
- ツール名は 2 階層:まず MCP サーバー(例:Firecrawl)があり、その下に複数のツールがあります(
firecrawl_scrapeページスクレイプ、firecrawl_searchウェブ検索、firecrawl_mapサイトマップ列挙...)。接続後は各ツールがmcp__<サーバー名>__<ツール名>として現れます —— サーバー名がfirecrawlなら、そのスクレイプツールはmcp__firecrawl__firecrawl_scrape。これは Claude Code や Codex の命名形式と一致します。異なるサーバー同士は名前を共有しても衝突しません(それぞれ接頭辞が違うため)。 - デフォルトではどのサーバーも有効化されない:プラグインが入っているかどうかは別の話;どのサーバーに接続するかは完全にあなたの宣言次第です。設定がなければ何も接続されません。一度宣言すれば、dsh 起動時にそのサーバーに接続し、ツールがツールリストに登録されます;どのラウンドでどのツールを呼ぶかは、そのときどきでモデルが自分で選びます —— 毎回すべてのツールを呼ぶわけではありません。
- 現状ブリッジしているのは「ツール」のみ:MCP プロトコルには「ツール」(Tool、呼び出し可能なアクション)の他に、「Resources」(Resource、読み取り専用のデータ/ファイル) と「Prompt テンプレート」(Prompt) の 2 つの能力があります。dsh のブリッジプラグインは現状「ツール」だけを取り込みます;Resources と Prompt テンプレートはまだ使えません。
- 多くのサーバーは認証が必要:GitHub や Firecrawl のような実サービスに接続する MCP サーバーは通常 API Key やトークンを必要とします。キーは設定の
headersフィールド(HTTP 方式)を介して渡し、設定ファイルにハードコードしないでください —— 設定セクションで詳しく説明します。
実操作:初めての MCP サーバーを接続 —— Firecrawl
Firecrawl(実際のウェブスクレイピング MCP サービス、Firecrawl サイト)を例に説明します。その MCP サーバーはウェブ系ツールを多数提供:firecrawl_scrape(単一ページ取得)、firecrawl_search(ウェブ検索)、firecrawl_map(サイトマップ列挙)、firecrawl_crawl(サイト全体を巡回)、firecrawl_extract(構造化フィールド抽出)、など。
ステップ 1:MCP Client プラグインが入っているか確認
まず dsh-mcp-client があるかどうか確認します。コマンドラインは不要、Web UI のプラグインリストを直接見ます:設定 → プラグイン を開き、mcp を検索。下の画像は私の結果 —— 検索ボックスに mcp を入力すると、プラグインリストが空になり(「一致するプラグインなし」)、つまりインストールされていません:
リストに見つからなければ、コマンドラインに戻り web profile の依存としてインストールします:
dsh plugin --profile web add @deepseek-ai/dsh-mcp-client注意:このコマンドは単にそれを profile にパッケージ化するだけです(dsh plugin list --profile web で依存に表示される)、それだけでは起動しません —— プラグインを実際にロードするには、ステップ 3 で cordis.patch.yml に insert し、サーバーの設定が必要です。実測からの落とし穴:insert だけでサーバー設定がないと、dsh 起動時に直接 Cannot read properties of undefined (reading 'serverName') と報告されます、なぜなら serverName は必須フィールドだからです。
設定と dsh の再起動後、もう一度 設定 → プラグイン を見ると、mcp-client が現れ、状態は「有効」(下の画像はインストール後で、検索ボックスにはまだ mcp が入力され、プラグインリスト 1 件、状態有効):
ステップ 2:Firecrawl API Key を取得
Firecrawl は認証が必要です。Firecrawl サイト にログインし、登録して API Key を作成 —— 公式の使い方はそれを Bearer トークンとして https://mcp.firecrawl.dev/v2/mcp に送る形です。無料枠は月 1000 credits。
下の画像は私が作成したページ:左にクレジット残量、中央にデフォルトキーがリストされ(fc- 接頭辞、中央は脱敏)、右上に + Create:
キーを取得したら、まずシステム環境変数として設定します(ステップ 3 の設定からそれを参照します)。1 つ明確にしておきます:環境変数はテキストファイルに書かれるものではなく、Windows システム UI で統一的に維持される「リスト」です;設定画面はこのリストに 1 行追加します。Windows では GUI を使います、コマンドは不要:
Winキーを押し、「環境変数」と入力、システムの環境変数の編集 を開く- 右下の環境変数 ボタンをクリック
- ユーザー環境変数 セクションで新規 をクリック:変数名に
FIRECRAWL_API_KEY、変数値にfc-your-full-keyを入力
- OK を押してウィンドウを閉じる
注意:設定後、新しいターミナルを開いて dsh を起動してください —— すでに開いているウィンドウは新しく設定した環境変数を自動的には読み取りません。
ステップ 3:profile 設定で Firecrawl を宣言
MCP サーバーの設定は web profile の patch ファイル(CH 08 の cordis.patch.yml)に書きます:
- Windows:
C:\Users\<ユーザー名>\.dsh\profiles\web\cordis.patch.yml - macOS / Linux:
~/.dsh/profiles/web/cordis.patch.yml
insert リストにサーバーを追加し、公式推奨の streamable-http 方法を使います(リモートエンドポイントに接続):
各 insert エントリで
serverNameは必須(ステップ 1 の起動エラーはこれが空だったため) —— ツール名の名前空間であり、mcp__<ここ>__toolの形を決めます。
Firecrawl 公式のリモートエンドポイントは https://mcp.firecrawl.dev/v2/mcp、Bearer トークンで認証:
- insert:
- id: mcp-firecrawl
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: firecrawl
transport: streamable-http
url: https://mcp.firecrawl.dev/v2/mcp
headers:
Authorization: !!js '`Bearer ${process.env.FIRECRAWL_API_KEY}`'キーは環境変数(process.env.FIRECRAWL_API_KEY)経由で参照し、ファイルに直接ハードコードしません(環境変数の設定方法はステップ 2) —— Git にコミットされれば漏洩のリスクがあります。後ほど他の MCP サーバーを接続するには、この形式で insert エントリを追加するだけです。
よくあるフィールドの説明:
| フィールド | 意味 |
|---|---|
serverName | ツール名の名前空間(mcp__<ここ>__tool)、1〜32 文字の英数字とアンダースコア、scope 内で一意 |
transport | stdio(ローカルプログラム)または streamable-http(リモートサービス) |
command / args / env | stdio 用:実行可能ファイル、引数、追加環境変数 |
url / headers | HTTP エンドポイント住所と追加リクエストヘッダー(認証トークンはここ) |
toolCallTimeoutMs | ツール呼び出しごとのタイムアウト(デフォルト 60 秒) |
reconnect | 切断時の自動再接続ポリシー(デフォルト有効、初期バックオフ 500ms 倍々、上限 30s、10 回連続失敗で諦め) |
編集保存後のファイルの様子 —— 新しく追加した insert セクションを蛍光イエローで強調:
ステップ 4:再起動、モデルに呼ばせる
dsh を開き直し、起動完了を待ちます。Firecrawl のツールには専用の「ツール一覧ページ」がないので、確認する最も直接的な方法はモデルに 1 回使わせること:
- セッションで、
Use Firecrawl to scrape the main content of deepseek.comを送る - モデルの返答と軌跡を見る:接続が成功すれば、モデルが
mcp__firecrawl__firecrawl_scrapeを呼び出し、軌跡に TOOL 行が現れ、右側パネルにurlパラメータと取得された markdown 結果が出る
- ツールが入ってこなければ、モデルは明示的に「ここにはこのスクレイプツールを持っていない」と言ったり、単に組み込みのウェブ検索にフォールバックしたりします —— どちらもサーバーが接続されていないことを示します;前節に戻ってトラブルシュート
手間を省きたい?コミュニティプラグインを 2 つ入れる
公式ビルドには「ツール一覧」ページも「プラグイン閲覧」エントリもありません;コミュニティがこの 2 つを埋めており、両方ともコマンド 1 つで済みます:
① プラグインマーケット dsh-market(987 stars):インストール後、設定に「プラグインマーケット」が追加され、カテゴリ別閲覧、検索、コミュニティプラグインの 1 クリックインストールが可能。マーケット経由で入れたプラグインはほぼページ更新だけで有効、dsh の再起動は不要:
dsh plugin --profile web add dshmarket
② MCP 可視化パネル DSH Skill & MCP Panel(108 stars):インストール後、設定に「MCP 管理」が追加され、各サーバーの状態とツール数が直接見え、追加/削除/編集、起動/停止を cordis.patch.yml を編集せず UI で行えます。コマンド入力は不要 —— ① のマーケットで dsh-skill-mcp-panel を直接検索、1 クリックでインストール、ページ更新で有効(ホストレベルの一部プラグインは「再起動が必要」と表示するので、その指示に従ってください):
この 2 つのプラグインが、まさに本章冒頭の一文 —— すべてはプラグイン —— の脚注です:公式 UI にない能力はコミュニティプラグインが埋め、インストールすれば dsh の一部になります。
プラグインのインストールと管理にはもっと多くの門道があります —— コマンドラインでのインストール、bundle 自動マウント、グローバル vs Profile。この章では MCP シナリオで窓を少し開いただけ;後ほど 1 章全体を割いてプラグインインストールを系統的に扱い、そのあとプラグイン開発に進み、シナリオ実操作へとつないでいきます。
よくある問題
| 問題 | 対処 |
|---|---|
| 接続したのにツールが見えない | まずログで接続/検出エラーを確認;サーバー自体が到達可能か確認(ブラウザや curl で直接エンドポイントをテスト);serverName が他のサーバーと衝突していないか確認;認証必要サーバーはキーが正しく渡っているか確認(401/403 は大抵これ) |
| Firecrawl のようなサービスのキーはどこへ | 設定の headers を介して渡す(HTTP 方式)、起動前にキー用の環境変数を設定(ステップ 2)、cordis.patch.yml にハードコードしない —— Git にコミットされれば漏洩のリスク |
| サーバーが落ちたら? | プラグインは自動再接続(初期バックオフ 500ms 倍々)、再接続中もツールはリストされるが呼び出しは失敗する;10 回連続失敗で設定リロードまたは再起動までツールは削除される。設定を編集すればサーバー接続は即時リロード、名前は変わらない |
| トークンを食い過ぎる? | 各サーバーのツール説明と入力スキーマが毎回リクエストに乗る。実際に使う分だけ接続、山ほど溜め込まない |
この章で学んだこと
下の項目を自力で達成できれば合格です:
- [ ] MCP の役割と、dsh がどう接続するかを説明できる(1 つのプラグイン
dsh-mcp-client) - [ ] ツール名が 2 階層であることを知っている:1 つの MCP サーバーは複数のツールを持ち、接続後は
mcp__サーバー名__ツール名として現れる - [ ] Firecrawl のような認証必要 MCP サーバーのキーがどう渡されるか、なぜ設定ファイルにハードコードしないかを言える
- [ ]
cordis.patch.ymlで MCP サーバーを宣言できる(stdio か streamable-http の少なくとも 1 つ) - [ ] 実際にモデルに MCP ツールを呼ばせ、軌跡で
mcp__接頭辞付き呼び出しを見られる - [ ] サーバーが接続失敗した・落ちたとき、エラーをどこで見て、どうトラブルシュートするか知っている
- [ ] 手間を省くため、2 つのコミュニティプラグイン(dsh-market:プラグインマーケット、DSH Skill & MCP Panel:MCP 可視化)を入れられることを知っている