# 连接 MCP 服务并导入工具

MCP 连接保存远程服务地址、传输方式和凭据引用；探测接口读取该服务公布的工具；批量导入接口把选中的远程工具注册为工作区工具。智能体运行时使用的是导入后的工具，不是直接“运行连接”。

## 开始之前

请准备：

- Product API Base URL、个人访问令牌和工作区 ID；
- 可从当前环境访问的 MCP 服务地址；
- MCP 服务使用的传输方式和认证方式；
- 允许列出工具和执行目标工具的最小必要凭据。

只连接受信任的 MCP 服务。探测前确认服务地址使用受支持的安全协议，且不会通过重定向把凭据发送到其他主机。

## 1. 创建连接

下面创建一个使用 HTTP Streaming、无需认证的 MCP 连接。需要认证时，把认证方式和凭据放入对应字段，不要把密钥拼到 URL 中。

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/connections" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-mcp",
    "description": "Tools provided by the support service.",
    "status": "active",
    "kind": "mcp_server",
    "endpoint_uri": "<MCP_HTTPS_ENDPOINT>",
    "auth_type": "none",
    "visibility": "workspace",
    "config": {
      "transport": "http-streaming"
    }
  }'
```

保存响应中的 `data.id`。凭据由服务端保存为引用；后续读取连接时不应期待返回明文凭据。

## 2. 探测 MCP 服务

使用连接 ID 探测服务：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/connections/actions/probe-mcp" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<CONNECTION_ID>"
  }'
```

成功响应中的 `tool_count` 和 `tools` 反映本次探测发现的能力。检查每个工具的远程名称、描述、`inputSchema` 和 `outputSchema`。探测成功不会自动导入工具，也不能证明每个工具调用都一定成功。

## 3. 选择并导入工具

只导入业务确实需要的工具。下面把探测到的 `get_ticket` 注册为工作区工具：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/connections/actions/batch-create-mcp-tools" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<CONNECTION_ID>",
    "visibility": "workspace",
    "items": [
      {
        "tool_name": "get_ticket",
        "name": "get-ticket",
        "description": "Read one support ticket by ID.",
        "input_schema": {
          "type": "object",
          "properties": {
            "ticket_id": {"type": "string"}
          },
          "required": ["ticket_id"]
        },
        "category": "support",
        "tags": ["ticket", "read"]
      }
    ]
  }'
```

逐项检查响应中的 `status`：

- `created`：已创建工作区工具，保存返回的工具 ID；
- `existing`：已存在对应工具，使用返回的工具资源继续检查；
- `failed`：本项导入失败，读取该项的错误，不要假定其他项也失败。

## 4. 验证导入结果

读取导入后的工具详情，确认来源指向正确连接，Schema 与探测结果一致，并检查 `bindable`、凭据和运行时支持。随后把工具绑定到技能或智能体，使用只读或低风险输入进行验证。

远程 MCP 服务的工具定义发生变化时，重新探测并对比 Schema，再决定是否更新工作区工具。不要在未评估兼容性时覆盖正在使用的输入输出契约。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 无法建立连接 | 服务地址、网络、TLS、传输方式 | 从当前运行环境确认地址可达，再检查服务日志。 |
| 探测返回认证错误 | `auth_type`、凭据范围和 Header 配置 | 更新连接凭据后重新探测。 |
| 探测成功但没有工具 | 远程服务是否公布工具、当前身份权限 | 使用同一身份在 MCP 服务端检查工具列表。 |
| 导入后不可绑定 | 工具详情中的可绑定原因和运行时 | 补齐配置，或换用受支持的工具和运行时。 |

## 下一步

- [发现和管理工具](../tools/manage-tools.md)
- [创建和管理技能](../skills/manage-skills.md)
- [查询 MCP 连接 API](api-reference.md)