AI Agent 实战：MCP 协议接入与工具调用排障

Agent 的能力边界就是它能调用的工具。MCP（Model Context Protocol）把“工具接入”标准化了：server 提供工具，client 负责调用，模型只管决定什么时候调哪个。这样一来，工具写一次，到处都能用。这篇讲 MCP 的结构、接入现成 server、自己写 server 与排障。

一、MCP 长什么样

• Host：跑模型和 Agent 的程序，比如 Claude Desktop、各类 Agent 框架。
• Client：Host 里负责和 server 说话的组件，一对一连一个 server。
• Server：提供工具的程序，可以是本地进程，也可以是远程服务。
• 协议：JSON-RPC 2.0，传输分两种：stdio（本地子进程，简单）和 SSE / Streamable HTTP（远程服务）。
• 三种能力：Tools（模型能调用的函数）、Resources（能读的数据）、Prompts（预设的提示词模板）。

二、接入一个现成的 MCP server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/eda/proj"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=Asia/Shanghai"]
    }
  }
}

配置就这几行：server 的名字、启动命令、参数。配好重启 client，模型就能调用 filesystem 的读写工具和 time 的时间工具。先从官方的 server 玩起：filesystem、fetch、memory、sequential-thinking，都是练手的好材料。

三、自己写一个 MCP server（Python FastMCP）

# pip install fastmcp
from fastmcp import FastMCP
import subprocess

mcp = FastMCP("eda-ops")

@mcp.tool()
def license_usage(feature: str) -> str:
    """查某个 EDA license feature 的占用情况"""
    out = subprocess.check_output(
        ["lmstat", "-f", feature, "-c", "27000@lic-server"], text=True)
    return out

@mcp.tool()
def disk_usage(path: str = "/eda/proj") -> str:
    """查指定目录的磁盘占用"""
    out = subprocess.check_output(["df", "-h", path], text=True)
    return out

if __name__ == "__main__":
    mcp.run()

一个 @mcp.tool() 就是一个工具：函数名是工具名，docstring 是给模型的说明，参数类型就是 schema。写好之后在 client 配置里加一行，模型就能直接问“VCS 的 license 还剩多少”，自己调工具查，不用你写脚本。

四、排障：最常见的四个问题

• stdio 握手失败：server 启动就退出，先手动跑一遍启动命令，看报错；多数是依赖没装或者路径不对。
• 超时：工具执行太慢，client 默认超时就断。耗时操作要异步，或者调大超时时间。
• 工具 schema 不对：参数类型和模型传的不一致，检查类型注解和必填项，别让模型猜。
• 权限：server 以 client 的身份运行，能读什么取决于启动它的用户，别指望它越权干活。

五、运维要点

• 进程托管：远程 server 用 systemd 托管，挂了自动拉起来；本地 stdio 的不用管，client 会拉起来。
• 日志：server 的日志打到文件，别打到 stdout，stdio 传输走的就是 stdout，日志混进去协议就乱了。
• 版本：工具改了参数要同步更新说明，模型按旧说明调用就会报错；工具名和参数名一旦发布就别乱改。
• 安全：工具能干什么，模型就能干什么。删文件、跑命令这类危险工具要加确认或者白名单，别全开。

MCP 的价值就一句：工具和模型解耦。工具写一次，哪个模型、哪个 Agent 都能用；模型换了，工具不用重写。先把自己最常用的两三个运维操作包成工具，Agent 马上就能帮你干活。

Mr丶点心

打赏 海报 链接