MCP 协议入门：MCP 服务器的发现和调用
MCP 服务器的配置和发现
MCP 主机会通过配置文件来发现和管理 MCP 服务器。不同的 MCP 主机可能有不同的配置方式，但通常都遵循类似的模式。
配置文件结构
以 Cursor 为例，MCP 服务器的配置通常存储在配置文件中，格式如下：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key-here"
}
}
}
}
配置文件中每个服务器条目包含： - command：启动服务器所需的命令 - args：传递给命令的参数数组 - env（可选）：环境变量，用于传递 API 密钥等敏感信息
服务器发现流程
MCP 主机的服务器发现流程通常包括以下步骤：
- 读取配置文件：MCP 主机启动时读取配置文件，获取所有已配置的 MCP 服务器信息
- 验证服务器可用性：检查服务器命令是否可执行，所需依赖是否已安装
- 初始化连接：为每个配置的服务器创建 MCP 客户端实例
- 建立通信通道：根据配置选择 stdio 或 HTTP 传输方式建立连接
连接建立过程
MCP 客户端和服务器之间的连接建立遵循标准的握手流程：
初始化请求（Initialize Request）
连接建立后，客户端首先发送 initialize 请求，服务器响应包含服务器的能力和信息。
初始化完成（Initialized Notification）
初始化成功后，客户端发送 initialized 通知，表示握手完成。
MCP 服务器的调用方式
MCP 服务器主要提供三类功能：工具（Tools）、资源（Resources）和提示（Prompts）。客户端通过 JSON-RPC 方法调用来使用这些功能。
工具（Tools）调用
工具是 MCP 服务器提供的可执行操作，类似于函数调用。客户端可以列出可用工具，然后调用特定工具。
列出可用工具
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}
服务器响应：
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "read_file", // 工具名称
"description": "读取文件内容", // 工具描述
"inputSchema": { // 输入参数模式（JSON Schema）
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "文件路径"
}
},
"required": ["path"] // 必需参数
}
}
]
}
}
调用工具
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call", // 调用工具方法
"params": {
"name": "read_file", // 要调用的工具名称
"arguments": { // 工具参数
"path": "/path/to/file.txt"
}
}
}
服务器执行工具并返回结果：
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [ // 返回内容数组
{
"type": "text", // 内容类型：text、image、resource 等
"text": "文件内容..."
}
],
"isError": false // 是否发生错误
}
}
资源（Resources）访问
资源是 MCP 服务器提供的只读数据，如文件、数据库记录等。客户端可以列出可用资源，然后读取特定资源。
列出可用资源
{
"jsonrpc": "2.0",
"id": 4,
"method": "resources/list"
}
服务器响应：
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"resources": [
{
"uri": "file:///path/to/file.txt",
"name": "文件示例",
"description": "示例文件",
"mimeType": "text/plain"
}
]
}
}
读取资源
{
"jsonrpc": "2.0",
"id": 5,
"method": "resources/read",
"params": {
"uri": "file:///path/to/file.txt"
}
}
服务器返回资源内容：
{
"jsonrpc": "2.0",
"id": 5,
"result": {
"contents": [
{
"uri": "file:///path/to/file.txt",
"mimeType": "text/plain",
"text": "资源内容..."
}
]
}
}
提示（Prompts）获取
提示是预定义的模板，用于生成上下文或指导大模型的输入。
列出可用提示
{
"jsonrpc": "2.0",
"id": 6,
"method": "prompts/list"
}
服务器响应：
{
"jsonrpc": "2.0",
"id": 6,
"result": {
"prompts": [
{
"name": "code_review",
"description": "代码审查提示",
"arguments": [
{
"name": "code",
"description": "要审查的代码",
"required": true
}
]
}
]
}
}
获取提示
{
"jsonrpc": "2.0",
"id": 7,
"method": "prompts/get",
"params": {
"name": "code_review",
"arguments": {
"code": "function example() { return true; }"
}
}
}
服务器返回格式化的提示内容：
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"description": "代码审查提示",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "请审查以下代码：\nfunction example() { return true; }"
}
}
]
}
}
通知机制
除了请求-响应模式，MCP 还支持服务器主动向客户端发送通知，用于实时更新。
资源变更通知
当资源发生变化时，服务器可以发送通知：
{
"jsonrpc": "2.0",
"method": "notifications/resources/changed",
"params": {
"resources": [
{
"uri": "file:///path/to/file.txt"
}
]
}
}
客户端收到通知后，可以重新读取资源以获取最新内容。
错误处理
MCP 使用标准的 JSON-RPC 错误格式：
{
"jsonrpc": "2.0",
"id": 8,
"error": {
"code": -32602,
"message": "Invalid params",
"data": {
"details": "参数 path 是必需的"
}
}
}
常见的错误代码包括：
- -32600：无效请求
- -32601：方法不存在
- -32602：无效参数
- -32603：内部错误
- -32000 到 -32099：服务器定义的错误