# 导入MCP服务（流式）

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

与 importMcpService 功能完全相同，仅响应形式不同：以 SSE 流式推送导入进度，包含 VALIDATING / GENERATING_NAME / CONNECTING / GENERATING_DESCRIPTION / PERSISTING / COMPLETED / FAILED 事件。

**请求体与 importMcpService 完全一致**：mcpServers 为 JSON 对象（非字符串）且只能包含一个 entry，字段清单与 headers 到鉴权类型的映射规则请参考 importMcpService 的参数说明。

身份说明：当您通过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。导入场景下服务描述始终由系统根据工具列表自动生成，本开关不影响结果 |

## 响应

### 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处理 |