# 通过JSON导入MCP服务

`POST` `/api/agent/finx/importMcpService`

支持标准MCP JSON格式导入服务（type支持sse、streamable-http），每次仅支持导入一个服务，mcpServers下只能有一个entry。注意：mcpServers字段必须是JSON对象而非字符串，且不要重复嵌套mcpServers层级，直接传标准MCP JSON中 mcpServers 键对应的值即可。完整请求体示例：{"agentId":123,"mcpServers":{"context7-mcp":{"type":"sse","url":"https://mcp.example.com/sse"}}}。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 是 | 智能体ID，服务导入后归属该智能体 |
| mcpServers | object | 是 | MCP服务配置（JSON对象，非字符串）。key为服务名称，value为该服务的配置对象，且只能包含一个服务。

**常见错误提示：**
- 该字段必须传JSON对象，不要将其序列化为字符串后传入
- 不要再包裹一层 mcpServers，请直接传标准MCP JSON中 mcpServers 键对应的值

**服务配置项：**
- url：MCP服务器地址（必填）
- type：传输协议类型（选填），可选值：sse、streamable-http；不传时默认按 streamable-http 尝试，且因协议不匹配连接失败时会自动换另一种协议重试；显式传入时不做自动重试
- headers：自定义请求头（JSON对象，选填）

**导入时的行为**
- 后端会先连接该 MCP Server 拉取工具列表，连不通直接报错、服务不会被创建
- key 不符合服务标识名规则（字母/下划线开头，仅含字母、数字、下划线、连字符）时，系统会自动生成合规的服务标识名与中文展示名
- 服务描述由系统根据工具列表自动生成

**headers 会被自动识别为鉴权配置**
- 不传或为空对象：识别为无需鉴权（NONE）
- `Authorization: Bearer <令牌>`：识别为 BEARER，令牌自动去掉 `Bearer ` 前缀后存为凭证
- `Authorization: Basic <凭证>`：识别为 BASIC
- 其他任意请求头：识别为 CUSTOM，所有 header 原样存为自定义请求头
- 导入后如需调整鉴权方式（例如改为「用户各自提供凭证」），请再调用 updateMcpService 编辑 |
| autoGenerateDescription | boolean | 否 | 保留字段，不传时默认 false。导入场景下服务描述始终由系统根据工具列表自动生成，本开关不影响结果 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | integer | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |