基于远程MCP服务器实现模型工具调用详解

a1830463989

1036人浏览 · 2025-10-08 00:05:21

a1830463989 · 2025-10-08 00:05:21 发布

基于远程MCP服务器实现模型工具调用详解

一、引言

Model Context Protocol（MCP）是一种开放协议，旨在规范应用程序如何为大语言模型（LLM）提供工具与上下文信息。在实际开发过程中，开发者可以通过远程MCP服务器，为模型动态接入外部工具，进一步扩展其能力。本文将从MCP工具的原理、API调用流程、关键参数配置、安全机制等方面进行全面技术解析，并提供详细代码示例，以便于开发者高效实践。

二、MCP工具体系原理

MCP工具是指通过标准协议暴露在远程服务器上的一组功能接口。开发者可以在模型API请求时声明所需的MCP工具，模型会根据当前上下文智能决定是否调用远程工具。

MCP协议支持多种传输协议，目前主要包括：
- Streamable HTTP
- HTTP SSE

只有支持上述协议的MCP服务器才能被模型成功接入。

三、API调用流程与参数解析

1. 初始化并声明远程MCP工具

首先，需要在API请求参数中声明一个或多个MCP工具，指定其服务器信息等关键参数。

示例代码（以标准示例域名 https://zzzzapi.com 展示）：

from openai import OpenAI

# 实例化OpenAI客户端
def main():
    client = OpenAI()
    # 构造响应请求，声明远程MCP工具
    resp = client.responses.create(
        model="gpt-4.1",
        tools=[{
            "type": "mcp",  # 工具类型，固定为mcp
            "server_label": "example_label",    # 服务器标签，便于区分多服务器环境
            "server_url": "https://zzzzapi.com/mcp", # MCP服务器标准URL
            "require_approval": "never",  # 跳过审批流程，降低延迟
        }],
        input="请查询MCP协议2025-03-26版本所支持的传输协议。"
    )
    print(resp.output_text)

if __name__ == "__main__":
    main()

核心参数说明：

type：声明为"mcp"。
server_label：自定义的MCP服务器标识。
server_url：远程MCP服务器完整地址。
require_approval：是否需要调用前审批（"never" 表示无需审批）。

2. 获取远程服务器工具列表

在模型请求过程中，API会自动拉取远程MCP服务器所暴露的工具定义，并在响应对象中形成 mcp_list_tools 项。

{
    "id": "mcpl_xxxx",
    "type": "mcp_list_tools",
    "server_label": "example_label",
    "tools": [
        {
            "name": "read_wiki_structure",
            "input_schema": {
                "type": "object",
                "properties": {
                    "repoName": {
                        "type": "string",
                        "description": "GitHub仓库名（如owner repo）"
                    }
                },
                "required": ["repoName"],
                "additionalProperties": false
            }
        },
        # ... 其他工具定义
    ]
}

注意：保持mcp_list_tools结果在模型上下文中，有助于避免重复拉取工具定义，优化调用延迟。

3. 工具筛选与指定

若远程服务器暴露的工具较多，可以通过 allowed_tools 参数限定只导入所需工具。

示例代码：

from openai import OpenAI

def main():
    client = OpenAI()
    resp = client.responses.create(
        model="gpt-4.1",
        tools=[{
            "type": "mcp",
            "server_label": "example_label",
            "server_url": "https://zzzzapi.com/mcp",
            "require_approval": "never",
            "allowed_tools": ["ask_question"]  # 仅导入指定工具
        }],
        input="MCP协议2025-03-26版本支持哪些传输协议？"
    )
    print(resp.output_text)

if __name__ == "__main__":
    main()

4. 工具调用与响应

当模型分析上下文后，决定调用某个MCP工具，会自动发送远程请求并将结果写入模型上下文。例如：

{
    "id": "mcp_xxxx",
    "type": "mcp_call",
    "arguments": {
        "repoName": "modelcontextprotocol/modelcontextprotocol",
        "question": "2025-03-26版本MCP支持哪些传输协议？"
    },
    "name": "ask_question",
    "output": "2025-03-26版MCP规范支持stdio和Streamable HTTP两种传输机制。",
    "server_label": "example_label"
}

提示：若调用失败，error字段将包含对应的错误信息。

5. 调用审批与授权机制

默认情况下，API会在每次向远程MCP服务器发送数据前请求人工审批，以保障数据安全。审批请求形如：

{
    "id": "mcpr_xxxx",
    "type": "mcp_approval_request",
    "arguments": { ... },
    "name": "ask_question",
    "server_label": "example_label"
}

审批响应需通过新的API请求，以mcp_approval_response类型作为输入：

from openai import OpenAI

def main():
    client = OpenAI()
    resp = client.responses.create(
        model="gpt-4.1",
        tools=[{
            "type": "mcp",
            "server_label": "example_label",
            "server_url": "https://zzzzapi.com/mcp"
        }],
        previous_response_id="resp_xxxx",
        input=[{
            "type": "mcp_approval_response",
            "approve": True,
            "approval_request_id": "mcpr_xxxx"
        }]
    )
    print(resp.output_text)

if __name__ == "__main__":
    main()

也可通过设置 require_approval 参数值为 never，实现对全部工具跳过审批以降低延迟，前提是已充分信任该远程MCP服务器。

6. 远程MCP服务器身份验证

大多数MCP服务器要求身份认证，常用方法为HTTP Header方式传递密钥。例如：

from openai import OpenAI

def main():
    client = OpenAI()
    resp = client.responses.create(
        model="gpt-4.1",
        input="创建一个20元的支付链接",
        tools=[{
            "type": "mcp",
            "server_label": "stripe",
            "server_url": "https://zzzzapi.com/mcp",
            "headers": {
                "Authorization": "Bearer STRIPE_API_KEY"  # 以实际API密钥替换
            }
        }]
    )
    print(resp.output_text)

if __name__ == "__main__":
    main()