MCP服务支持通过部署、导入、API一键转换的方式创建，能为智能体提供标准化工具调用能力，统一封装、调度各类模型与外部服务，降低存量系统智能化改造成本，适用于自研工具上线、存量能力复用等场景。本文介绍如何在AgentKit中创建MCP服务。 ## 背景信息 MCP协议用于简化大语言模型（LLM）与外部工具、API和服务的交互。通过标准化接口，LLM能够调用外部API、运行脚本、访问数据库等，扩展了自身能力边界。MCP的传输层支持多种协议，确保数据高效、安全传输。典型应用场景包括智能助手与代理、企业级知识管理、开发者工具与IDE集成、多模态数据集成等。此外，MCP还提供了交互式调试工具，帮助开发者高效测试和调试相关服务器与客户端。 AgentKit提供MCP服务功能，该功能提供RESTful API至MCP协议的平滑迁移能力，能够快速将现有HTTP应用转换为MCP Server。 ## 前提条件 * 仅支持Swagger和OpenAPI 3.0格式的API。 * （可选）如需访问私有网络 VPC，请确保已开通火山引擎私有网络，已在MCP服务待部署地域创建私有网络、子网。详细操作请参见 [创建私有网络](https://www.volcengine.com/docs/6401/69467)、[创建子网](https://www.volcengine.com/docs/6401/67823)。 * （可选）通过已有的后端服务创建 MCP 服务时，请先完成对应后端服务的创建。 * 函数服务：已创建函数实例，操作详情参见 [函数创建方式选型](https://www.volcengine.com/docs/6662/97175)。 * 容器服务：已在容器服务中创建服务，操作详情参见 [服务](https://www.volcengine.com/docs/6460/100984)。 * 云服务器：已创建云服务器实例，操作详情参见 [购买并使用云服务器实例](https://www.volcengine.com/docs/6396/1133968)。 ## 创建MCP服务 1. 登录[AgentKit控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中选择“网关\>MCP服务”。 3. 单击“创建MCP服务”，在创建页面参照下表完成参数配置。 * **创建方式** 选择创建MCP服务的方式。 * **部署MCP服务**：您可以部署自研或公开的MCP服务并提供对外访问，同时将Local MCP自动转换为Remote MCP。 * **导入MCP服务**：您可以导入已有MCP服务便于智能体统一对接，平台支持固定域名、容器服务、云服务器、函数服务的方式完成导入。 * **HTTP转MCP**：提前准备API文件及后端服务地址后，您可以将存量API一键转换为MCP服务。 * **基本信息** |参数 |说明 | |---|---| |名称 |配置MCP服务的名称。创建后不支持修改。 | |协议支持 |创建方式为**部署MCP服务**或**导入MCP服务**时，需要配置协议支持。当前仅支持**Streamable HTTP**。 | |访问路径 |配置MCP服务的访问路径。 | |API信息 |创建方式为**HTTP转MCP**时，需要配置API信息。当前仅支持上传Swagger和OpenAPI 3.0格式的API。 | * **网络配置** |参数 |说明 | |---|---| |网络访问 |配置MCP服务的网络访问方式，包括：|\ | ||\ | |* 公网访问：默认访问方式。|\ | |* 私网访问：选择同地域中的任意一个VPC和子网，每个可用区支持最多选择一个子网。 | * **认证信息** |参数 |说明 | |---|---| |入站身份认证 |配置MCP服务身份认证方式。入站身份认证是构建服务访问的第一道安全屏障，确保只有经过授权的主体才能调用 MCP 服务，避免非法访问、数据泄露和恶意攻击。支持以下配置方式：|\ | ||\ | |* API Key：输入名称后，将自动为MCP服务创建和绑定API Key，MCP服务创建成功后，可在MCP服务详情页查看。|\ | |* OAuth JWT：使用OAuth授权模式完成访问令牌申请和API调用，提升安全性，同时简化配置。配置前，请确认已[创建用户池](https://www.volcengine.com/docs/86681/1873447?lang=zh#Gzz7rgDs)和[客户端](https://www.volcengine.com/docs/86681/1873447?lang=zh#Gzz7rgDs)。 | * **后端配置** |参数 |说明 | |---|---| |创建方式为**部署MCP服务**时，配置以下参数。 || |配置方式 |支持**JSON配置**和**镜像**。 | |服务配置 |当**配置方式**选择为**JSON配置**时，需要配置服务配置。请参考以下模板编写配置代码。|\ | ||\ | |* **npx**|\ | | ```JSON|\ | | {|\ | | "mcpServers": {|\ | | "sequential-thinking": {|\ | | "command": "npx",|\ | | "args": [|\ | | "-y",|\ | | "@modelcontextprotocol/server-sequential-thinking"|\ | | ]|\ | | }|\ | | }|\ | | }|\ | | ```|\ | | |\ | |* **uvx**|\ | | ```JSON|\ | | {|\ | | "mcpServers": {|\ | | "time": {|\ | | "command": "uvx",|\ | | "args": [|\ | | "mcp-server-time"|\ | | ]|\ | | }|\ | | }|\ | | }|\ | | ```|\ | | |\ | | | |镜像 |当**配置方式**为**镜像**时，下拉选择已上传至镜像仓库的镜像即可。 | |启动命令 |当**配置方式**为**镜像**时，需要配置启动命令。|\ | |启动命令要根据自身代码进行修改，否则服务会拉起失败。 | |环境变量 |当**配置方式**选择为**镜像**时，需要配置环境变量。|\ | |自定义配置的环境变量，在MCP服务代码运行时可以直接读取。实现代码和配置的分离，增强代码的可移植能力。|\ | |支持如下两种环境变量配置方法：|\ | ||\ | |* **使用表单编辑**：通过键值对方式，配置环境变量。|\ | | 单击**添加环境变量**，根据控制台界面提示的变量输入要求，设置**键**和**值**。|\ | |* **使用JSON格式编辑**：通过JSON文件方式配置环境变量。|\ | | JSON文件需满足如下格式：|\ | | ```JSON|\ | | {|\ | | "envKey1": "envValue1",|\ | | "envKey2": "envValue2"|\ | | }|\ | | ```|\ | | |\ | ||\ | | | |日志服务 |开启后，将会提供MCP服务日志。支持在服务详情页的**日志**页签查看，详情参见[查看日志](https://www.volcengine.com/docs/86681/1844827)。 | |出站凭证 |配置MCP服务的出站授权，允许智能体使用该凭据访问下游资源。创建凭证的方式参见[创建凭据](https://www.volcengine.com/docs/86848/2080921)。|\ | ||\ | |* API Key：适用于使用固定密钥进行认证的外部服务。|\ | |* OAuth Client：适用于需要通过OAuth 2.0 流程进行认证的下游服务。 | |创建方式为**导入MCP服务**或**HTTP转MCP**时，配置以下参数。 || |服务类型 |配置MCP服务对接的后端服务类型，包括：|\ | ||\ | |* 函数服务：选择已存在的[函数服务veFaaS](https://www.volcengine.com/docs/6662/98457)。|\ | |* 容器服务：选择容器服务中目标服务所处的容器集群、命名空间，以及服务的名称和端口。支持在容器服务的服务列表页面，查看对应的信息。服务列表页的登录路径参见[管理服务](https://www.volcengine.com/docs/6460/100989)。|\ | |* 云服务器：选择目标云服务器，同时完成对应端口的配置。|\ | |* 固定域名：配置MCP服务使用的协议、域名、端口。 | |出站凭证 |配置MCP服务的出站授权，允许智能体使用该凭据访问下游资源。创建凭证的方式参见[创建凭据](https://www.volcengine.com/docs/86848/2080921)。|\ | ||\ | |* API Key：适用于使用固定密钥进行认证的外部服务。|\ | |* OAuth Client：适用于需要通过OAuth 2.0 流程进行认证的下游服务。 | * 高级配置 |参数 |说明 |示例值 | |---|---|---| |所属项目 |项目是一组资源的集合，您可以将本次创建的MCP服务添加至项目中并按项目维度统一管理，有利于保持资源独立，维护数据安全。有关项目的更多信息请参见[项目管理](https://www.volcengine.com/docs/86681/2075078)。|default |\ | || |\ | |* 默认为default，一个资源只能归属于一个项目。| |\ | |* 选定项目后，创建的MCP服务只能被具有该项目权限的用户使用。创建MCP服务后，您可以按需[更改实例所属项目](https://www.volcengine.com/docs/6649/94336)。| |\ | |* 若无可用项目，您可单击“新建项目”按钮进行创建，创建完成后，返回本页面即可选择新添加的项目。 | | |标签 |标签由一个键\-值对（Key\-Value）组成，用于标识云资源，可以从不同维度（例如用途、所有者或环境等）对云资源进行分类，便于搜索和聚合。|Key1:Value1 |\ | |单击“+ 添加标签” 按钮，选择已有标签或输入新的标签，为MCP服务绑定标签。更多信息，请参见[标签管理](https://www.volcengine.com/docs/86681/2075077)。| |\ | |:::tip| |\ | |单次操作最多可绑定20个标签，单个资源最多可绑定50个标签。| |\ | || |\ | |:::| | 4. 单击“创建”，完成操作。 ## 调试MCP服务 :::tip 仅当**网络访问**选择**公网访问**的MCP服务，支持在线调试功能。 ::: 1. MCP服务创建完成后，在服务列表中选择目标服务，单击服务名称，进入服务详情页面。 2. 选择“调试”页签，根据导航提示验证MCP服务中的工具。 * 域名：MCP服务的公网访问域名。 * API Key或Access Token：MCP服务的入站身份认证。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d9ed51cbd707059fa7da7e948ad7a5f8.png =557x) 若回显 **测试成功**，则表示MCP服务工具连接正常。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_19e29d3f574eab43b0e8c9a1d88f282e.png =554x) ## 获取调用示例和Access Token MCP服务创建完成后，支持通过IDE工具或CLI工具调用，操作步骤如下：单击目标服务名称操作列的“调用示例”，获得该MCP服务的域名、调用示例和生成Access Token的代码示例。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_8f7e50e44d219afee90afca2ede36388.png) * 调用示例 * Gemini CLI调用示例：适用于Gemini CLI等CLI工具。 * Trae调用示例：适用于Trae、Cursor等IDE工具。 * Access token 单击“如何获取Access Token”查看生成Access Token的代码示例。 ## 添加MCP Tools :::tip 仅当**MCP访问方式**选择**HTTP转MCP**时，允许添加MCP Tools。 ::: MCP服务创建完成后，支持基于[Swagger文件](#N1dv6gxA)添加MCP Tools。操作步骤如下： 1. MCP服务创建完成后，在服务列表中选择目标服务，单击服务名称，进入服务详情页面。 2. 选择“MCP Tools”页签，单击“上传API信息”。 3. 选择上传时存在同名工具：“坚持上传，覆盖原工具”或“跳过上传，不覆盖原工具”。 4. 单击或拖拽文件到控制台，上传准备好的Swagger文件。 5. 单击“确定”，完成操作。配置完成后，您可以在MCP Tools页面中查看和管理已上传的文件。 ## 其他操作 |操作 |步骤 | |---|---| |更新标签 |1. 在MCP服务列表中选择目标服务，单击服务名称，进入服务详情页面。|\ | |2. 选择“基本信息”页签，单击“标签”旁的![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b4ebe7d87f46b77eb8bff52c9709ebfd.png =20x) 。|\ | |3. 在“编辑标签”弹框中更新标签。|\ | |4. 单击“确定”，完成操作。 | |更新身份认证 |1. 在MCP服务列表中选择目标服务，单击服务名称，进入服务详情页面。|\ | |2. 选择“基本信息”页签，单击“身份认证”旁的“编辑”。|\ | |3. 在“编辑身份认证”面板中更新访问用户。 | |更新后端服务 |1. 在MCP服务列表中选择目标服务，单击服务名称，进入服务详情页面。|\ | |2. 选择“基本信息”页签，单击“后端服务”旁的“编辑”。|\ | |3. 在“编辑后端服务”面板中更新服务类型。 | |查看MCP服务启动失败日志 |1. 在MCP服务列表中，将鼠标移动到目标智能体运行时状态列的不可用，然后单击“查看日志”按钮。|\ | |2. 在弹出的“MCP服务日志”对话框中，查看MCP服务启动失败原因。|\ | | ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_91ae679fbdbff593af6d645d1ce0deb9.png =441x) |\ | ||\ | |:::tip|\ | |仅当MCP服务状态为**不可用**且**后端服务**为**新建MCP服务**时，支持查看MCP服务启动失败日志。|\ | ||\ | |:::| |删除MCP服务 |在MCP服务列表中，单击目标服务操作列的“删除”，删除服务。|\ | |:::warning|\ | |删除MCP服务后，无法恢复，请谨慎操作，避免因误删除导致Agent运行失败。|\ | ||\ | |:::| ## 常见问题 ### 如何上传正确的Swagger文件 * 使用限制 Swagger文件需要符合以下条件： |类型 |说明 | |---|---| |语法 |* 仅支持Swagger和OpenAPI 3.0格式的 API。|\ | |* 代码中不存在Swagger语法错误。|\ | |* 代码中必须包含Swagger元数据、title和version。 | |请求方法 |仅支持GET、POST、PUT、DELETE、PATCH。 | |请求类型 |支持JSON（application/json）和Form（application/x\-www\-form\-urlencoded）内容类型。 | |请求参数 |* 参数名存在且唯一。|\ | |* 仅支持存在一个请求体（body）。多个formData，会自动合并为一个body。body和formData不能同时出现。|\ | |* in支持path、query、header、formData和body等位置参数。|\ | |* in为path、query、header或formData时，支持boolean、integer、number、string数据类型，不支持array类型。|\ | |* in为body且使用schema时，支持boolean、integer、number、string、array、object数据类型。|\ | |* schema不支持oneOf、anyOf和allOf。|\ | |* schema不支持null数据类型。|\ | |* enum唯一且符合数据类型。|\ | |* array、object、null不支持enum。 | |响应 |仅支持解析200、201和default，且仅解析1个。同时存在时，解析的顺序为200 \> 201 \> default。 | * 代码示例 JSON格式的POST请求示例如下。 * Swagger ```JSON { "swagger": "2.0", "info": { "title": "weather", "version": "1.0.0" }, "paths": { "/weather/{city}": { "get": { "operationId": "weather", "summary": "Check weather status。", "consumes": ["application/json"], "parameters": [ { "name": "city", "description": "City", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "date": { "description": "Date", "type": "string" } } } } ], "responses": { "200": { "description": "Weather status", "schema": { "type": "object", "properties": { "weather": { "description": "Weather", "type": "string" } } } } } } } } } ``` * OpenAPI 3.0 ```JSON { "openapi": "3.0.1", "info": { "title": "weather", "version": "1.0.0" }, "paths": { "/weather/{city}": { "get": { "operationId": "weather", "summary": "check the weather", "parameters": [ { "name": "city", "description": "city", "type": "string", "schema": { "type": "string" }, "in": "path", "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "description": "Date", "type": "string" } } } } } }, "responses": { "200": { "description": "weather", "content": { "application/json": { "schema": { "type": "object", "properties": { "weather": { "description": "weather", "type": "string" } } } } } } } } } } } ```