# MCP 连接 API 参考

本页汇总 MCP 连接、探测和工具导入接口。MCP 工具导入后通过[工具 API](../tools/api-reference.md)管理。

## 接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `GET` | `/workspaces/{workspace_id}/connections` | 列出连接。 |
| `POST` | `/workspaces/{workspace_id}/connections` | 创建连接。 |
| `GET` | `/workspaces/{workspace_id}/connections/{connection_id}` | 读取连接详情。 |
| `PATCH` | `/workspaces/{workspace_id}/connections/{connection_id}` | 部分更新连接。 |
| `POST` | `/workspaces/{workspace_id}/connections/actions/probe-mcp` | 探测 MCP 服务和工具。 |
| `POST` | `/workspaces/{workspace_id}/connections/actions/batch-create-mcp-tools` | 批量导入 MCP 工具。 |

连接列表支持 `query`、`status`、`kind`、`auth_type`、`visibility`、`owner_user_id`、`limit` 和 `offset`。

## 连接字段

| 字段 | 类型 | 必需 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `name` | string | 创建时是 | — | 连接名称。 |
| `description` | string | 否 | — | 连接用途。 |
| `status` | string | 否 | — | 连接状态。 |
| `kind` | string | 否 | — | MCP 连接使用 `mcp_server`。 |
| `endpoint_uri` | string | 创建时是 | — | MCP 服务地址。 |
| `auth_type` | string | 否 | — | 认证方式。 |
| `credential_ref` | string | 否 | — | 已保存的凭据引用。 |
| `credential` | object | 条件必需 | — | 创建或更新时提交的 Bearer Token、API Key、Basic Auth 或自定义 Header。 |
| `visibility` | string | 否 | — | 连接可见范围。 |
| `config` | object | 否 | — | 传输方式等连接配置。 |

连接响应还包含 `last_test_status`、`last_tested_at`、`last_test_error` 和 `version`。读取响应不会返回明文凭据。

## 探测请求

探测请求可以使用现有 `connection_id`，也可以临时提交 `endpoint_uri`、`auth_type`、`api_key_header`、`credential` 和 `transport`。`transport` 支持 `sse` 或 `http-streaming`。

探测响应包含：

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `tool_count` | integer | 成功时返回 | 本次发现的工具数量。 |
| `tools` | array | 成功时返回 | 工具名称、标题、描述及输入输出 Schema。 |
| `protocol_version` | string | 服务提供时返回 | 本次探测协商的协议版本。 |

## 批量导入请求

请求可引用现有 `connection_id`，或同时提供新连接所需的名称、地址、传输方式、认证和凭据。`items` 中每项包含远程 `tool_name`、工作区工具 `name`，以及可选描述、输入输出 Schema、标签和分类。

响应的 `connection_status` 为 `created` 或 `existing`。每个导入项独立返回 `created`、`existing` 或 `failed`；失败项还会返回错误信息，因此客户端应逐项处理。

## 安全和限制

- 不要把 Bearer Token、API Key 或 Basic Auth 密码写入 URL、日志或工具描述。
- 探测只发现服务声明的工具，不验证所有业务调用路径。
- 导入会创建工作区工具；后续运行权限仍受工具凭据、策略和远程服务限制。
- 更新服务地址或认证后，应重新探测并检查已导入工具的兼容性。

## 任务指南

- [连接 MCP 服务并导入工具](connect-import-tools.md)
- [发现和管理工具](../tools/manage-tools.md)