Skip to main content

從您的應用程式連接到 MCP 伺服器

本教程將向您展示如何使用 AgentBuilder 的 MCP Tools Components 將 MCP 伺服器連接到您的應用程式。

Model Context Protocol (MCP) 通過 MCP 客戶端 和 MCP 伺服器 幫助 agent 與 LLM 整合。 具體來說，MCP 伺服器託管 agent（MCP 客戶端）用來完成專門任務的工具。 MCP 伺服器連接到像 Cursor 這樣的 MCP 客戶端。 然後，您與客戶端互動，客戶端會根據需要使用連接伺服器的工具來完成您的請求。

您可以將 AgentBuilder 作為 MCP 客戶端和 MCP 伺服器運行：

  • 將 AgentBuilder 用作 MCP 客戶端：當作為 MCP 客戶端運行時，AgentBuilder Flow 中的 Agent Components可以使用連接的Components作為工具來處理請求。 您可以使用現有Components作為工具，並且可以將任何 MCP 伺服器連接到您的 Flow，使該伺服器的工具可供 agent 使用。

  • 將 AgentBuilder 用作 MCP 伺服器：當作為 MCP 伺服器運行時，您的 Flow 成為可由 MCP 客戶端使用的工具，這可能是外部客戶端或另一個 AgentBuilder Flow。

在本教程中，您將使用 AgentBuilder MCP Tools Components將多個 MCP 伺服器連接到您的 Flow，然後您將使用 Python 應用程式以程式設計方式運行您的 Flow 並與 agent 聊天。

先決條件​

本教程使用 OpenAI LLM。如果您想使用不同的提供商，您需要該提供商的有效憑證。

建立 Agent Flow​

  1. 在 AgentBuilder 中，點擊 New Flow，然後選取 Simple Agent 模板。

  2. 在 Agent Components中，輸入您的 OpenAI API 金鑰。

    如果您想使用不同的提供商或模型，請相應地編輯 Model Provider、Model Name 和 API Key 欄位。

  3. 要測試 Flow，點擊 Playground，然後詢問 LLM Is it safe to go hiking in the Adirondacks today?

    此查詢演示了 LLM 本身可能無法存取專門設計用來處理專門查詢的資訊或功能。在這個例子中，預設 OpenAI 模型提供了一個模糊的回應，儘管 agent 確實知道當前日期，因為它使用了內部的 get_current_date 函數。


    _10
    Today is July 11, 2025.
    _10
    To determine if it's safe to go hiking in the Adirondacks today, you should check the current weather conditions, trail advisories, and any local alerts (such as bear activity or flooding).
    _10
    Would you like a detailed weather forecast or information on trail conditions for the Adirondacks today?

    要改善回應，您可以將提供 agent 在產生回應時使用的專門工具的 MCP 伺服器連接到您的 Flow。在本教程的下一部分，您將連接一個為 agent 提供即時天氣資訊的 MCP 伺服器，以便它能夠產生更具體的回應。

新增 MCP Tools Components​

線上有許多可用的 MCP 伺服器，提供不同任務的不同工具。 要將 MCP 伺服器與 MCP 客戶端一起使用，您必須使伺服器可供客戶端使用。 對於所有 MCP 客戶端，有幾種方法可以做到這一點：

  • 在本地安裝伺服器。
  • 使用 uvx 或 npx 來獲取和運行伺服器套件。
  • 調用遠端運行的伺服器，如 Smithery 上可用的伺服器。

本教程演示如何使用 uv pip install 在本地安裝天氣伺服器，以及如何使用 npx 運行地理位置伺服器套件。 您的特定 MCP 伺服器要求可能有所不同。

在 AgentBuilder 中，您使用 MCP Tools Components將特定的 MCP 伺服器連接到FLOW。 對於您希望FLOW使用的每個 MCP 伺服器，您需要一個 MCP Tools Components。

  1. 對於本教程，使用 uv 和 Python 在您的本地機器上安裝 天氣 MCP 伺服器：


    _10
    uv pip install mcp_weather_server

    確保您在 AgentBuilder 運行的同一 Python 環境中安裝伺服器：

    • AgentBuilder 在虛擬環境中：安裝伺服器之前啟動環境。
    • AgentBuilder Docker 映像：在 Docker 容器內安裝伺服器。
    • AgentBuilder Desktop 或系統範圍的 AgentBuilder OSS：在全域或運行 AgentBuilder 的同一使用者環境中安裝伺服器。

  2. 在您的 Simple Agent Flow 中，移除 URL 和 Calculator 工具，然後新增 MCP Tools Components。

  3. 點擊 MCP Tools Components，然後點擊 Add MCP Server。

    tip

    要管理所有 MCP 伺服器連接，點擊視覺編輯器中的 MCP servers，或點擊您的個人資料圖標，選取 Settings，然後點擊 MCP Servers。

  4. 在 Add MCP Server 窗格中，提供伺服器啟動命令和參數以將天氣 MCP 伺服器連接到您的FLOW。對於本教程，使用 JSON 或 STDIO 選項之一。

    當 agent 確定需要使用該伺服器提供的工具時，AgentBuilder 會運行命令來啟動伺服器。

    請注意，這兩種配置都提供了相同資訊，但格式不同。 這意味著如果您的 MCP 伺服器儲存庫只提供伺服器的 JSON 檔案，您仍然可以使用 STDIO 選項使用這些值。

    要將 MCP 伺服器配置作為 JSON 物件提供，選取 JSON，然後將伺服器配置貼上到 JSON 欄位中：


    _13
    {
    _13
    "mcpServers": {
    _13
    "weather": {
    _13
    "command": "python",
    _13
    "args": [
    _13
    "-m",
    _13
    "mcp_weather_server"
    _13
    ],
    _13
    "disabled": false,
    _13
    "autoApprove": []
    _13
    }
    _13
    }
    _13
    }

  5. 點擊 Add Server，然後等待 Actions 清單填入。這意味著 MCP 伺服器成功連接。

    使用此天氣伺服器，MCP Tools Components還新增了一個可選的 City 欄位。 對於本教程，不要在此欄位中輸入任何內容。 相反，您將在下一步中新增地理位置 MCP 伺服器，agent 將使用它來檢測您的位置。

  6. 點擊 MCP Tools Components，在 Components的標頭選單 中啟用 Tool Mode，然後將Components的 Toolset 連接埠連接到 Agent Components的 Tools 連接埠。

    此時您的 Flow 有四個連接的Components：

    • Chat Input Components連接到 Agent Components的 Input 連接埠。這允許 Flow 由來自使用者或應用程式的傳入提示觸發。
    • 帶有天氣 MCP 伺服器的 MCP Tools Components連接到 Agent Components的 Tools 連接埠。agent 可能不會為每個請求使用此伺服器；只有當 agent 決定伺服器可以幫助回應提示時，才會使用此連接。
    • Agent Components的 Output 連接埠連接到 Chat Output Components，它將最終回應返回給使用者或應用程式。

    連接到 MCP 天氣伺服器的 Agent Components

  7. 要測試天氣 MCP 伺服器，點擊 Playground，然後詢問 LLM Is it safe to go hiking in the Adirondacks today?

    Playground 向您顯示 agent 的邏輯，因為它分析請求並選取要使用的工具。

    理想情況下，由於天氣 MCP 伺服器提供的額外上下文，agent 的回應將比之前的回應更具體。 例如：


    _10
    The current weather in Lake Placid, a central location in the Adirondacks,
    _10
    is foggy with a temperature of 17.2°C (about 63°F).
    _10
    If you plan to go hiking today, be cautious as fog can reduce visibility
    _10
    on trails and make navigation more difficult.

    這是一個更好的回應，但什麼使這個 MCP 伺服器比僅僅調用天氣 API 更有價值？

    首先，MCP 伺服器通常針對特定任務進行自訂，例如高度專門的動作或用於複雜、多步驟問題解決的鏈式工具。 通常，您必須為特定任務編寫自訂腳本，可能在單個腳本中包含多個 API 調用，然後您必須在 agent 上下文之外執行此腳本，或者以某種方式將其提供給您的 agent。

    相反，MCP 確保所有 MCP 伺服器都以相同的方式新增到 agent 中，而無需知道每個伺服器的特定 EndPoint 結構或編寫自訂整合。 MCP 是將許多不同工具整合到 agent 應用程式中的標準化方式。 每次想要使用新的 MCP 伺服器時，您不必學習新的 API 或編寫自訂程式碼。

    此外，您可以根據想要應用程式解決的問題，將許多 MCP 伺服器附加到一個 agent。 您新增的伺服器越多，agent 在其回應中可以使用的專門上下文就越多。 在本教程中，新增天氣 MCP 伺服器已經改善了 LLM 回應的品質。 在教程的下一節中，您將新增一個 ip_geolocation MCP 伺服器，以便 agent 可以在使用者沒有在提示中指定位置的情況下檢測使用者的位置。

新增地理位置伺服器​

Toolkit MCP 伺服器 包含多個用於網路監控的 MCP 工具，包括 IP 地理位置。它不是非常精確，但不需要 API 金鑰。

請注意，此工具返回您的 AgentBuilder 伺服器的 IP 地理位置，因此如果您的伺服器遠端部署，請考慮替代方法來獲取特定於使用者的位置資料，例如瀏覽器地理位置 API。

此 MCP 伺服器可以使用一個 npx 命令啟動，它會下載並運行 Toolkit MCP 伺服器 Node 登錄套件，而無需在本地安裝套件。

要將 Toolkit MCP 伺服器新增到您的FLOW，請執行以下操作：

  1. 將另一個 MCP Tools Components新增到您的 Flow，點擊該Components，然後點擊 Add MCP Server。

  2. 選取 STDIO。

  3. 對於 Name，輸入 ip_geolocation。

    tip

    工具名稱和描述幫助 agent 選取工具。 如果您的 agent 難以選取工具，請確保名稱和描述清晰且人類可讀。

  4. 對於 Command，輸入 npx @cyanheads/toolkit-mcp-server。

  5. 點擊 Add Server，然後等待 Actions 清單填入。這意味著 MCP 伺服器成功連接。

  6. 點擊 MCP Tools Components，在 Components的標頭選單 中啟用 Tool Mode，然後將Components的 Toolset 連接埠連接到 Agent Components的 Tools 連接埠。

    您的 Flow 現在有另一個 MCP Tools Components，總共五個Components。

    連接到 MCP 天氣和地理位置伺服器的 Agent Components

建立連接到 AgentBuilder 的 Python 應用程式​

此時，您可以開啟 Playground 並詢問您當前位置的天氣來測試 IP 地理位置工具。 但是，地理位置工具在應用程式中最有用，在這些應用程式中，您或您的使用者想要詢問世界各地不同地方的天氣。

在本教程的最後部分，您將學習如何使用 AgentBuilder API 在腳本中運行 Flow。 這可能是較大應用程式的一部分，例如移動應用程式，使用者想要知道天氣是否適合特定運動。

當您使用 AgentBuilder API 運行 Flow 時，您可以更改 Flow 的某些方面，而無需更改程式碼。 例如，您可以在 AgentBuilder 中為您的 Flow 新增更多 MCP 伺服器，然後使用相同的腳本運行 Flow。 您可以使用相同的輸入或新的輸入，提示 agent 使用其他工具。1. 對於本教程的 Python 腳本，收集以下資訊：

  • AGENTBUILDER_SERVER_ADDRESS：您的 AgentBuilder 伺服器的網域。預設值為 127.0.0.1:7860。您可以從FLOW的 API access 窗格上的程式碼片段中獲取此值。
  • FLOW_ID：您的 Flow 的 UUID 或自訂 EndPoint 名稱。您可以從 Flow 的 API access 窗格上的程式碼片段中獲取此值。
  • AGENTBUILDER_API_KEY：有效的 AgentBuilder API 金鑰。

  1. 將以下腳本複製到 Python 檔案中，然後將佔位符替換為您在上一步收集的資訊：


    _34
    import requests
    _34
    import os
    _34
    _34
    url = "AGENTBUILDER_SERVER_ADDRESS/api/v1/run/FLOW_ID" # 此 Flow 的完整 API 端點 URL
    _34
    _34
    # 請求載荷配置
    _34
    payload = {
    _34
    "output_type": "chat",
    _34
    "input_type": "chat",
    _34
    "input_value": "What's the weather like where I am right now?"
    _34
    }
    _34
    _34
    # 請求標頭
    _34
    headers = {
    _34
    "Content-Type": "application/json",
    _34
    "x-api-key": "AGENTBUILDER_API_KEY"
    _34
    }
    _34
    _34
    try:
    _34
    # 發送 API 請求
    _34
    response = requests.request("POST", url, json=payload, headers=headers)
    _34
    response.raise_for_status() # 為不良狀態碼引發異常
    _34
    _34
    # 解析並僅列印訊息文字
    _34
    data = response.json()
    _34
    message = data["outputs"][0]["outputs"][0]["results"]["message"]["text"]
    _34
    print(message)
    _34
    _34
    except requests.exceptions.RequestException as e:
    _34
    print(f"Error making API request: {e}")
    _34
    except ValueError as e:
    _34
    print(f"Error parsing response: {e}")
    _34
    except (KeyError, IndexError) as e:
    _34
    print(f"Error extracting message from response: {e}")

    請注意，此腳本使用的提示與之前的 Playground 示例不同。 在此腳本中，input_value 詢問使用者當前位置的天氣，而沒有提供任何關於使用者位置的提示，例如特定城市。

    此外，此腳本包含解析程式碼，以從整個 AgentBuilder API 回應中提取 LLM 的回覆。 您會想在自己的應用程式中使用類似的提取，因為 AgentBuilder API 回應包含對傳遞給使用者的回覆不相關的元資料和其他資訊。

    儲存並運行腳本以發送請求並測試 Flow。

    agent 使用 ip_geolocation 工具檢測請求者的位置，然後使用 weather 工具檢索該位置的天氣資訊。 例如：


    _10
    The weather in Waynesboro, Pennsylvania, is currently overcast with a temperature of 23.0°C (about 73.4°F).
    _10
    If you need more details or have any other questions, feel free to ask!

    請記住，本教程中使用的 ip_geolocation 工具使用您的 AgentBuilder 伺服器的位置，這可能與您的實際位置不同。

下一步​

要繼續建構本教程中介紹的概念，請參閱以下內容：

Search