创建智能体连接

保存智能体可引用的连接配置。创建 MCP 连接时，符合复用条件的现有连接会被更新，返回的连接标识不一定是新建标识。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/connections

调用前准备

准备可访问目标工作区的个人访问令牌和目标工作区 ID。

请求体

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/connections" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "MCP 服务",
    "kind": "mcp_server",
    "endpoint_uri": "https://mcp.example.com"
  }'

参数说明

字段	类型	是否必填	说明
id	string	否	自定义连接 ID。省略或空字符串时由服务生成。
name	string	是	连接名称。
endpoint_uri	string	是	连接服务地址。
description	string	否	连接说明。
status	string	否	连接状态。
kind	string	否	连接类型。
auth_type	string	否	认证类型。
credential_ref	string	否	已保存凭据的引用。
capabilities	string（字符串数组）	否	连接能力列表。
owner_user_id	string	否	连接所有者用户 ID。
visibility	string	否	可见范围。
config	object	否	连接配置。
labels	object	否	标签。
annotations	object	否	注释。
metadata	object	否	扩展元数据。
credential	object	否	凭据，可包含 bearer_token、api_key、basic_username、basic_password 或 custom_headers。
credential.bearer_token	string	否	Bearer Token。
credential.api_key	string	否	API Key。
credential.basic_username	string	否	Basic 认证用户名。
credential.basic_password	string	否	Basic 认证密码。
credential.custom_headers	object	否	自定义请求头。

只有 MCP 连接接受 credential 对象。auth_type 为 bearer_token 时填写 credential.bearer_token。为 api_key 时填写 credential.api_key。为 basic 时同时填写用户名和密码。为 custom_headers 时提交字符串请求头映射。

结构化凭据与 credential_ref 不能同时提交。none 不接受任何凭据。当前未配置 OAuth 流程，service_account 和 client_certificate 也不能通过此处的结构化凭据创建。响应只返回保存后的引用，不返回明文。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "id": "connection_01",
    "workspace_id": "workspace_example",
    "name": "MCP 服务",
    "status": "draft",
    "kind": "mcp_server",
    "endpoint_uri": "https://mcp.example.com",
    "auth_type": "none",
    "visibility": "private",
    "version": 1,
    "created_at": "2026-10-14T00:00:00Z",
    "updated_at": "2026-10-14T00:00:00Z",
    "config": {
      "transport": "http-streaming"
    }
  }
}

字段说明

字段	类型	说明
code	integer	请求处理成功时为 0。
data	object	响应数据。
data.id	string	已保存的连接 ID。可能是复用的现有连接。
data.workspace_id	string	所属工作区 ID。
data.name	string	名称。
data.description	string	说明。未设置时可省略。
data.status	string	当前状态。取值：draft、active、disabled、archived。
data.kind	string	连接类型。取值：model_api、huggingface、mcp_server、http_api、external_drive、object_storage、database、webhook、channel。
data.endpoint_uri	string	服务端点地址。
data.auth_type	string	认证方式。取值：none、api_key、bearer_token、oauth2、basic、custom_headers、service_account、client_certificate。
data.credential_ref	string	已保存凭据的引用，不是明文密钥。未设置时可省略。
data.capabilities	string（字符串数组）	可用能力列表。未设置时可省略。
data.owner_user_id	string	所属用户标识。未设置时可省略。
data.visibility	string	可见范围。取值：private、workspace。
data.config	object	非敏感配置，字段随连接或通道类型变化。未设置时可省略。
data.last_test_status	string	最近测试状态，取 succeeded 或 failed。未设置时可省略。取值：succeeded、failed。
data.last_tested_at	string	最近测试时间，采用 RFC 3339 格式。未设置时可省略。
data.last_test_error	string	最近测试的错误说明。未设置时可省略。
data.version	integer	当前版本号。
data.labels	object	标签键值对。未设置时可省略。
data.annotations	object	扩展注解。未设置时可省略。
data.metadata	object	扩展元数据。未设置时可省略。
data.created_by	string	创建者标识。未设置时可省略。
data.updated_by	string	最近更新者标识。未设置时可省略。
data.created_at	string	创建时间，采用 RFC 3339 格式。
data.updated_at	string	最近更新时间，采用 RFC 3339 格式。

错误响应

响应示例

{
  "code": 2,
  "message": "invalid connection metadata"
}

字段说明

字段	类型	说明
code	integer	错误代码。
message	string	面向调用者的错误信息。

最后更新于 2026 年 10 月 19 日