Merge pull request #312 from langgenius/mcp-integration

Add translation for MCP
2026-03-27 13:28:32 +07:00 · 2025-07-10 16:25:31 +09:00
parent 6bbeb9e8c4 0efab321bd
commit 85f7a55d91
6 changed files with 541 additions and 0 deletions
--- a/docs.json
+++ b/docs.json
@@ -793,6 +793,7 @@
                                        "group": "工具",
                                        "pages": [
                                            "zh-hans/guides/tools/readme",
+                                            "zh-hans/guides/tools/mcp",
                                            "zh-hans/guides/tools/quick-tool-integration",
                                            "zh-hans/guides/tools/advanced-tool-integration",
                                            {
@@ -825,6 +826,7 @@
                                                    "zh-hans/guides/application-publishing/launch-your-webapp-quickly/conversation-application"
                                                ]
                                            },
+                                            "zh-hans/guides/application-publishing/publish-mcp",
                                            "zh-hans/guides/application-publishing/embedding-in-websites",
                                            "zh-hans/guides/application-publishing/developing-with-apis",
                                            "zh-hans/guides/application-publishing/based-on-frontend-templates"
@@ -1461,6 +1463,7 @@
                                                    "ja-jp/guides/application-publishing/launch-your-webapp-quickly/conversation-application"
                                                ]
                                            },
+                                            "ja-jp/guides/application-publishing/publish-mcp",
                                            "ja-jp/guides/application-publishing/embedding-in-websites",
                                            "ja-jp/guides/application-publishing/developing-with-apis",
                                            "ja-jp/guides/application-publishing/based-on-frontend-templates"
@@ -1511,6 +1514,13 @@
                                            }
                                        ]
                                    },
+                                    {
+                                        "group": "ツール",
+                                        "pages": [
+                                            "ja-jp/guides/tools/types-of-tools",
+                                            "ja-jp/guides/tools/mcp"
+                                        ]
+                                    },
                                    {
                                        "group": "コラボレーション",
                                        "pages": [
--- a/ja-jp/guides/application-publishing/publish-mcp.mdx
+++ b/ja-jp/guides/application-publishing/publish-mcp.mdx
@@ -0,0 +1,66 @@
+---
+title: "DifyのアプリをMCPサーバーとして公開"
+---
+
+Difyがアプリケーションを[MCP](https://modelcontextprotocol.io/introduction)（モデルコンテキストプロトコル）サーバーとして公開できるようになりました。これにより、Claude Desktop のような AI アシスタントや Cursor のような開発環境とのシームレスな統合が可能になります。これらのツールは、まるでネイティブな拡張機能のように、Difyアプリと直接やり取りすることができます。
+
+<Note>
+  Difyのワークフローやエージェント内でMCPツールを使用する方法については、[こちら](/ja-jp/guides/tools/mcp)を参照してください。
+</Note>
+
+## DifyアプリをMCPサーバーとして設定
+
+Difyのアプリケーション設定ページに移動すると、MCPサーバー設定モジュールが表示されます。デフォルトで無効化されていますが、有効化するとDifyがアプリケーション用のユニークなMCPサーバーアドレスを生成します。このアドレスは、外部ツールが接続するための接続点として機能します。
+
+<Danger>
+  生成されたMCPサーバーURLには認証情報が含まれているため、APIキーのように扱ってください。もし漏洩の恐れがある場合は、「regenerate」ボタンを使用して新しいURLを作成してください。古いURLはすぐに無効になります。
+</Danger>
+
+<img
+  src="/images/CleanShot2025-07-07at08.18.02.png"
+  alt="CleanShot 2025-07-07 at 08.18.02.png"
+  title="CleanShot 2025-07-07 at 08.18.02.png"
+  className="mx-auto"
+  style={{ width:"46%" }}
+/>
+
+## Claude Desktop との統合
+
+DifyアプリをClaude Desktopに接続するには、Claudeとの統合を追加する必要があります。Claude Profile > Settings > Integrations > Add integration に移動してください。統合URLをDifyアプリのサーバーURLに置き換えてください。
+
+## Cursor との統合
+
+Cursorに対しては、プロジェクトのルートにある `.cursor/mcp.json` ファイルを作成または編集します：
+
+```json
+{
+  "mcpServers": {
+    "your-server-name": {
+      "url": "your-server-url"
+    }
+  }
+}
+```
+
+指定された URL を Dify アプリの MCP サーバーアドレスに置き換えてください。Cursor はこの設定を自動的に検出し、あなたの Dify アプリをツールとして利用可能にします。`mcpServers` オブジェクトに追加のエントリーを含めることで、複数の Dify アプリを追加することもできます。
+
+## 実用的な考慮事項
+
+- 説明
+
+  ツールとその入力パラメータの説明を編成する際、AIがそれをどのように解釈するかを考慮することをお勧めします。明確で具体的な記述を心がけることで、より良い呼び出しを引き出します。「入力データ」とするのではなく、「必須フィールド（名前、メールアドレス、好み）を含むユーザープロファイルのJSONオブジェクト」と具体的に記述してください。
+
+- レイテンシ
+
+  MCPプロトコルは通信層を扱いますが、Difyアプリのパフォーマンスも重要です。アプリの処理に通常30秒かかる場合、その遅延がクライアントアプリケーションにも影響します。進捗状況を表示したり、複雑なワークフローをより小さく迅速な操作に分割したりすることを検討してください。
+
+{/*
+Contributing Section
+DO NOT edit this section!
+It will be automatically generated by the script.
+*/}
+
+---
+
+[このページを編集する](https://github.com/langgenius/dify-docs/edit/main/ja-jp/guides/application-publishing/publish-mcp.mdx) | [問題を報告する](https://github.com/langgenius/dify-docs/issues/new?title=ドキュメントの問題%3A%20sh-&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs%2Fblob%2Fmain%2Fja-jp/guides/application-publishing%2Fpublish-mcp.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E)
+
--- a/ja-jp/guides/tools/mcp.mdx
+++ b/ja-jp/guides/tools/mcp.mdx
@@ -0,0 +1,182 @@
+---
+title: "MCPツールの活用"
+---
+
+外部の[MCP](https://modelcontextprotocol.io/introduction)サーバーが提供する[ツール](https://modelcontextprotocol.io/docs/concepts/tools)を直接 Dify Agent やワークフローで利用できます。既存のDifyプラグインに制限される代わりに、特定の機能を提供する成長している MCP サーバーの[エコシステム](https://mcpservers.org/)を活用できます。
+
+<Note>
+  この記事では、Dify内でMCPツールを使用する方法を解説します。Difyアプリケーションを MCP サーバーとして公開する方法については、[こちら](https://mcpservers.org/en/guides/application-publishing/publish-mcp)をご覧ください。
+</Note>
+
+<Info>
+  現在、[HTTPトランスポート](https://modelcontextprotocol.io/docs/concepts/architecture#transport-layer)をサポートしている MCP サーバーのみが利用可能です。
+</Info>
+
+## MCPサーバー管理へのアクセス
+
+Difyワークスペースの**ツール** → **MCP**に移動します。ここでは、アプリケーション用にツールを提供する全ての外部MCPサーバーを管理します。
+
+![6cef1436fcc13a65ccedb54bcf5ab77eb87b8faba1098a85951839fb1907f2d2.png](/images/6cef1436fcc13a65ccedb54bcf5ab77eb87b8faba1098a85951839fb1907f2d2.png)
+
+## MCPサーバーの追加
+
+<img
+  src="/images/b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
+  alt="b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
+  title="b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
+  className="mr-auto"
+  style={{ width:"70%" }}
+/>
+
+**MCP Server (HTTP)を追加** をクリックして、新しい外部ツールプロバイダーに接続します：
+
+* **サーバーURL**: MCPサーバーのHTTPエンドポイント（例: `https://api.notion.com/mcp` はNotionとの統合に用いるためのHTTPエンドポイントです）。
+
+* **名前とアイコン**: 提供されるツールを説明する名前を付けます。Difyは可能な限りサーバーのドメインからアイコンを自動で取得し、自分で選ぶこともできます。
+
+* **サーバーの識別**: Difyがこのサーバーを管理するために使用するユニークなID（小文字、数字、アンダースコア、ハイフン、最大24文字）。
+
+<Warning>
+  サーバーIDは設計上永久的です。これを変更すると、このサーバーのツールを使用している既存の Agent やワークフローが機能しなくなります。これは[アプリケーションのポータビリティ](##application-portability)にとって重要です。
+</Warning>
+
+## 認証とツールの発見
+
+サーバーを追加した後、Difyは自動的に以下を行います：
+
+1. **利用可能なツールの検出**: サーバーが提供する機能をチェックします。
+2. **認証処理**: サーバーが認証を必要とする場合、OAuthフローを開始します。
+3. **ツール定義の取得**: アプリケーションで使用できるようツールのスキーマをダウンロードします。
+4. **ツールのインベントリを更新**: Agent やワークフロービルダーでツールを使用できるようにします。
+
+Difyが少なくとも1つの使用可能なツールを正常に取得するとサーバーカードが追加されます：
+
+![fcef5ecad1deca82a1d8988c4bcb7cec745a0cd47945ff05fca588502cfaafbc.png](/images/fcef5ecad1deca82a1d8988c4bcb7cec745a0cd47945ff05fca588502cfaafbc.png)
+
+## 接続されたサーバーの管理
+
+サーバーカードをクリックすると、以下ができます：
+
+* **ツールの更新**: サーバーから入手可能なツールを更新します。外部サービスが新しい機能を追加した場合に使用します。
+
+  <img
+    src="/images/7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
+    alt="7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
+    title="7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
+    className="mx-auto"
+    style={{ width:"59%" }}
+  />
+
+* **再認証**: 認証ステータスをクリックして権限を更新します。
+
+* **設定の変更**: サーバーの詳細を変更します。
+
+  <Warning>
+  注意: URLの変更は再認証を引き起こし、サーバーIDの変更は既存のアプリケーションを破損させます。
+  </Warning>
+
+  <img
+    src="/images/CleanShot2025-07-07at07.28.04@2x.png"
+    alt="CleanShot 2025-07-07 at 07.28.04@2x.png"
+    title="CleanShot 2025-07-07 at 07.28.04@2x.png"
+    className="mx-auto"
+    style={{ width:"60%" }}
+  />
+
+* **サーバーの削除**: サーバーを切断します。そのツールを使用しているアプリケーションは、再接続またはツールを削除するまでエラーが表示されます。
+
+## アプリケーションでのMCPツールの使用
+
+サーバーが設定されると、そのツールは作成時のツール選択インターフェースに表示されます：
+
+### Agent アプリケーション
+
+- MCP ツールは Agent 設定の組み込みツールと一緒に表示されます。
+- ツールはサーバー別に整理されます: "Notion MCP » ページ作成", "Linear MCP » 課題作成"。
+- "すべて追加"オプションを使用すると、サーバーの全ツールを迅速に有効にできます。
+
+### Workflow アプリケーション
+- MCP ツールは Workflow ビルダーの利用可能なノードタイプとして表示されます。
+- 各ツールノードはどのサーバーから来ているかを示します（トラブルシューティングに役立ちます）。
+- 複雑なツールパラメーターは構造化データ用のJSON入力インターフェースを持ちます。
+
+### Workflow 内の Agent ノード
+
+- MCPツールはスタンドアロン Agent と同様に Agent ノード内でも選択できます。
+
+### MCP ツールをユースケースにカスタマイズする
+
+Agent ノードや Agent に MCP ツールを追加すると、その動作をカスタマイズできます：
+
+<img
+  src="/images/CleanShot2025-07-07at07.41.33@2x.png"
+  alt="CleanShot 2025-07-07 at 07.41.33@2x.png"
+  title="CleanShot 2025-07-07 at 07.41.33@2x.png"
+  className="mx-auto"
+  style={{ width:"57%" }}
+/>
+
+### ツールの説明
+
+MCPサーバーからのデフォルトの説明をオーバーライドできます。これにより、ユースケースに特化した説明が可能です。
+
+### パラメーター設定（推論設定）
+
+各ツールパラメーターについて、次の選択ができます：
+
+**自動**: コンテキストに基づいてAIモデルがパラメーター値を決定します（デフォルトの動作）。
+
+**固定値**: 常に使用される特定の値（静的な値または変数）を設定し、AIの推論からパラメーターを取り除きます。
+
+これは次のような状況で便利です：
+
+- 一貫した設定値を設定するため（検索ツールに対して `numResults: 10` のように）。
+- 変更すべきでないパラメーターを事前に設定するため（特定のAPIエンドポイントやフォーマット設定）。
+- AIが処理する必要のあるパラメーターを減らしてツールの使用を簡素化します。
+
+例えば、Web 検索ツールを使う場合、以下のように設定できます：
+
+* `query`を「自動」に保ち、AIが何を検索するかを決定します。
+* `numResults`を「5」として固定値に設定し、応答サイズを制限します。
+* 検索フィルターなど他のパラメーターを固定値として設定し、一貫した動作を実現します。
+
+## アプリケーションのポータビリティ
+
+MCPツールを使用するDifyアプリケーションをエクスポートすると：
+
+* **DSLエクスポート**: エクスポートされたDSLは、MCPサーバーをそのIDで参照します。
+
+* **環境移行**: 他の場所でアプリケーションを使用するには、ターゲット環境に同じMCPサーバーを同一のIDで追加します。
+
+* **アプリの共有**: アプリケーションに依存するMCPサーバーを、URLや必要なサーバーIDを含めて文書化します。
+
+## 統合問題のトラブルシューティング
+
+* **"未設定サーバー"**: 認証に失敗したか、ツールが見つかりません。サーバーURLを確認し、再認証してください。
+* **アプリ内のツールが欠如**: "ツールを更新"をクリックして — 外部サービスが提供を変更したかもしれません。
+* **サーバー変更後のアプリの破損**: サーバーIDを変更したりサーバーを削除した場合、アプリケーションはツールエラーを表示します。元のIDでサーバーを再追加して機能を回復させてください。
+
+## ベストプラクティス
+
+**一貫したサーバーID**: github-mcpやsalesforce-apiのような説明的で永久的なIDを使用します。一度、アプリケーションが依存し始めたら変更しないでください。
+
+**環境の一貫性**: 開発、ステージング、プロダクション環境間で同じMCPサーバー構成を維持します。
+
+**ツールのカスタマイズ**: パラメーター設定を活用し、アプリケーションでツールが一貫して機能するようにします。固定値を設定し、動的な入力をAIに処理させます。
+
+**ツールの文書化**: アプリケーションで使用している外部ツール、行ったカスタマイズ、及びその機能を文書化します。これにより、チームメンバーがアプリケーションの依存関係を理解しやすくなります。
+
+**段階的な更新**: 外部サービスがMCPサーバーを更新する際、プロダクション環境での統合を更新する前に開発環境でツールの変更をテストします。
+
+**バックアッププラン**: 外部MCPサーバーが利用できなくなった場合、アプリケーションがどのように動作するかを考慮します。
+
+{/*
+Contributing Section
+DO NOT edit this section!
+It will be automatically generated by the script.
+*/}
+
+---
+
+[このページを編集する](https://github.com/langgenius/dify-docs/edit/main/ja-jp/guides/tools/mcp.mdx) | [問題を報告する](https://github.com/langgenius/dify-docs/issues/new?title=ドキュメントの問題%3A%20&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs%2Fblob%2Fmain%2Fja-jp/guides/tools%2Fmcp.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E)
+
--- a/ja-jp/guides/tools/types-of-tools.mdx
+++ b/ja-jp/guides/tools/types-of-tools.mdx
@@ -0,0 +1,33 @@
+---
+title: "ツールの種類"
+description: "ツールは、ワークフローやエージェントが同様に使用できる定義済みのサービスです。"
+---
+
+<CardGroup cols={2}>
+  <Card title="ツールプラグイン" icon="puzzle-piece" iconType="regular" href="https://docs.dify.ai/en/plugins/quick-start/install-plugins">
+    Difyの[マーケットプレイス](https://marketplace.dify.ai/?category=tool_)で、Difyネイティブの数百ものツールを探索しましょう
+  </Card>
+  <Card title="MCP" icon="sparkles" href="ja-jp/guides/tools/mcp">
+    [Model Context Protocol](https://modelcontextprotocol.io/introduction)に基づいた、常に成長し続けるツールのエコシステムに接続しましょう。
+  </Card>
+</CardGroup>
+
+<CardGroup cols={2}>
+  <Card title="カスタムツール" icon="paintbrush-pencil">
+    OpenAPI / Swagger標準フォーマットのAPIサービスを、ツールに変換します。
+  </Card>
+  <Card title="ツールとして呼び出したワークフロー" icon="network-wired">
+    別のDifyワークフローをツールとして呼び出します
+  </Card>
+</CardGroup>
+
+{/*
+Contributing Section
+DO NOT edit this section!
+It will be automatically generated by the script.
+*/}
+
+---
+
+[このページを編集する](https://github.com/langgenius/dify-docs/edit/main/ja-jp/guides/tools/types-of-tools.mdx) | [問題を報告する](https://github.com/langgenius/dify-docs/issues/new?title=ドキュメントの問題%3A%20-of-to&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs%2Fblob%2Fmain%2Fja-jp/guides/tools%2Ftypes-of-tools.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E)
+
--- a/zh-hans/guides/application-publishing/publish-mcp.mdx
+++ b/zh-hans/guides/application-publishing/publish-mcp.mdx
@@ -0,0 +1,66 @@
+---
+title: "将 Dify 应用部署为 MCP 服务器"
+---
+
+Dify 现已支持将你的应用部署为 [MCP](https://modelcontextprotocol.io/introduction)（模型上下文协议，一种让 AI 工具之间相互通信的标准协议）服务器。通过这一功能，你可以轻松将 Dify 应用集成到如 Claude Desktop 这样的 AI 助手，或像 Cursor 这样的开发环境中，让这些工具能够直接调用你的 Dify 应用，实现无缝扩展。
+
+<Note>
+  如果你希望在 Dify 工作流或智能体中使用 MCP 工具，请参考[相关指南](/zh-hans/guides/tools/mcp)。
+</Note>
+
+## 配置 Dify 应用为 MCP 服务器
+
+在 Dify 应用的配置页面中，你可以找到 MCP 服务器的相关配置选项。该功能默认关闭，开启后，Dify 将为当前应用自动生成唯一的 MCP 服务器地址。此地址将作为外部工具访问你应用的专用接口。
+
+<Danger>
+  MCP 服务器地址包含了敏感的身份验证信息，应等同于 API Key 妥善保管。如怀疑信息泄露，可点击"重新生成"，获取新的服务器地址，原有地址将立即失效。
+</Danger>
+
+<img
+  src="/images/CleanShot2025-07-07at08.18.02.png"
+  alt="CleanShot 2025-07-07 at 08.18.02.png"
+  title="CleanShot 2025-07-07 at 08.18.02.png"
+  className="mx-auto"
+  style={{ width:"46%" }}
+/>
+
+## 与 Claude Desktop 集成
+
+要将 Dify 应用集成到 Claude Desktop，请依次选择：个人资料 > 设置 > 集成 > 添加集成。在"集成 URL"一栏，填写你 Dify 应用的 MCP 服务器地址即可。
+
+## 与 Cursor 集成
+
+在 Cursor 中集成 Dify 应用，只需在项目根目录下创建或编辑 `.cursor/mcp.json` 文件，内容如下：
+
+```json
+{
+  "mcpServers": {
+    "your-server-name": {
+      "url": "your-server-url"
+    }
+  }
+}
+```
+
+请将 `url` 部分替换为你的 Dify 应用的 MCP 服务器地址。保存文件后，重启 Cursor 即可自动识别这一配置，并将 Dify 应用作为工具集成。该配置支持添加多个应用，只需在 `mcpServers` 对象下增加新的条目即可。
+
+## 实用建议
+
+- **描述信息的清晰性**
+
+  在编写工具描述和参数说明时，应从 AI 处理数据的角度出发。说明越明确、具体，AI 的调用效果就越好。例如，与其简单写"输入数据"，不如详细说明为："包含用户姓名、邮箱和偏好设置的 JSON 对象"。
+
+- **延迟（Latency）管理**
+
+  MCP 协议负责通信层，但 Dify 应用的响应速度依然至关重要。如果你的应用处理时间较长（例如超过 30 秒），用户将在客户端直接感知到延迟。建议增加进度提示，或将复杂流程拆解为多个更快的小步骤，以提升整体体验。
+
+{/*
+Contributing Section
+DO NOT edit this section!
+It will be automatically generated by the script.
+*/}
+
+---
+
+[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/guides/application-publishing/publish-mcp.mdx) | [提交问题](https://github.com/langgenius/dify-docs/issues/new?title=文档问题%3A%20sh-&body=%23%23%20问题描述%0A%3C%21--%20请简要描述您发现的问题%20--%3E%0A%0A%23%23%20页面链接%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs%2Fblob%2Fmain%2Fzh-hans/guides/application-publishing%2Fpublish-mcp.mdx%0A%0A%23%23%20建议修改%0A%3C%21--%20如果有具体的修改建议，请在此说明%20--%3E%0A%0A%3C%21--%20感谢您对文档质量的关注！%20--%3E)
+
--- a/zh-hans/guides/tools/mcp.mdx
+++ b/zh-hans/guides/tools/mcp.mdx
@@ -0,0 +1,184 @@
+---
+title: "集成 MCP 工具"
+---
+
+你可以在 Dify 的 Agent 和 Workflow 应用中，直接集成来自外部 [MCP](https://modelcontextprotocol.io/introduction) 服务器的[工具](https://modelcontextprotocol.io/docs/concepts/tools)。除了使用 Dify 内置插件外，还可以接入 MCP [生态系统](https://mcpservers.org/)中的第三方服务，持续扩展你的应用功能。
+
+<Note>
+  本文介绍了如何在 Dify 内集成和使用 MCP 工具。如果你希望将自己的 Dify 应用发布为 MCP 服务器，请参考此[链接](/zh-hans/guides/application-publishing/publish-mcp)。
+</Note>
+
+<Info>
+  目前仅支持接入使用 HTTP 传输协议的 [MCP 服务器](https://modelcontextprotocol.io/docs/concepts/architecture#transport-layer) 。
+</Info>
+
+## MCP 服务器管理界面
+
+登录 Dify 后，在左侧导航栏中依次点击 **工具** → **MCP**，即可进入外部 MCP 服务器的管理页面。在这里，你可以统一管理所有为自身应用配置的 MCP 服务器。
+
+![6cef1436fcc13a65ccedb54bcf5ab77eb87b8faba1098a85951839fb1907f2d2.png](/images/6cef1436fcc13a65ccedb54bcf5ab77eb87b8faba1098a85951839fb1907f2d2.png)
+
+## 添加 MCP 服务器
+
+<img
+  src="/images/b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
+  alt="b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
+  title="b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
+  className="mr-auto"
+  style={{ width:"70%" }}
+/>
+
+点击 **添加 MCP 服务器（HTTP）**，即可集成新的外部工具服务。需要填写如下信息：
+
+* **服务器 URL**：MCP 服务器的 HTTP 接口地址，例如集成 Notion 时为 `https://api.notion.com/mcp`。
+
+* **名称与图标**：自定义服务器名称，建议选择能清晰体现工具用途的名字。Dify 会自动尝试获取服务器域名的图标，你也可以手动上传。
+
+* **服务器标识符**：Dify 用于区分服务器的唯一 ID。规则：小写字母、数字、下划线或连字符，最多 24 个字符。
+
+<Warning>
+  服务器 ID 一旦创建即无法更改。如果更改服务器 ID，所有依赖该服务器工具的 Agent 或 Workflow 都会失效。这一设计对于[应用迁移](##application-portability)尤为重要。
+</Warning>
+
+## 授权与工具发现
+
+添加服务器后，Dify 会自动执行如下操作：
+
+1. **检测可用工具**：自动识别该服务器能提供哪些工具功能。
+2. **处理授权流程**：如服务器需要身份验证，则自动发起 OAuth 授权流程。
+3. **获取工具定义**：下载各工具的接口定义（schema）。
+4. **同步工具列表**：将识别到的工具加入 Agent 或Workflow应用的构建页面。
+
+当 Dify 成功获取到至少一个可用工具后，会在页面中显示该服务器的信息卡片：
+
+![fcef5ecad1deca82a1d8988c4bcb7cec745a0cd47945ff05fca588502cfaafbc.png](/images/fcef5ecad1deca82a1d8988c4bcb7cec745a0cd47945ff05fca588502cfaafbc.png)
+
+## 管理已连接服务器
+
+点击对应服务器卡片，可进行以下操作：
+
+* **更新工具**：重新从服务器获取最新工具信息，适用于服务方新增或调整功能后更新。
+
+  <img
+    src="/images/7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
+    alt="7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
+    title="7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
+    className="mx-auto"
+    style={{ width:"59%" }}
+  />
+
+* **重新授权**：点击授权状态，更新服务器的访问权限（如令牌失效需重新授权）。
+
+* **编辑配置**：可修改服务器信息。
+
+<Warning>
+  更改服务器 URL 会触发重新授权，修改服务器 ID 会让已有应用失效！
+</Warning>
+
+<img
+  src="/images/CleanShot2025-07-07at07.28.04@2x.png"
+  alt="CleanShot 2025-07-07 at 07.28.04@2x.png"
+  title="CleanShot 2025-07-07 at 07.28.04@2x.png"
+  className="mx-auto"
+  style={{ width:"60%" }}
+/>
+
+* **移除服务器**：断开服务器连接。此后所有依赖该服务器工具的应用都会报错，直到你重新连接或删除相关工具。
+
+## 在应用中使用 MCP 工具
+
+当服务器配置完成后，其下的工具会出现在应用构建时的工具选择区：
+
+### Agent 应用
+
+- 在 Agent 配置界面，与内置工具并列显示 MCP 工具。
+- 工具按服务器分组，例如："Notion MCP » 创建页面"、"Linear MCP » 创建任务"等。
+- 可一键"添加全部"，快速启用该服务器下的所有工具。
+
+### Workflow 应用
+
+- 构建 Workflow 时，MCP 工具以可选节点类型出现。
+- 每个工具节点都会指明归属服务器，便于定位和排查问题。
+- 参数较为复杂的工具会自动生成 JSON 格式的结构化输入界面。
+
+### Workflows 中的 Agent 节点
+
+在 Workflow 的 Agent 节点中，也可灵活选择 MCP 工具进行配置，使用方式与独立 Agent 一致。
+
+## 按需定制 MCP 工具
+
+将 MCP 工具添加到Agent节点或 Agent 应用中后，你可以根据实际需求灵活定制：
+
+<img
+  src="/images/CleanShot2025-07-07at07.41.33@2x.png"
+  alt="CleanShot 2025-07-07 at 07.41.33@2x.png"
+  title="CleanShot 2025-07-07 at 07.41.33@2x.png"
+  className="mx-auto"
+  style={{ width:"57%" }}
+/>
+
+### 工具说明
+
+可自定义工具的显示描述，调整为更贴合业务场景的说明信息，替换原 MCP 服务器自带描述。
+
+### 参数配置（Reasoning Config）
+
+每个工具参数可灵活选择两种模式：
+
+* **自动（Auto）**：让 AI 根据上下文智能决定该参数值（默认）。
+
+* **固定值（Fixed Value）**：设定为某个确定的值（支持静态文本或变量表达式），AI 不再推理此参数。
+
+使用示例：
+
+* 统一配置项，例如将搜索工具的 `numResults` 固定为 10。
+* 预填写不应更改的参数，如特定的 API 地址、返回格式等。
+* 通过减少 AI 需要处理的参数数量，简化工具调用逻辑。
+
+例如，配置 Web 搜索工具时：
+
+* 将 `query` 设置为"自动"，由 AI 动态生成搜索内容。
+* 将 `numResults` 固定为 5，控制每次返回结果数量。
+* 其他如过滤条件参数也可固定，以保证结果一致性。
+
+## 应用迁移
+
+当你导出包含 MCP 工具的 Dify 应用时：
+
+* **DSL 导出**：导出的 DSL 文件会引用所用 MCP 服务器的唯一标识符（ID）。
+* **环境迁移**：迁移应用到其他环境时，需在目标环境添加相同 ID 的 MCP 服务器。这样可以确保工具引用关系保持不变。
+* **应用共享**：建议在文档中明确标注依赖的 MCP 服务器（包括 URL 和 ID），以便团队协作和环境同步。
+
+
+## 常见问题排查
+
+**"未配置的服务器"**: 授权失败或未获取到工具。请检查服务器 URL 并重新授权。
+
+**应用内工具缺失**: 点击"更新工具" - 有可能外部服务更改了工具列表。
+
+**服务器变动导致应用失效**: 如果修改服务器 ID 或移除服务器，应用会报错。需用原 ID 重新添加服务器，以恢复功能。
+
+## 最佳实践
+
+**服务器 ID 保持一致性**: 使用具备描述性的 ID 名，例如 `github-mcp` 或者 `salesforce-api`。ID 一旦被应用引用，请勿更改。
+
+**多环境一致性**: 开发、测试、生产等环境的 MCP 服务器配置应保持一致。
+
+**工具定制**: 主动设置固定参数值，保证工具行为稳定、简化 AI 推理，仅将动态输入交由 AI 处理。
+
+**工具文档**: 明确记录应用中用到的外部工具、定制内容及其用途，方便团队后续运维与协作。
+
+**逐步升级**: 外部服务升级或变更 MCP 服务器时，应先在开发环境测试通过后，再同步到生产环境。
+
+**应急方案**: 提前规划好关键外部 MCP 服务器不可用时的应用应对策略。
+
+{/*
+Contributing Section
+DO NOT edit this section!
+It will be automatically generated by the script.
+*/}
+
+---
+
+[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/guides/tools/mcp.mdx) | [提交问题](https://github.com/langgenius/dify-docs/issues/new?title=文档问题%3A%20&body=%23%23%20问题描述%0A%3C%21--%20请简要描述您发现的问题%20--%3E%0A%0A%23%23%20页面链接%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs%2Fblob%2Fmain%2Fzh-hans/guides/tools%2Fmcp.mdx%0A%0A%23%23%20建议修改%0A%3C%21--%20如果有具体的修改建议，请在此说明%20--%3E%0A%0A%3C%21--%20感谢您对文档质量的关注！%20--%3E)
+