本地大模型如何通过MCP协议调用私有API：从Ollama部署到LangChain集成实战-三亩地-编程学习日记

1. 从“玩具”到“生产力”：为什么我们需要本地大模型调用私有API？

最近在折腾本地大模型的朋友，估计都经历过这么一个阶段：一开始兴致勃勃地用 Ollama 拉取 Qwen2.5、Llama 这些模型，在命令行里一问一答，感觉拥有了一个“私人AI”，新鲜感十足。但用不了多久，你就会发现，它好像除了聊天和写点代码片段，能干的事情非常有限。你想让它帮你分析一下本地数据库里的销售数据？不行，它连不上。你想让它根据你公司内部的文档知识库来回答问题？也不行，它读不到。你想让它调用一个你正在开发的内部工具API？更不行，它被“困”在了本地，成了一个信息孤岛里的“聪明玩具”。

这就是当前本地大模型部署最核心的痛点：能力与数据、工具的割裂。模型本身很强大，但它的“手”和“眼睛”被限制住了。而“私有API”，恰恰是我们为它装上“手”和“眼睛”的关键。这里的私有API，范围很广：可以是你自己用 Flask 或 FastAPI 写的一个小服务，用来查询数据库；可以是你公司内部的某个业务系统接口；甚至可以是你家里的智能家居控制中枢。让本地大模型能安全、可控地调用这些API，意味着它能真正融入你的工作流，从“聊天机器人”升级为“AI助手”或“智能体（Agent）”。

那么，怎么实现呢？最直接的想法可能是：“我在提示词里告诉模型API地址和参数格式不就行了？” 实测下来，这条路基本走不通。大模型是文本生成器，不是HTTP客户端。它无法主动发起网络请求，也无法解析复杂的JSON响应。你需要一个“中间人”来桥接大模型的“思考”和外部世界的“行动”。这就是MCP（Model Context Protocol）协议要解决的问题。

简单来说，MCP定义了一套标准，让大模型（如你本地的Qwen2.5）能够“发现”外部工具（你的私有API），并“请求”使用这些工具。而一个实现了MCP协议的服务器（MCP Server），就负责将这些工具暴露给模型，并在模型发出指令时，真正地去执行API调用，然后把结果格式化后返回给模型。这样一来，模型只需要“思考”和“决策”，具体的“执行”交给专业的MCP Server。

所以，今天要聊的“本地大模型 + MCP 协议”，其核心目标就是：打破本地模型的孤岛状态，让它能安全、灵活地调用你拥有的任何私有API，从而将模型的通用能力与你私有的数据、工具相结合，创造出真正个性化的AI应用。接下来，我会以通义千问Qwen2.5-7B-Instruct模型为例，手把手带你搭建这套环境，并实现几个实用的私有API调用案例。

2. 环境搭建：Ollama、MCP Server与客户端的选型与部署

要实现这个目标，我们需要三个核心组件：本地大模型运行时、MCP服务器和MCP客户端。下面我们来逐一拆解选型理由和部署细节。

2.1 本地大模型运行时：为什么是Ollama + Qwen2.5？

在本地运行大模型，Ollama 是目前最省心、生态最活跃的选择。它封装了模型加载、推理优化（通常使用GGUF量化格式）、上下文管理等复杂细节，提供了一个简单的命令行和API接口。对于我们要做的MCP集成，Ollama的标准化API至关重要。

选择Qwen2.5-7B-Instruct模型，主要基于以下几点考虑：

优秀的指令跟随能力：Instruct版本专门针对对话和指令执行进行了微调，在理解“调用工具”这类复杂指令上表现更佳。
适中的资源消耗：7B参数规模在消费级显卡（如RTX 3060 12GB）甚至部分高性能CPU上都能流畅运行，兼顾了能力与可及性。
强大的中文与代码能力：作为国产模型的佼佼者，Qwen在中英文混合场景和代码生成/理解上都有不错的表现，适合处理多样化的任务。
活跃的社区与更新：模型迭代快，问题修复和生态工具支持相对及时。

部署步骤：

# 1. 安装Ollama (以Linux/macOS为例，Windows可直接下载安装包) curl -fsSL https://ollama.com/install.sh | sh # 2. 拉取Qwen2.5-7B-Instruct模型 ollama pull qwen2.5:7b-instruct # 3. 运行模型服务 (默认在11434端口提供API) ollama run qwen2.5:7b-instruct

运行后，Ollama会在本地http://localhost:11434提供一个兼容OpenAI API格式的接口，这是我们后续连接的基础。

2.2 MCP服务器（Server）：你的私有API“翻译官”

MCP Server是核心中的核心，它需要做两件事：

声明工具：告诉外界“我这里有哪些工具（即你的私有API），每个工具叫什么名字，需要什么参数”。
执行调用：当收到调用某个工具的请求时，它负责将请求参数转换成对真实私有API的HTTP调用，并将API返回的结果处理成模型能理解的格式。

你可以用任何语言编写MCP Server，官方提供了Python、TypeScript/JavaScript等SDK。这里我选择Python，因为它生态丰富，写HTTP客户端和数据处理逻辑非常方便。

核心依赖安装：

pip install mcp[cli] httpx pydantic

mcp[cli]：包含了MCP协议的核心库和命令行工具。
httpx：一个现代、异步的HTTP客户端，用于调用你的私有API。
pydantic：用于数据验证和序列化，确保工具参数格式正确。

2.3 MCP客户端（Client）与推理框架：连接模型与Server的“桥梁”

MCP Client负责与MCP Server通信，获取工具列表，并在模型生成过程中，在合适的时机将工具调用请求发送给Server，并等待结果返回给模型。我们不需要从头写一个Client，可以直接使用集成了MCP支持的AI应用开发框架。

这里我推荐LangChain。虽然它有点“重”，但其对MCP的原生支持（通过langchain-mcp-adapters包）是目前最成熟、文档最全的方案之一。它能轻松地将Ollama的模型与MCP Server连接起来。

安装LangChain及相关组件：

pip install langchain langchain-community langchain-mcp-adapters

至此，我们的技术栈就清晰了：Ollama (运行Qwen2.5模型) -> LangChain with MCP (作为Client) -> 自研Python MCP Server -> 你的私有API。接下来，我们从一个最简单的例子开始，编写第一个MCP Server。

3. 实战一：构建你的第一个MCP Server——天气查询工具

让我们从一个最经典的例子开始：让模型调用一个天气查询API。假设我们有一个私有的天气服务，它接受城市名作为参数，返回天气信息。我们将为这个API创建一个MCP工具。

3.1 定义工具与Server

首先，创建一个名为weather_mcp_server.py的文件。

import asyncio from typing import Any import httpx from mcp import ClientSession, StdioServerParameters from mcp.server import Server from mcp.server.models import TextContent from pydantic import BaseModel # 1. 定义工具输入参数的模型（Pydantic） class WeatherQueryInput(BaseModel): city: str # 你可以在这里添加更多参数，如country_code, units等 # 2. 创建MCP Server实例 server = Server("weather-tools-server") # 3. 使用装饰器注册工具 @server.list_tools() async def handle_list_tools() -> list[dict[str, Any]]: # 返回此Server提供的所有工具描述 return [ { "name": "get_current_weather", "description": "获取指定城市的当前天气信息。", "inputSchema": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，例如：北京、Shanghai" } }, "required": ["city"] } } ] # 4. 实现工具的执行逻辑 @server.call_tool() async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]: if name == "get_current_weather": # 验证参数 input_data = WeatherQueryInput(**arguments) city = input_data.city # 这里是调用你私有天气API的地方 # 假设你的API是 GET http://your-private-weather-api/weather?city={city} async with httpx.AsyncClient() as client: try: # 注意：这里替换成你真实的API端点、密钥等 # 示例使用一个模拟的响应 # response = await client.get(f"http://your-private-weather-api/weather", params={"city": city, "api_key": "YOUR_KEY"}) # response.raise_for_status() # weather_data = response.json() # 为了演示，我们模拟一个响应 weather_data = { "city": city, "temperature": 22, "condition": "晴朗", "humidity": 65, "wind_speed": 10 } result_text = f"{city}的当前天气：{weather_data['condition']}，温度{weather_data['temperature']}°C，湿度{weather_data['humidity']}%，风速{weather_data['wind_speed']}km/h。" return [TextContent(type="text", text=result_text)] except httpx.RequestError as e: return [TextContent(type="text", text=f"请求天气API失败：{str(e)}")] except Exception as e: return [TextContent(type="text", text=f"处理天气数据时出错：{str(e)}")] else: raise ValueError(f"未知的工具：{name}") # 5. Server运行入口（使用Stdio通信，这是MCP的标准方式） async def main(): async with await StdioServerParameters(server=server).create_session() as session: await session.run() if __name__ == "__main__": asyncio.run(main())

关键点解析：

@server.list_tools(): 这个装饰器下的函数用于向Client宣告本Server提供了哪些工具。返回的字典必须包含name、description和inputSchema，这直接决定了模型能否正确理解和使用这个工具。
@server.call_tool(): 这个装饰器下的函数是工具的实际执行体。当Client（LangChain）请求调用get_current_weather时，会触发这里的逻辑。
参数验证：使用Pydantic模型WeatherQueryInput来验证传入的参数，确保city字段存在且是字符串。这是避免后续API调用错误的重要一步。
错误处理：在调用真实API时，网络超时、认证失败、API返回错误码（如400, 429, 500）都是常态。必须用try...except包裹，并将友好的错误信息返回给模型，否则整个调用链会中断。

3.2 运行Server并测试

在终端运行这个Server：

python weather_mcp_server.py

Server会以标准输入输出（stdio）模式运行，等待Client连接。接下来，我们需要编写Client代码来连接它和Ollama模型。

4. 实战二：使用LangChain连接MCP Server与Qwen2.5

现在，我们让LangChain扮演MCP Client的角色，它同时连接着Ollama（模型）和我们的Weather MCP Server（工具）。

创建一个新的Python脚本run_agent_with_weather.py。

import asyncio from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain_community.chat_models import ChatOllama from langchain_mcp_adapters import MultiServerMCPClient async def main(): # 1. 初始化LangChain的Ollama聊天模型 # 确保ollama run qwen2.5:7b-instruct 正在运行 llm = ChatOllama( model="qwen2.5:7b-instruct", base_url="http://localhost:11434", temperature=0.1, # 降低随机性，让工具调用更稳定 # 注意：如果遇到上下文长度错误，可能需要调整模型参数或使用支持更长上下文的版本 # 例如：num_ctx=8192 (在Ollama pull时指定) ) # 2. 创建MCP Client并连接我们的Weather Server # 这里假设weather_mcp_server.py在同一个目录运行 async with MultiServerMCPClient() as client: # 添加一个通过stdio连接的Server # 你需要确保weather_mcp_server.py脚本的路径正确 # 这里使用子进程的方式启动Server，LangChain MCP适配器会管理其生命周期 weather_server_params = { "command": "python", "args": ["/path/to/your/weather_mcp_server.py"], # 替换为你的实际路径 "env": {} # 可选的环境变量 } await client.add_server_async("weather", weather_server_params) # 从Client获取所有可用的工具（这里就是我们定义的get_current_weather） tools = await client.get_tools_async() # 3. 构建Agent提示词 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个有帮助的助手，可以调用工具来获取信息。请根据用户的问题，决定是否需要以及调用哪个工具。在回复时，请清晰说明你调用了工具以及工具返回的结果。"), ("placeholder", "{chat_history}"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) # 4. 创建Tool Calling Agent # 这是LangChain提供的一种高级Agent，能很好地处理工具调用逻辑 agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt) # 5. 创建Agent执行器 agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True) # 6. 运行一个查询 question = "上海现在的天气怎么样？" print(f"用户提问: {question}") result = await agent_executor.ainvoke({"input": question}) print(f"助手回复: {result['output']}") # 7. 再试一个不需要工具的问题 question2 = "你好，请做一下自我介绍。" print(f"\n用户提问: {question2}") result2 = await agent_executor.ainvoke({"input": question2}) print(f"助手回复: {result2['output']}") if __name__ == "__main__": asyncio.run(main())

关键点解析与避坑指南：

MultiServerMCPClient: 这是一个可以管理多个MCP Server连接的客户端。我们通过add_server_async方法，以子进程方式启动了我们之前写的Python Server脚本。这意味着LangChain会负责启动、通信和终止这个Server进程，管理起来更方便。
工具获取：await client.get_tools_async()是核心步骤。它向所有已连接的Server请求工具列表，并将它们转换成LangChain的Tool对象列表。这些Tool对象包含了名称、描述和参数模式，LangChain的Agent框架会利用这些信息来指导模型何时以及如何调用工具。
create_tool_calling_agent: 这是LangChain提供的一个“开箱即用”的Agent构造器。它内部使用了bind_tools方法，将工具的定义“注入”到LLM的上下文中，并设置好了消息格式，使得模型（Qwen2.5）能够输出符合特定格式（如JSON）的工具调用请求。这是整个流程能自动化的关键。
temperature参数：在工具调用场景下，建议将温度值设低（如0.1或0）。较高的温度会增加模型输出的随机性，可能导致工具调用的参数格式出错，或者在不该调用工具时乱调用。低温度能保证更确定、更符合指令的输出。
handle_parsing_errors=True: 这个参数非常重要。即使模型输出了不符合预期的工具调用格式，AgentExecutor也不会直接崩溃，而是会将错误信息作为输入重新喂给模型，让它有机会纠正。这大大提高了系统的鲁棒性。
路径问题：在weather_server_params中，args里的Python脚本路径必须是绝对路径或相对于当前工作目录的正确路径，否则会找不到文件。

运行这个脚本，你应该能看到类似以下的输出（Verbose模式会显示详细的思考过程）：

用户提问: 上海现在的天气怎么样？ > 进入新的AgentExecutor链... 思考：用户想知道上海的天气，我需要使用get_current_weather工具。 行动：

{ "action": "get_current_weather", "action_input": {"city": "上海"} }

观察：上海的当前天气：晴朗，温度22°C，湿度65%，风速10km/h。 思考：我已经通过工具获取了上海的天气信息，现在可以回答用户了。 行动：

{ "action": "Final Answer", "action_input": "上海现在的天气是晴朗，气温22摄氏度，湿度65%，风速10公里每小时。" }

上海现在的天气是晴朗，气温22摄氏度，湿度65%，风速10公里每小时。

恭喜！你已经成功搭建了一个能调用私有API的本地AI助手。模型自动识别了用户意图，选择了正确的工具，传入了正确的参数，并基于返回结果生成了自然的回复。 ## 5. 进阶实战：构建多功能MCP Server与复杂场景处理 单一的天气工具显然不够。一个真正的私有API集成平台，需要能同时管理多个工具。让我们升级我们的MCP Server，并处理更复杂的场景。 ### 5.1 构建一个多工具MCP Server 创建一个新的文件 `multi_tools_mcp_server.py`，集成天气查询、待办事项管理和简易计算三个工具。 ```python import asyncio import json from typing import Any import httpx from mcp import ClientSession, StdioServerParameters from mcp.server import Server from mcp.server.models import TextContent from pydantic import BaseModel, Field from datetime import datetime # --- 工具1: 天气查询 (升级版，带缓存示例) --- class WeatherQueryInput(BaseModel): city: str = Field(..., description="城市名称") country_code: str = Field("CN", description="国家代码，默认CN") # 简单的内存缓存，避免频繁调用外部API weather_cache = {} CACHE_TTL = 300 # 5分钟 # --- 工具2: 待办事项管理 --- # 模拟一个内存中的待办列表 todo_list = [] class TodoAddInput(BaseModel): task: str = Field(..., description="待办事项内容") priority: str = Field("medium", description="优先级: low, medium, high") class TodoListInput(BaseModel): filter_status: str = Field("all", description="过滤状态: all, pending, completed") # --- 工具3: 简易计算器 --- class CalculatorInput(BaseModel): expression: str = Field(..., description="数学表达式，例如： (10 + 5) * 2") # --- 创建Server --- server = Server("my-private-tools-server") @server.list_tools() async def handle_list_tools() -> list[dict[str, Any]]: return [ { "name": "get_weather", "description": "查询城市天气，支持国家代码。", "inputSchema": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名"}, "country_code": {"type": "string", "description": "国家代码，如CN, US"} }, "required": ["city"] } }, { "name": "add_todo_item", "description": "添加一个新的待办事项。", "inputSchema": { "type": "object", "properties": { "task": {"type": "string", "description": "任务内容"}, "priority": {"type": "string", "description": "优先级", "enum": ["low", "medium", "high"]} }, "required": ["task"] } }, { "name": "list_todo_items", "description": "列出所有待办事项，可按状态过滤。", "inputSchema": { "type": "object", "properties": { "filter_status": {"type": "string", "description": "过滤状态", "enum": ["all", "pending", "completed"]} } } }, { "name": "calculate", "description": "执行一个简单的数学表达式计算。注意：出于安全考虑，仅支持基本算术。", "inputSchema": { "type": "object", "properties": { "expression": {"type": "string", "description": "数学表达式，如 '3 + 4 * 2'"} }, "required": ["expression"] } } ] @server.call_tool() async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]: if name == "get_weather": input_data = WeatherQueryInput(**arguments) cache_key = f"{input_data.city}_{input_data.country_code}" # 检查缓存 current_time = datetime.now().timestamp() if cache_key in weather_cache: cached_data, timestamp = weather_cache[cache_key] if current_time - timestamp < CACHE_TTL: return [TextContent(type="text", text=f"[缓存] {cached_data}")] # 模拟调用外部API async with httpx.AsyncClient() as client: try: # 这里替换为真实的API调用 # response = await client.get(...) # 模拟延迟和响应 await asyncio.sleep(0.5) mock_response = f"{input_data.city}({input_data.country_code})天气：晴转多云，18-25°C，东南风2级。" # 更新缓存 weather_cache[cache_key] = (mock_response, current_time) return [TextContent(type="text", text=mock_response)] except Exception as e: return [TextContent(type="text", text=f"查询天气失败：{str(e)}")] elif name == "add_todo_item": input_data = TodoAddInput(**arguments) new_item = { "id": len(todo_list) + 1, "task": input_data.task, "priority": input_data.priority, "status": "pending", "created_at": datetime.now().isoformat() } todo_list.append(new_item) return [TextContent(type="text", text=f"已添加待办事项：'{input_data.task}' (优先级: {input_data.priority})")] elif name == "list_todo_items": input_data = TodoListInput(**arguments) filtered_list = todo_list if input_data.filter_status != "all": filtered_list = [item for item in todo_list if item["status"] == input_data.filter_status] if not filtered_list: return [TextContent(type="text", text="当前没有待办事项。")] result_lines = [] for item in filtered_list: result_lines.append(f"- [{item['id']}] {item['task']} (优先级: {item['priority']}, 状态: {item['status']})") return [TextContent(type="text", text="\n".join(result_lines))] elif name == "calculate": input_data = CalculatorInput(**arguments) # 安全警告：直接使用eval是危险的，仅用于演示。 # 在生产环境中，必须使用安全的表达式求值库（如`asteval`）或严格限制字符集。 try: # 极其简单的安全过滤（仅用于演示，不保证安全） allowed_chars = set("0123456789+-*/(). ") if not all(c in allowed_chars for c in input_data.expression): return [TextContent(type="text", text="错误：表达式中包含不安全字符。")] result = eval(input_data.expression) return [TextContent(type="text", text=f"{input_data.expression} = {result}")] except Exception as e: return [TextContent(type="text", text=f"计算表达式 '{input_data.expression}' 时出错：{str(e)}")] else: raise ValueError(f"未知的工具：{name}") async def main(): async with await StdioServerParameters(server=server).create_session() as session: await session.run() if __name__ == "__main__": asyncio.run(main())

5.2 处理复杂查询与工具编排

现在，我们可以用LangChain测试这个更强大的Server。关键在于，当用户提出一个复杂请求时，模型需要能够自主规划并顺序调用多个工具。

更新我们的Client测试脚本，或者创建一个新的run_complex_agent.py。

import asyncio from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain_community.chat_models import ChatOllama from langchain_mcp_adapters import MultiServerMCPClient async def main(): llm = ChatOllama( model="qwen2.5:7b-instruct", base_url="http://localhost:11434", temperature=0.1, ) async with MultiServerMCPClient() as client: # 连接我们新的多功能Server await client.add_server_async("my_tools", { "command": "python", "args": ["/path/to/your/multi_tools_mcp_server.py"], }) tools = await client.get_tools_async() # 使用一个更强调规划和工具使用的系统提示词 prompt = ChatPromptTemplate.from_messages([ ("system", """你是一个强大的助手，拥有多种工具。请仔细分析用户请求，一步步思考。 如果请求需要多个步骤或涉及多个工具，请规划好顺序并依次执行。 在回复最终答案时，请清晰总结你采取的行动和得到的结果。"""), ("placeholder", "{chat_history}"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True, max_iterations=6) # 增加最大迭代次数 # 测试1：混合任务 question1 = "帮我查一下北京和纽约的天气，然后创建一个优先级为高的待办事项，内容是‘对比两地天气写报告’。" print(f"测试1 - 复杂请求: {question1}") result1 = await agent_executor.ainvoke({"input": question1}) print(f"助手回复: {result1['output']}\n") # 测试2：需要计算的任务 question2 = "我有一个项目预算，先计算 (5000 + 1200 * 3) 的结果，然后把这个数字作为‘项目总预算核对’待办事项的内容添加进去，优先级设为中等。" print(f"测试2 - 计算与任务结合: {question2}") result2 = await agent_executor.ainvoke({"input": question2}) print(f"助手回复: {result2['output']}\n") # 测试3：查看结果 question3 = "列出我所有未完成的待办事项。" print(f"测试3 - 查询状态: {question3}") result3 = await agent_executor.ainvoke({"input": question3}) print(f"助手回复: {result3['output']}") if __name__ == "__main__": asyncio.run(main())

运行这个脚本，你将看到Agent如何一步步拆解复杂指令：

对于问题1，它可能会先调用两次get_weather（北京、纽约），然后调用一次add_todo_item。
对于问题2，它会先调用calculate，得到结果8600，然后将这个结果作为task参数的一部分，调用add_todo_item。
问题3则直接调用list_todo_items，并可能设置filter_status为pending。

这里的关键经验是：

max_iterations参数：对于复杂任务，可能需要多次工具调用。这个参数限制了Agent“思考-行动”循环的最大次数，防止陷入死循环。根据任务复杂度适当调高。
系统提示词（System Prompt）：在复杂任务中，系统提示词至关重要。明确的指令如“一步步思考”、“规划好顺序”，能显著提升模型的任务分解和工具调用规划能力。
工具描述的清晰度：在@server.list_tools()中返回的description和inputSchema要尽可能清晰、无歧义。模型的工具调用能力很大程度上依赖于这些元信息的质量。

6. 避坑指南与性能优化：从“跑通”到“好用”

在实际部署中，你会遇到各种各样的问题。下面是我在多次实践中总结出的关键问题和解决方案。

6.1 常见错误与排查

API Error: 400 'type' must be in ["enabled", "disabled", "auto"]
- 问题：这通常是调用Ollama API时，传递了不被支持的参数。例如，在ChatOllama初始化时，错误地传递了OpenAI SDK中才有的stream_options等参数。
- 解决：检查你的LangChainChatOllama初始化参数，确保只使用Ollama官方API文档支持的参数。最安全的做法是只保留model,base_url,temperature等几个核心参数。
API Error: 400 This model's maximum context length is ... tokens. However, your messages resulted in ...
- 问题：提示词（系统提示+历史对话+工具描述）总长度超过了模型的上下文窗口。Qwen2.5-7B的默认上下文可能是4K或8K，当工具很多、描述很长时容易触发。
- 解决：
  - 精简工具描述：在@server.list_tools()中，确保description和inputSchema的description字段言简意赅，移除冗余信息。
  - 使用支持更长上下文的版本：Ollama拉取模型时，可以指定支持更长上下文的变体，例如有些量化版本支持32K上下文。使用ollama pull qwen2.5:7b-instruct-32k（如果存在）。
  - 调整Ollama运行参数：在运行Ollama时，可以通过环境变量或修改Modelfile来增加num_ctx参数。例如，在Ollama WebUI中创建模型副本并修改配置。
  - 流式处理长对话：对于超长对话，需要在应用层实现历史消息的摘要或选择性保留，避免无限增长。
连接失败或Server启动错误
- 问题：MultiServerMCPClient无法启动子进程，或stdio通信失败。
- 排查：
  - 检查Python脚本路径是否正确、有无语法错误。
  - 确保asyncio事件循环正确运行（在脚本入口使用asyncio.run(main())）。
  - 查看Server脚本是否有打印错误信息（标准错误输出可能被LangChain捕获）。
  - 尝试先用最简单的“Hello World”式MCP Server测试连通性。
模型不调用工具或调用参数错误
- 问题：模型直接回答了问题，而没有调用工具；或者调用了工具但参数格式不对。
- 解决：
  - 强化系统提示词：在系统提示中明确要求“你必须使用工具来获取信息”或“如果你需要XXX信息，请调用YYY工具”。
  - 检查工具描述：确保工具名称、参数名称和描述清晰无误。模糊的描述会导致模型困惑。
  - 调整温度：将temperature设为0或接近0的值，减少随机性。
  - 使用更强大的模型：如果7B模型效果不佳，可以尝试14B或更大参数的模型，它们在工具调用和指令跟随上通常更强。

6.2 性能与稳定性优化

MCP Server的异步与并发：我们的Server使用了async/await，这是正确的。确保在调用外部API时使用异步HTTP客户端（如httpx.AsyncClient），避免阻塞事件循环。如果你的工具涉及耗时操作（如查询大型数据库），考虑在Server内使用线程池来执行，防止阻塞其他工具请求。
工具调用的超时与重试：在@server.call_tool()的实现中，应该为外部API调用设置超时（httpx有timeout参数）。对于可能因网络波动失败的非关键操作，可以实现简单的重试逻辑。
Ollama模型加载优化：首次运行或切换模型时，Ollama需要加载模型到显存/内存，这会耗时数秒到数十秒。在生产环境中，可以考虑：
- 使用ollama serve在后台常驻一个模型服务。
- 对于多个工具频繁调用的场景，确保Ollama服务保持运行，避免频繁冷启动。
安全性考量：
- 计算工具的安全：上面的计算器示例使用了eval，这是极其危险的，绝对不要在生产环境中使用。应替换为安全的库，如asteval，或仅实现一个受限的算术表达式解析器。
- 私有API的认证：在调用真正的私有API时，认证信息（如API Key）不应硬编码在代码中。可以通过环境变量、配置文件或安全的密钥管理服务来获取。
- 输入验证与清理：Pydantic模型提供了基础验证。对于字符串参数，还应警惕SQL注入、命令注入等攻击。在将用户输入（来自模型，但源头是用户）传递给底层API前，进行严格的验证和清理。
错误信息的友好化：MCP Server返回的错误信息会被模型看到。设计错误信息时，应提供足够的信息让模型理解问题所在（例如，“城市名称不能为空”比“参数错误”更好），但又不能泄露系统内部细节（如数据库结构、服务器路径）。

7. 扩展思路：将MCP集成到更广阔的生态

掌握了基础搭建后，你可以探索更多可能性：

连接真实的私有API：将示例中的模拟调用替换为对你内部系统的真实HTTP请求。可以是REST API，也可以是GraphQL。使用httpx可以轻松处理各种认证方式（Bearer Token, API Key, OAuth2等）。
集成数据库与知识库：创建一个“知识查询”工具，接收用户问题，将其转换为数据库查询语句（或调用向量数据库的检索接口），返回相关信息。这相当于为模型接上了私有的“长期记忆”。
与桌面自动化结合：通过MCP Server调用本地脚本或程序，实现文件操作、发送邮件、控制音乐播放器等桌面自动化任务。这需要Server有权限执行这些本地命令，需格外注意安全。
使用MCP Inspector进行调试：Anthropic官方提供了一个图形化的MCP调试工具@modelcontextprotocol/inspector。你可以用它单独连接和测试你的MCP Server，观察工具列表和调用过程，这对于开发和调试非常有帮助。
探索其他MCP客户端：除了LangChain，其他框架如Claude Desktop、Cursor IDE、Continue.dev等也开始支持MCP。这意味着你编写的MCP Server可以同时为多个AI应用提供工具，实现“一次编写，多处使用”。

本地大模型通过MCP协议调用私有API，这套组合拳真正释放了AI的潜力。它不再是那个只能泛泛而谈的“百科全书”，而是变成了一个能真正为你做事、操作你私有数据和系统的智能伙伴。从简单的天气查询到复杂的业务流程编排，边界只取决于你为它提供了什么样的“工具”。搭建过程虽然涉及多个组件，但每一步都有成熟的工具和协议支持，一旦跑通，后续的扩展就会变得非常顺畅。我最深刻的体会是，清晰的工具定义（name, description, schema）和一个稳定的模型（如Qwen2.5）是成功的关键。开始动手为你自己的场景打造第一个工具吧，你会发现一个全新的、高度个性化的AI工作流正在眼前展开。

日记详情

本地大模型如何通过MCP协议调用私有API：从Ollama部署到LangChain集成实战