前言

2026 年初，在探索 AI Agent 开发时，我频繁接触到 MCP（Model Context Protocol） 这个概念。作为 Anthropic 于 2024 年 11 月推出的开放标准，MCP 已逐步成为连接 AI 模型与外部数据源的重要协议。本文记录我学习 MCP 的全过程，希望能帮助同样想入门的朋友少走弯路。

学习背景：有一定的 AI 开发经验，希望深入了解如何让 AI 模型更好地与外部系统交互。

---

一、初识 MCP：概念理解

MCP 是什么？

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 于 2024 年 11 月推出的开放标准。简单来说，它定义了一套规范，让 AI 应用能够标准化地连接各种数据源和工具。

官方定义是：

MCP enables communication between the system and locally running MCP servers that provide additional tools and resources to extend your capabilities.

翻译过来：MCP 让系统能够与本地运行的 MCP 服务器通信，这些服务器提供额外的工具和资源来扩展 AI 的能力。

为什么需要 MCP？

在学习之前，我一直有个疑问：为什么需要一个新的协议？

理解了背景后，答案就很清晰了：

痛点	传统方案	MCP 方案
数据孤岛	AI 无法直接访问企业数据	标准化接口连接各种数据源
集成复杂	每个数据源单独开发对接	统一协议，一次开发多处复用
扩展困难	新增数据源需要改代码	无需改动 AI 应用，接入新 Server 即可
维护成本	碎片化集成难以维护	模块化架构，易于管理

一个形象的比喻

如果把 AI 模型比作一台电脑，那么：

• 没有 MCP：想连接打印机、硬盘、显示器，每种设备都需要专门的驱动和接口，很麻烦
• 有了 MCP：就像有了 USB-C 接口，所有设备统一标准，即插即用

这个比喻让我清晰理解了 MCP 的核心价值——标准化。

---

二、架构理解：组件与通信

Host-Client-Server 三层架构

MCP 采用经典的客户端-服务器架构，理解这三者的关系是学习 MCP 的基础：

┌─────────────────────────────────────┐
│          MCP Host（宿主应用）          │
│    例如：Claude Desktop、IDE 插件      │
└──────────────┬──────────────────────┘
               │ 管理多个连接
       ┌───────┼───────┐
       ▼       ▼       ▼
   ┌───────┐ ┌───────┐ ┌───────┐
   │Client1│ │Client2│ │Client3│
   └───┬───┘ └───┬───┘ └───┬───┘
       │         │         │
       ▼         ▼         ▼
   ┌───────┐ ┌───────┐ ┌───────┐
   │Server1│ │Server2│ │Server3│
   │文件系统│ │数据库  │ │API服务│
   └───────┘ └───────┘ └───────┘

三大组件职责：

组件	定义	职责
Host	运行 AI 模型的应用程序	管理连接、协调交互、处理请求
Client	协议客户端	维护与 Server 的连接、数据序列化
Server	提供能力的轻量程序	暴露资源、工具、提示模板

三大核心概念：Resources、Tools、Prompts

这是 MCP 最核心的设计，理解这三个概念就理解了 MCP：

1. Resources（资源）

只读数据，让 AI 能够访问但不修改的内容：

• 文件内容（代码、文档、配置）
• 数据库查询结果
• API 响应数据

@server.list_resources()
async def list_resources() -> list[Resource]:
    return [
        Resource(
            uri="file:///src/main.py",
            name="main.py",
            mimeType="text/x-python"
        )
    ]

2. Tools（工具）

可执行操作，让 AI 能够执行具体任务：

• 文件写入
• API 调用
• 数据库更新

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="write_file",
            description="Write content to a file",
            inputSchema={
                "type": "object",
                "properties": {
                    "path": {"type": "string"},
                    "content": {"type": "string"}
                }
            }
        )
    ]

3. Prompts（提示模板）

可重用的提示，标准化 AI 交互：

@server.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="analyze_code",
            description="Analyze code structure and quality",
            arguments=[
                PromptArgument(name="file_path", required=True)
            ]
        )
    ]

通信机制：JSON-RPC 2.0

MCP 基于 JSON-RPC 2.0 协议，支持三种传输方式：

传输方式	适用场景	特点
stdio	本地进程通信	最简单，适合入门
HTTP	网络通信	跨机器访问
WebSocket	实时双向通信	支持推送订阅

一个典型的初始化消息：

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1,
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": {"subscribe": true},
      "tools": {"listChanged": true}
    }
  }
}

---

三、搭建过程：从零开始

环境准备

前置条件：

• Python 3.10+ 或 Node.js 18+
• 安装官方 SDK

# Python 版本（官方 SDK）
pip install mcp

# 或使用 FastMCP（更易用的封装）
pip install fastmcp

# Node.js 版本
npm install @modelcontextprotocol/sdk

注意：安装前建议创建虚拟环境，避免依赖冲突。

创建第一个 MCP Server

我选择用 Python 创建一个简单的文件系统 Server：

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, Resource
import os

# 创建 Server 实例
server = Server("my-first-server")

@server.list_resources()
async def list_resources():
    """列出当前目录的文件"""
    resources = []
    for file in os.listdir("."):
        if os.path.isfile(file):
            resources.append(
                Resource(
                    uri=f"file:///{file}",
                    name=file,
                    mimeType="text/plain"
                )
            )
    return resources

@server.read_resource()
async def read_resource(uri: str):
    """读取文件内容"""
    path = uri.replace("file:///", "")
    with open(path, "r") as f:
        return f.read()

@server.list_tools()
async def list_tools():
    """提供工具列表"""
    return [
        Tool(
            name="list_files",
            description="List all files in current directory",
            inputSchema={"type": "object", "properties": {}}
        )
    ]

# 启动服务器
async def main():
    async with stdio_server() as streams:
        await server.run(streams[0], streams[1])

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

在 Claude Desktop 中配置

创建配置文件 claude_desktop_config.json，不同系统配置文件位置如下：

系统	配置文件路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

配置内容示例：

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["C:/Users/yourname/projects/mcp-server/server.py"]
    }
  }
}

Windows 用户注意：路径使用正斜杠 / 或双反斜杠 \\，避免转义问题。

配置完成后重启 Claude Desktop，就能看到 Server 提供的工具和资源了。

---

四、踩坑经验：问题与解决

在学习过程中，遇到了不少问题，这里记录下来供参考：

问题 1：Server 启动失败

现象：配置后 Claude Desktop 提示连接失败

原因：路径配置错误，使用了相对路径

解决：使用绝对路径，并且注意 Windows 路径格式

// ❌ 错误
"args": ["./server.py"]

// ✅ 正确
"args": ["C:/Users/xxx/projects/server.py"]

问题 2：Python 版本不兼容

现象：运行 Server 报 TypeError 错误

原因：Python 版本过低，MCP SDK 需要 3.10+

解决：升级 Python 或使用 pyenv 管理多版本

# 检查版本
python --version

# 使用 pyenv 切换版本
pyenv install 3.11
pyenv local 3.11

问题 3：权限问题

现象：资源访问被拒绝

原因：Server 没有文件系统权限

解决：在配置中明确指定允许访问的目录，或使用沙盒模式

问题 4：调试困难

现象：Server 运行但 Claude 无法识别

解决方法：

1. 使用官方提供的 Inspector 工具：

npx @modelcontextprotocol/inspector python your_server.py

2. 添加日志输出：

import logging
logging.basicConfig(level=logging.DEBUG)

---

五、应用场景思考

通过学习，我认为 MCP 在以下场景中有很大潜力：

场景一：代码库分析

让 AI 直接访问项目文件，实现：

• 智能代码审查
• 自动生成文档
• 依赖分析

场景二：数据库查询

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="execute_sql",
            description="Execute SQL query",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                }
            }
        )
    ]

AI 可以直接查询数据库，实现自然语言转 SQL。

场景三：企业知识库

将企业内部文档暴露为 Resources，配合 RAG 实现：

• 智能问答
• 文档检索
• 知识汇总

---

总结

学习收获

1. 理解了 MCP 的核心价值：标准化解决 AI 数据孤岛问题
2. 掌握了基本架构：Host-Client-Server 三层，三大核心概念
3. 跑通了 Demo：成功创建并连接了第一个 MCP Server
4. 避开了常见坑：路径配置、版本兼容、权限问题

对 MCP 的期待

作为一个开放标准，MCP 还在快速发展中。期待：

• 更多官方 Server 模板
• 更完善的调试工具
• 更广泛的生态支持

给初学者的建议

1. 从 stdio 开始：这是最简单的传输方式，适合入门
2. 使用 Inspector：调试神器，能帮你快速定位问题
3. 多看官方示例：Anthropic 提供了很多参考实现
4. 循序渐进：先实现 Resources，再加 Tools，最后考虑 Prompts

---

参考资料

• MCP 官方文档
• Anthropic MCP GitHub
• 深入理解 MCP：架构解析与开发实践

---

本文首发于 CSDN，记录个人学习心得，欢迎交流讨论。