MCP协议从入门到实战：手把手搭建AI Agent工具调用系统

一、背景：为什么需要MCP？

说实话，半年前我第一次接触AI Agent开发的时候，最头疼的问题不是模型能力不够，而是怎么让AI"碰到"真实世界。

你想啊，大模型再强，它也只是一个"会说话的脑子"。你想让它查数据库、发邮件、调用API，它做不到。除非你给它写一堆工具函数，然后手动编排调用逻辑。

但问题来了——每个Agent都要重新写一套工具集成，每换一个模型就要重新适配API。这活儿干一次还行，干十次就真的想骂人了。

MCP（Model Context Protocol）就是来解决这个问题的。它是由Anthropic提出的一种开放协议，目的是让AI模型和外部工具之间有一个标准化的通信方式。说白了，就是给AI装一个"USB接口"，你想插什么工具就插什么。

二、MCP核心概念

MCP的核心就三个东西：Client、Server、Tool。

2.1 Client（客户端）

Client是"宿主"，也就是运行AI模型的地方。它可以是一个CLI工具、一个IDE插件、或者一个Web应用。Client负责：

• 连接MCP Server
• 把Server暴露的工具列表告诉模型
• 把模型的工具调用请求转发给Server
• 把Server的返回结果送回给模型

2.2 Server（服务器）

Server是"工具提供方"。每个MCP Server可以暴露一个或多个工具。比如一个"文件系统Server"可以提供读写文件、列目录等工具。

2.3 Tool（工具）

Tool是具体的能力单元。一个工具包含：

• 名称（name）
• 描述（description）
• 输入参数定义（input schema）
• 执行函数（handler）

@mcp.tool()
async def search_web(query: str, max_results: int = 5) -> str:
    """搜索互联网并返回结果"""
    results = await web_search(query, max_results)
    return format_results(results)

三、环境准备

在开始之前，你需要准备以下环境：

组件	版本要求	备注
Python	>= 3.10	推荐3.12
Node.js	>= 18	运行MCP Inspector
pip	最新版	安装Python包

# 安装MCP Python SDK
pip install mcp

# 安装MCP CLI工具
npm install -g @modelcontextprotocol/inspector

四、实战：搭建一个文件搜索Agent

接下来我们手写一个实战案例：一个能搜索本地文件的AI Agent。

4.1 创建MCP Server

# file_search_server.py
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio
import mcp.types as types
import os
import fnmatch

# 创建Server实例
server = Server("file-search")

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="find_files",
            description="在指定目录中搜索文件，支持通配符",
            inputSchema={
                "type": "object",
                "properties": {
                    "directory": {
                        "type": "string",
                        "description": "要搜索的目录路径"
                    },
                    "pattern": {
                        "type": "string",
                        "description": "文件通配符模式，如 *.py"
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "最大返回结果数",
                        "default": 20
                    }
                },
                "required": ["directory", "pattern"]
            }
        )
    ]

@server.call_tool()
async def handle_call_tool(
    name: str, arguments: dict
) -> list[types.TextContent]:
    if name == "find_files":
        directory = arguments["directory"]
        pattern = arguments["pattern"]
        max_results = arguments.get("max_results", 20)
        
        results = []
        for root, dirs, files in os.walk(directory):
            for filename in fnmatch.filter(files, pattern):
                full_path = os.path.join(root, filename)
                results.append(full_path)
                if len(results) >= max_results:
                    break
            if len(results) >= max_results:
                break
        
        return [types.TextContent(
            type="text",
            text=f"找到 {len(results)} 个匹配文件:\n" + "\n".join(results)
        )]
    raise ValueError(f"未知工具: {name}")

async def main():
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="file-search",
                server_version="1.0.0",
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                ),
            ),
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

4.2 启动Server并测试

# 启动MCP Server
python file_search_server.py

# 在另一个终端中，用MCP Inspector测试
npx @modelcontextprotocol/inspector python file_search_server.py

这样你就有了一个可以通过MCP协议暴露的"文件搜索"工具。任何支持MCP的AI Client都可以调用它。

五、将MCP接入Claude Code

如果你在用Claude Code，只需要在配置文件里注册MCP Server：

// claude_desktop_config.json
{
  "mcpServers": {
    "file-search": {
      "command": "python",
      "args": ["path/to/file_search_server.py"]
    }
  }
}

重启Claude Code后，它就能自动发现并调用file_search工具了。你可以直接说"帮我找一下最近修改的Python文件"，Claude会自己调用find_files工具来完成。

六、常见问题

Q: MCP和Function Calling有什么区别？
A: Function Calling是模型的能力，MCP是工具通信协议。两者是互补关系——MCP定义"怎么暴露工具"，Function Calling定义"模型怎么调用工具"。

Q: 一个Server可以暴露多个工具吗？
A: 可以，在handle_list_tools里返回多个Tool对象就行。

Q: MCP支持流式输出吗？
A: 支持。MCP协议支持text streaming，Server可以逐步返回结果。

Q: 安全性如何？
A: 每个Server都在独立的进程中运行，Client控制权限。建议不要以root权限运行MCP Server。

七、总结

MCP协议让AI Agent的工具集成变得标准化了。你不用再为每个框架写一套工具适配层，一套MCP Server走天下。说实话，这玩意儿虽然刚出来不久，但生态已经起来了——从文件系统到数据库到浏览器，各种MCP Server层出不穷。

下一步你可以试试：

• 自己写一个MCP Server，连上你常用的内部API
• 在MCP Hub上找别人写好的Server
• 把MCP集成到你自己的AI应用里

有问题欢迎在评论区留言，一起交流。