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 Client | AI 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: 100JSON 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框架集成 |