构建并提供 MCP (模型上下文协议) 服务器

从零构建MCP服务器：把HTTP API变成AI Agent的工具

在AI开发圈子里，重复造轮子是个老问题。每换一个Agent框架，就要为同一个API写一套新的适配代码。MCP（模型上下文协议）的出现改变了这种局面：它给工具集成定义了一个稳定的协议边界。你只需要实现一次服务器，任何兼容MCP的客户端都能直接使用。

本文用一个真实场景——问题追踪系统的集成——带你从零搭建并测试一个MCP服务器。整个过程使用TypeScript和Node.js，不依赖特定的厂商SDK。最终，你的Agent可以通过自然语言查询未解决问题，而模型本身不需要知道HTTP细节。

为什么需要MCP服务器

假设你有一个问题追踪API，比如GET /v1/issues?project=OPS&status=open&limit=10。如果没有MCP，你想让LLM调用它，就得为每个Agent框架写单独的适配器：LangChain写一个工具，AutoGPT再写一个，以后换个框架又得重写。

MCP把这一切标准化。你只需构建一个MCP服务器，将API封装成一个工具，比如search_open_issues。服务器的职责是校验输入、调用API、规范化响应，返回模型可以直接理解的紧凑结果。之后，任何支持MCP的Agent主机都能连接这个服务器，而无需改动业务逻辑。

这就像在闲鱼或猪八戒网上接单：你只需要提供一个标准服务入口，客户（Agent框架）通过统一协议来调用你，不需要关心你的具体实现。

架构与协议边界

整个链路分为三层：

• API客户端：负责认证、超时处理、HTTP状态码判断和响应规范化。
• MCP服务器：负责工具发现、输入校验、工具描述和协议格式的结果输出。
• Agent主机：负责模型提示词、工具调用审批、对话状态和停止条件。

这种分离意味着，未来你从某个Agent框架切换到另一个，只要新框架支持MCP，你的问题追踪适配器完全不用改。

准备项目

用TypeScript启动一个Node.js项目，安装必要的依赖。建议使用@modelcontextprotocol/sdk作为MCP协议实现，用dotenv管理环境变量，用tsx或ts-node运行TypeScript代码。

环境变量中设置ISSUE_TRACKER_API_URL和ISSUE_TRACKER_TOKEN，不要将凭据硬编码到源码里。这样账号信息安全，也方便在不同环境间切换。

构建HTTP API客户端

这一层是纯粹的业务代码，与MCP无关。创建一个http-client.ts文件，封装对上游API的请求。核心功能包括：

• 拼接请求URL，处理查询参数。
• 发送带Bearer Token的HTTPS请求。
• 处理非200响应，抛出可读的错误信息。
• 将响应JSON规范化为统一的Issue[]接口。

这里的关键是保持客户端的纯粹性。你可以在测试中单独验证它，而无需启动MCP服务器。

实现MCP服务器

MCP服务器的主要工作是定义工具。使用SDK提供的Server类和McpServer接口，注册search_open_issues工具。

工具定义包含：

• 输入模式：使用JSON Schema描述参数，比如projectKey是必填字符串，limit是可选数字。
• 处理函数：校验参数后调用HTTP客户端，将结果转换为MCP的CallToolResult结构。
• 错误处理：捕获异常并返回错误消息，让Agent知道问题所在。

可选地，还可以实现一个getProjectStatus工具，但本文聚焦一个工具，足够演示完整流程。

测试服务器：不经过模型

不要急着连接LLM。先用一个简单的MCP客户端测试服务器是否能正常工作。在测试文件中，通过stdio与服务器建立会话，调用listTools确认工具存在，然后调用callTool传入参数，断言返回的结果。

这种确定性测试是必要的。它能在不消耗token的情况下验证整个链路，包括输入校验、API调用和响应格式化。你甚至可以伪造一个本地HTTP服务来模拟上游API，实现完全自动化测试。

连接到LLM Agent

当服务器通过测试后，就可以接入Agent。一个典型的Agent循环如下：

• 用户提问："OPS项目有多少未解决的问题？"
• Agent主机加载系统提示词，包含可用的工具列表。
• 模型决定调用search_open_issues，生成一个工具调用请求。
• MCP客户端将该请求转发给服务器，服务器执行HTTP调用。
• 结果返回给模型，模型总结成自然语言回复用户。

你可以在Node.js中使用openai或anthropicSDK，配合MCP客户端库实现。关键点：模型不直接接触HTTP，只看到工具名称、描述和返回的数据，这大大降低了出错的概率。

验证完整路径

建议构建一个端到端测试脚本，模拟用户提问，断言最终回复中包含预期的问题数量。用nock或msw拦截HTTP请求，让测试稳定且不依赖外部系统。

同时，检查服务器是否正确处理了空结果、超大响应和部分失败。这些边界情况决定了你的工具在真实场景中的可靠程度。

失败场景与加固

生产环境中的MCP服务器不能只处理理想路径。你需要考虑：

• 上游API超时：设置合理的超时时间，例如10秒，超时后返回明确错误。
• 认证失败：捕获401/403，提示用户重新配置token。
• 输入不合法：如果缺少projectKey，返回参数校验错误，而不是用默认值默默运行。
• 协议兼容：确保你使用的SDK版本与客户端匹配，避免消息格式不一致。

加固思路是：暴露给模型的信息必须简洁且有效。不要返回原始HTTP响应，而是提取关键字段，如id、title、status，让模型能够快速理解。

局限性与未来方向

本文构建的MCP服务器只是一个起点。它处理了一个简单工具的调用，但真实场景中通常有多个工具、复杂认证和分页数据。下一步可以考虑：

• 将工具扩展为多个，并处理好工具之间的依赖。
• 支持OAuth2动态令牌，而不是静态Bearer Token。
• 将服务器发布到npm或Docker Hub，方便其他开发者通过MCP市场安装。
• 在服务器中增加遥测和日志，方便观测Agent调用行为。

MCP的价值在于标准化。当你把API集成做成MCP服务器，它就能被所有支持MCP的Agent复用。这就像在淘宝服务市场发布一个标准API接口，买家只需按协议接入，不用关心你的实现语言和部署环境。

如果你正在将现有项目接入AI Agent，试着为你的API写一个MCP层。用TypeScript快速上手，用测试确保稳定，然后连接任意LLM。你会发现，工具集成不再是每个框架都要重写一次的重复劳动。