Skip to content

MCP 协议详解 ​

Model Context Protocol — 标准化的工具调用协议


📋 什么是 MCP? ​

MCP(Model Context Protocol) 是一种用于连接 AI 模型与外部工具和数据源的标准化协议。它允许 AI Agent 通过统一的接口调用各种工具,而无需关心工具的具体实现细节。

核心价值:

  • ✅ 标准化:统一的工具描述和调用格式
  • ✅ 安全性:内置的权限控制和安全检查
  • ✅ 可扩展性:轻松添加新工具
  • ✅ 互操作性:不同框架和模型之间的无缝集成

🏗️ MCP 架构 ​

协议架构 ​

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     AI Model    │ ←→  │    MCP Server   │ ←→  │   MCP Tools     │
│   (Agent)       │     │  (Broker)       │     │  (Plugins)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                      │                      │
         │ 1. 请求工具列表       │ 2. 注册工具          │
         │ 2. 调用工具          │ 3. 执行工具          │
         │ 3. 获取结果          │ 4. 返回结果          │
         └──────────────────────┘                      │
                                                       │
                                    ┌──────────────────┘
                                    ▼
                          ┌─────────────────┐
                          │   安全策略      │
                          │  (Security)     │
                          └─────────────────┘

核心组件 ​

组件职责
MCP ClientAI Agent 端,发起工具调用请求
MCP Server中间代理,管理工具注册和调用路由
MCP Tool具体工具实现,执行实际操作
Security Layer安全层,处理认证、授权、审计

🔧 工具定义 ​

工具描述格式 ​

yaml
name: "web_search"
description: "搜索互联网获取最新信息"
version: "1.0.0"
author: "Harness Engineering"
license: "MIT"

inputs:
  - name: "query"
    type: "string"
    description: "搜索查询词"
    required: true
    max_length: 200
  
  - name: "max_results"
    type: "integer"
    description: "最大返回结果数"
    required: false
    default: 5
    minimum: 1
    maximum: 20

outputs:
  - name: "results"
    type: "array"
    description: "搜索结果列表"
    items:
      type: "object"
      properties:
        title:
          type: "string"
          description: "标题"
        url:
          type: "string"
          description: "链接"
        snippet:
          type: "string"
          description: "摘要"

metadata:
  category: "information"
  risk_level: "low"
  rate_limit: 100

JSON Schema 定义 ​

json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Web Search Tool",
  "description": "搜索互联网获取最新信息",
  "properties": {
    "name": {
      "type": "string",
      "const": "web_search"
    },
    "description": {
      "type": "string"
    },
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "搜索查询词"
        },
        "max_results": {
          "type": "integer",
          "description": "最大返回结果数",
          "default": 5,
          "minimum": 1,
          "maximum": 20
        }
      },
      "required": ["query"]
    },
    "returns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string" },
          "snippet": { "type": "string" }
        }
      }
    }
  },
  "required": ["name", "description", "parameters"]
}

🚀 工具开发 ​

基础工具实现 ​

python
from mcp import MCPTool, ToolInput, ToolOutput
from typing import List, Dict, Optional

class WebSearchTool(MCPTool):
    """Web搜索工具"""
    
    name = "web_search"
    description = "搜索互联网获取最新信息"
    version = "1.0.0"
    
    async def execute(
        self,
        query: str,
        max_results: int = 5
    ) -> ToolOutput:
        """执行搜索"""
        # 调用搜索API
        results = await self._search(query, max_results)
        
        return ToolOutput(
            success=True,
            data={
                "results": results
            },
            message="搜索成功"
        )
    
    async def _search(self, query: str, max_results: int) -> List[Dict]:
        """内部搜索实现"""
        # 这里可以调用真实的搜索API
        return [
            {
                "title": f"搜索结果 {i+1}",
                "url": f"https://example.com/result/{i}",
                "snippet": f"关于'{query}'的搜索结果摘要..."
            }
            for i in range(max_results)
        ]

工具注册 ​

python
from mcp import MCPServer

# 创建MCP服务器
server = MCPServer(
    name="Harness MCP Server",
    version="1.0.0",
    description="企业级AI Agent工具服务器"
)

# 注册工具
server.register_tool(WebSearchTool())

# 注册更多工具
from tools import (
    CalculatorTool,
    FileReadTool,
    FileWriteTool,
    EmailTool,
    DatabaseTool
)

server.register_tool(CalculatorTool())
server.register_tool(FileReadTool())
server.register_tool(FileWriteTool())
server.register_tool(EmailTool())
server.register_tool(DatabaseTool())

# 启动服务器
server.run(host="localhost", port=8080)

🔄 工具调用流程 ​

Client 端调用 ​

python
from mcp import MCClient

# 创建客户端
client = MCClient("http://localhost:8080")

# 获取工具列表
tools = await client.list_tools()
for tool in tools:
    print(f"- {tool.name}: {tool.description}")

# 调用工具
result = await client.call_tool(
    name="web_search",
    params={
        "query": "2026年AI趋势",
        "max_results": 5
    }
)

# 处理结果
if result.success:
    for item in result.data["results"]:
        print(f"标题: {item['title']}")
        print(f"链接: {item['url']}")
        print(f"摘要: {item['snippet']}")
else:
    print(f"调用失败: {result.message}")

工具调用协议 ​

请求格式 ​

json
{
  "jsonrpc": "2.0",
  "id": "12345",
  "method": "tool.call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "2026年AI趋势",
      "max_results": 5
    },
    "context": {
      "agent_id": "agent_001",
      "task_id": "task_123",
      "user_id": "user_456"
    }
  }
}

响应格式 ​

json
{
  "jsonrpc": "2.0",
  "id": "12345",
  "result": {
    "success": true,
    "data": {
      "results": [
        {
          "title": "2026年AI趋势预测",
          "url": "https://example.com/ai-trends-2026",
          "snippet": "2026年AI将继续快速发展..."
        }
      ]
    },
    "message": "搜索成功",
    "metadata": {
      "execution_time": 1200,
      "token_usage": 0,
      "cost": 0.001
    }
  }
}

🛡️ 安全机制 ​

认证与授权 ​

python
from mcp.security import (
    APIKeyAuth,
    JWTBearerAuth,
    PermissionChecker
)

# API Key 认证
api_key_auth = APIKeyAuth(
    api_key="your-api-key",
    header_name="X-MCP-API-Key"
)

# JWT Bearer 认证
jwt_auth = JWTBearerAuth(
    secret="your-secret",
    algorithm="HS256"
)

# 权限检查
permission_checker = PermissionChecker()
permission_checker.add_permission(
    tool="web_search",
    role="user",
    allowed=True
)
permission_checker.add_permission(
    tool="file_write",
    role="user",
    allowed=False
)

# 配置安全层
server = MCPServer(
    name="Harness MCP Server",
    auth=[api_key_auth, jwt_auth],
    permission_checker=permission_checker
)

请求验证 ​

python
from mcp.validation import InputValidator

class WebSearchTool(MCPTool):
    """带验证的搜索工具"""
    
    async def execute(self, query: str, max_results: int = 5) -> ToolOutput:
        # 验证输入
        validator = InputValidator()
        validator.add_rule("query", "min_length", 1)
        validator.add_rule("query", "max_length", 200)
        validator.add_rule("query", "no_sql_injection")
        validator.add_rule("max_results", "range", (1, 20))
        
        errors = validator.validate({
            "query": query,
            "max_results": max_results
        })
        
        if errors:
            return ToolOutput(
                success=False,
                message=f"输入验证失败: {', '.join(errors)}"
            )
        
        # 执行搜索
        results = await self._search(query, max_results)
        return ToolOutput(
            success=True,
            data={"results": results}
        )

审计日志 ​

python
from mcp.audit import AuditLogger

class AuditMiddleware:
    """审计中间件"""
    
    def __init__(self, logger: AuditLogger):
        self.logger = logger
    
    async def process_request(self, request, next_handler):
        """处理请求前记录"""
        self.logger.log({
            "action": "tool_call_start",
            "tool_name": request.params["name"],
            "agent_id": request.context.get("agent_id"),
            "user_id": request.context.get("user_id"),
            "timestamp": time.time()
        })
        
        # 调用下一个处理器
        response = await next_handler(request)
        
        # 处理请求后记录
        self.logger.log({
            "action": "tool_call_end",
            "tool_name": request.params["name"],
            "success": response.result.get("success"),
            "execution_time": response.result.get("metadata", {}).get("execution_time"),
            "timestamp": time.time()
        })
        
        return response

# 使用审计中间件
audit_logger = AuditLogger(file_path="audit.log")
server.add_middleware(AuditMiddleware(audit_logger))

🔗 与 Agent 框架集成 ​

LangChain 集成 ​

python
from langchain.tools import MCPTool as LangChainMCPTool

# 加载MCP工具
mcp_tool = LangChainMCPTool.from_server("http://localhost:8080")

# 获取工具列表
tools = mcp_tool.get_tools()

# 创建Agent
from langchain.agents import create_tool_calling_agent
from langchain.agents import AgentExecutor

agent = create_tool_calling_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools)

# 执行Agent
result = agent_executor.invoke({
    "input": "搜索2026年AI趋势并总结"
})

CrewAI 集成 ​

python
from crewai import Agent, Task, Crew
from crewai_tools import MCPServerTool

# 创建工具
mcp_tools = MCPServerTool("http://localhost:8080")

# 创建Agent
researcher = Agent(
    role="AI研究员",
    goal="搜索最新AI资讯",
    backstory="你是一位专业的AI研究员",
    tools=[mcp_tools.web_search]
)

# 创建任务
task = Task(
    description="搜索2026年AI趋势并撰写报告",
    agent=researcher
)

# 创建Crew
crew = Crew(
    agents=[researcher],
    tasks=[task]
)

# 执行
result = crew.kickoff()

🔧 工具开发最佳实践 ​

错误处理 ​

python
class SafeDatabaseTool(MCPTool):
    """安全的数据库工具"""
    
    async def execute(self, query: str) -> ToolOutput:
        try:
            # 安全检查
            if not self._is_safe_query(query):
                return ToolOutput(
                    success=False,
                    message="危险的SQL查询"
                )
            
            # 执行查询
            result = await self._execute_query(query)
            return ToolOutput(
                success=True,
                data={"result": result}
            )
        
        except Exception as e:
            # 记录错误但不泄露敏感信息
            self.logger.error(f"数据库查询失败: {e}")
            return ToolOutput(
                success=False,
                message="数据库操作失败,请联系管理员"
            )
    
    def _is_safe_query(self, query: str) -> bool:
        """检查查询安全性"""
        dangerous_patterns = ["DROP", "DELETE", "TRUNCATE", "UPDATE"]
        return not any(pattern in query.upper() for pattern in dangerous_patterns)

性能优化 ​

python
from mcp.caching import ToolCache

class CachedSearchTool(MCPTool):
    """带缓存的搜索工具"""
    
    def __init__(self):
        super().__init__()
        self.cache = ToolCache(ttl=3600)  # 1小时缓存
    
    async def execute(self, query: str, max_results: int = 5) -> ToolOutput:
        # 检查缓存
        cache_key = f"search:{query}:{max_results}"
        cached_result = self.cache.get(cache_key)
        
        if cached_result:
            return ToolOutput(
                success=True,
                data=cached_result,
                message="从缓存获取"
            )
        
        # 执行搜索
        results = await self._search(query, max_results)
        
        # 存入缓存
        self.cache.set(cache_key, results)
        
        return ToolOutput(
            success=True,
            data={"results": results},
            message="搜索成功"
        )

🔗 快速导航 ​

章节内容
项目概述MCP 核心概念与架构
工具定义工具描述格式与规范
工具开发工具实现与注册
安全机制认证、授权、审计
集成指南与Agent框架集成