Skip to main content

创建自定义 MCP

创建自定义 MCP 服务并立即部署,支持 STDIO、HTTP、SSE 和 OPENAPI 四种类型。

接口

POST /api/v1/mcp/servers 创建成功后立即触发部署,返回 201 和 Location 响应头。部署失败仍返回 201,服务状态为 ACTIVATE_FAILED,失败原因放在 activate_fail_reason。

请求体

字段类型必填说明
server_namestring是MCP 名称,不能为空白
descriptionstring是MCP 描述,不能为空白
mcp_typestring是STDIO、HTTP、SSE 或 OPENAPI
mcp_configobject是按 mcp_type 传入对应配置

STDIO

字段类型必填说明
commandstring是npx 或 uvx
argsarray<string>是启动参数,不能为空;每项匹配 [A-Za-z0-9_@./:=,+-]+
envmap<string,string>否环境变量,名称匹配 [A-Za-z_][A-Za-z0-9_]*,值必须为字符串
fc_deploy_regionstring否函数计算部署地域,需使用控制台支持的地域
使用 STDIO 前,需要为账号授权函数计算 FC。

HTTP / SSE

字段类型必填说明
urlstring是公网 HTTP(S) 地址,不能包含凭据、# 片段或反斜杠
headersmap<string,string>否下游请求头,名称需为合法 HTTP Header,值不能包含 CR/LF
不包含路径时,HTTP 默认使用 /mcp,SSE 默认使用 /sse。

OPENAPI

字段类型必填说明
api_hoststring是公网 HTTP(S) 地址,不能包含查询串、片段、凭据或反斜杠
headersmap<string,string>否下游请求头,名称需为合法 HTTP Header,值不能为空白或包含 CR/LF
api_listarray<Api>是API 列表,不能为空
Api
字段类型必填说明
namestring是工具名,不能为空白,同一 api_list 内不能重复
descriptionstring是工具描述,不能为空白
pathstring是以 / 开头的相对路径,支持 {param} 占位符
methodstring是GET 或 POST
content_typestring否application/json(默认)或 application/x-www-form-urlencoded
input_paramsarray<InputParam>否入参定义,省略时按空数组处理
InputParam
字段类型必填说明
namestring是参数名,不能为空白,同级不能重复
descriptionstring是参数描述,不能为空白
locationstring顶层必填Query、Path、Header 或 Body;子属性可省略
typestring是String、Number、Integer、Boolean、Object、Array<String>、Array<Number>、Array<Integer>、Array<Boolean> 或 Array<Object>
requiredboolean否是否必填,默认 false
propertiesarray<InputParam>视类型Object 或 Array<Object> 必须提供非空子属性
GET 不能定义顶层 Body 参数;顶层对象和数组参数只能放在 Body。全部枚举值区分大小写。

响应

返回 CreateResponse,未赋值的字段不输出。
字段类型说明
mcp_codestringMCP 编码
server_namestringMCP 名称
server_statusstring部署结果状态
server_status_textstring状态文案
activate_fail_reasonstring部署失败原因,仅部署失败时返回

示例

创建 HTTP 类型

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/mcp/servers" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "weather-mcp",
    "description": "天气查询 MCP",
    "mcp_type": "HTTP",
    "mcp_config": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }'
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {
    "mcp_code": "mcp-a1b2c3d4e5f6g7h8",
    "server_name": "weather-mcp",
    "server_status": "ACTIVATED",
    "server_status_text": "已启用"
  },
  "request_id": "6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11"
}
响应头:
Location: /api/v1/mcp/servers/mcp-a1b2c3d4e5f6g7h8
X-Request-Id: 6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11

创建 STDIO 类型

{
  "server_name": "amap-maps",
  "description": "高德地图 MCP",
  "mcp_type": "STDIO",
  "mcp_config": {
    "command": "npx",
    "args": ["-y", "@amap/amap-maps-mcp-server"],
    "env": {
      "AMAP_MAPS_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "fc_deploy_region": "cn-hangzhou"
  }
}

创建 OPENAPI 类型

{
  "server_name": "order-api",
  "description": "订单查询 API",
  "mcp_type": "OPENAPI",
  "mcp_config": {
    "api_host": "https://api.example.com",
    "headers": {
      "X-Api-Key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "api_list": [
      {
        "name": "getOrder",
        "description": "根据订单号查询订单",
        "path": "/orders/{orderId}",
        "method": "GET",
        "input_params": [
          {
            "name": "orderId",
            "description": "订单号",
            "location": "Path",
            "type": "String",
            "required": true
          }
        ]
      }
    ]
  }
}

错误

HTTP 状态码error_code说明
400InvalidParameter请求体缺失、字段类型错误或字段取值不合法
403AccessDenied函数计算未授权,或目标地址不允许访问
500InternalError服务内部错误
目标地址为内网地址时返回 403,地址格式错误或无法解析时返回 400。