基于 LLM 的 MCP 架构实战：服务端搭建、工具开发与 Dify 集成全流程

随着分布式系统与跨端通信技术的快速发展，客户端与服务端的高效交互成为各类应用开发的核心环节，MCP 架构凭借其轻量化、高适配性与灵活的通信机制，在多场景开发中得到广泛应用。深入解析 MCP 客户端与服务端的核心架构、运行逻辑及交互原理，是掌握该技术体系的关键。本文立足 MCP 架构的应用实践，从核心组成、数据传输、协议适配等维度展开解析，厘清客户端与服务端的职责划分、通信流程及协同机制，明晰二者在数据请求、指令响应、异常处理中的核心逻辑，为相关技术研发、架构优化与问题排查提供理论支撑与实践参考。

1 uv管理工具使用

1.1 uv 下载与安装

shell 复制代码

# mac or linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# windows 打开powershell，以管理员身份运行
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装成功后，终端会显示 uv 的安装路径，如下图所示：

常见安装报错处理：

若在 Windows 上执行安装命令时出现如下提示：
Error: PowerShell requires an execution policy in [Unrestricted, RemoteSigned, Bypass] to run uv. For example, to set the execution policy to 'RemoteSigned' please run:
Set-ExecutionPolicy RemoteSigned -scope CurrentUser

解决办法，直接输入：

shell 复制代码

Set-ExecutionPolicy RemoteSigned -scope CurrentUser

1.2 uv 基本操作指南

1.2.1 创建新项目

shell 复制代码

# 创建项目文件夹
uv init weather
cd weather

执行成功后，项目目录下会自动生成标准的 Python 项目结构，包括 pyproject.toml 等配置文件，如下图所示：

1.2.2 创建虚拟环境

shell 复制代码

# Create virtual environment and activate it
uv venv
# linux
source .venv/bin/activate
# windwos
.venv\Scripts\activate

环境创建后，项目根目录下会生成 .venv 目录，其中包含完整的 Python 运行时环境，如下图所示：

1.2.3 安装项目依赖

shell 复制代码

uv add "mcp[cli]" httpx

安装完成后，所有依赖包会被部署到虚拟环境的 Lib/site-packages 目录中，完成 MCP 开发所需的核心依赖配置，如下图所示：

2 MCP 服务端搭建与实践

2.1 环境准备与项目初始化

shell 复制代码

uv init mcp_weather_srv
cd mcp_weather_srv
uv add "mcp[cli]"
# linux
touch weather_srv.py
# windows cmd
type nul > weather_srv.py

2.2 服务端代码实现

将以下代码写入 weather_srv.py。该服务为 LLM/Agent 提供可调用的工具能力，是大模型工具调用的核心服务层：

python 复制代码

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel

# 初始化 MCP 服务端（精简配置，保留核心参数）
mcp = FastMCP(
    name="weatherDemo",
    host="0.0.0.0",
    port=8888,
)

# 核心工具1：查询张三是谁
@mcp.tool(description="查询张三个人信息，回答张三是谁、张三这个人怎么样这类问题")
def get_zhangsan_info() -> str:
    zs_info = "张三，为人豁达开朗，行事沉稳靠谱，待人真诚友善，是兼具责任心与亲和力的人；\n日常随和低调，遇事条理清晰，既有处事的分寸感，也有待人的包容心，口碑端正，品性踏实。"
    return zs_info

# 结构化天气数据模型
class WeatherData(BaseModel):
    city: str
    temperature: float
    condition: str

# 核心工具2：获取指定城市的模拟天气数据
@mcp.tool(description="获取指定城市的模拟天气数据，返回城市、温度、天气状况")
def get_weather(city: str) -> WeatherData:
    mock_data = {
        "北京": WeatherData(city="Beijing", temperature=25.5, condition="晴"),
        "上海": WeatherData(city="Shanghai", temperature=23.0, condition="多云"),
        "广州": WeatherData(city="Guangzhou", temperature=28.0, condition="雷阵雨")
    }
    return mock_data.get(city, WeatherData(city=city, temperature=22.0, condition="未知"))

# 启动MCP服务
if __name__ == "__main__":
    print("MCP服务端启动：http://0.0.0.0:8888/mcp")
    mcp.run(transport="streamable-http")

说明：将服务接口暴露至公网网段（0.0.0.0）是为了适配 Docker 环境中部署的 Dify 大模型应用平台，实现跨环境的 LLM 应用与 MCP 服务的互联互通。

完成代码编写后，使用以下命令启动服务：

shell 复制代码

cd mcp_weather_srv
uv run weather_srv.py

服务启动成功后，控制台将显示如下运行状态，表明 MCP 工具服务已就绪，可被 LLM/Agent 调用：

2.3 测试mcp服务

本次验证基于主流的 LLM 应用开发平台 Dify 完成，通过 Dify 的 Agent 能力实现对 MCP 工具的自动化调用，贴合真实的大模型落地场景。

2.3.1 注册mcp服务

如下图所示，在 Dify 平台后台点击「工具」→「添加 MCP 服务」，进入服务配置页面：

按照下图所示配置 MCP 服务参数：

配置完成后，平台会自动校验服务连通性，并加载 MCP 服务中注册的所有工具函数，完成服务与 LLM 平台的绑定：

2.3.2 测试mcp服务

第一步：在 Dify 平台创建专属 Agent 应用，基于该 Agent 实现 LLM 对 MCP 工具的调度与调用，如下图所示：

按照下图所示完成 Agent 的基本配置：

第二步：在 Agent 的工具配置模块中，点击「添加」并选中已注册的 MCP 工具函数，完成工具与 Agent 的绑定，如下图所示:

第三步：在对话界面发起业务请求，即可触发 LLM 的工具调用能力，自动请求 MCP 服务并返回结果：

实际测试中可看到，Dify 中的 LLM 能精准识别用户意图，自动调用对应的get_zhangsan_info和get_weather函数，MCP 服务端正常响应并返回标准化数据，工具调用链路通畅，结果返回准确：

3 常见问题与注意事项

版本兼容性提示：

若在初始化 FastMCP 时遇到如下错误提示，表明 host 与 port 参数在当前版本中可能已调整位置或不再直接支持：

python 复制代码

mcp = FastMCP(name="weatherDemo", host="0.0.0.0", port=8888)

建议使用 PyCharm 等 IDE 打开项目，通过 Go to Definition功能查看 FastMCP 类的构造函数定义。不同版本中，host 和 port 参数可能被移至 run() 方法中，或因传输协议（transport）的不同而有所差异。请根据实际使用的 MCP 版本调整代码。

总结

本文围绕大语言模型（LLM）生态的工具调用核心需求，完成了 MCP 架构的全流程实战落地。通过 uv 工具快速搭建轻量化开发环境，基于 FastMCP 搭建了可被 LLM 调用的 MCP 服务端，开发了结构化与非结构化两类工具函数，适配大模型的不同数据返回需求。并通过 Dify 平台完成 MCP 服务的集成与测试，验证了 LLM+Agent+MCP 的工具调用链路可行性。MCP 作为 LLM 与本地化工具的通信桥梁，其轻量化特性可高效对接各类大模型应用平台，本次实践也印证了 MCP 在大模型落地场景中，具备灵活适配、高效通信、易集成的核心优势，是 LLM 工具调用体系的重要技术选型。