Skip to main content

Create a custom MCP

Creates and immediately deploys a custom MCP service. Supports STDIO, HTTP, SSE, and OPENAPI.

Endpoint

POST /api/v1/mcp/servers The service is deployed immediately after creation. A successful request returns 201 and a Location header. If deployment fails, the request still returns 201, the status is ACTIVATE_FAILED, and the reason is returned in activate_fail_reason.

Request body

FieldTypeRequiredDescription
server_namestringYesMCP name. Cannot be blank
descriptionstringYesMCP description. Cannot be blank
mcp_typestringYesSTDIO, HTTP, SSE, or OPENAPI
mcp_configobjectYesConfiguration for the selected mcp_type

STDIO

FieldTypeRequiredDescription
commandstringYesnpx or uvx
argsarray<string>YesNon-empty startup arguments. Each item must match [A-Za-z0-9_@./:=,+-]+
envmap<string,string>NoEnvironment variables. Names must match [A-Za-z_][A-Za-z0-9_]*. Values must be strings
fc_deploy_regionstringNoFunction Compute region. Use a region supported by the console
Function Compute must be authorized for the account before using STDIO.

HTTP / SSE

FieldTypeRequiredDescription
urlstringYesPublic HTTP(S) URL. Cannot contain credentials, a # fragment, or backslashes
headersmap<string,string>NoDownstream request headers. Names must be valid HTTP headers. Values cannot contain CR/LF
If the URL has no path, HTTP uses /mcp and SSE uses /sse.

OPENAPI

FieldTypeRequiredDescription
api_hoststringYesPublic HTTP(S) URL. Cannot contain a query string, fragment, credentials, or backslashes
headersmap<string,string>NoDownstream request headers. Names must be valid HTTP headers. Values cannot be blank or contain CR/LF
api_listarray<Api>YesNon-empty API list
Api
FieldTypeRequiredDescription
namestringYesTool name. Cannot be blank and must be unique in api_list
descriptionstringYesTool description. Cannot be blank
pathstringYesRelative path starting with /. Supports {param} placeholders
methodstringYesGET or POST
content_typestringNoapplication/json (default) or application/x-www-form-urlencoded
input_paramsarray<InputParam>NoInput parameter definitions. Treated as an empty array when omitted
InputParam
FieldTypeRequiredDescription
namestringYesParameter name. Cannot be blank and must be unique at the same level
descriptionstringYesParameter description. Cannot be blank
locationstringRequired at top levelQuery, Path, Header, or Body. Optional for child properties
typestringYesString, Number, Integer, Boolean, Object, Array<String>, Array<Number>, Array<Integer>, Array<Boolean>, or Array<Object>
requiredbooleanNoWhether the parameter is required. Default false
propertiesarray<InputParam>Depends on typeRequired for Object or Array<Object> and cannot be empty
GET cannot define a top-level Body parameter. Top-level object and array parameters can only be placed in Body. All enumerated values are case-sensitive.

Response

Returns a CreateResponse. Unassigned fields are omitted.
FieldTypeDescription
mcp_codestringMCP code
server_namestringMCP name
server_statusstringDeployment status
server_status_textstringStatus text
activate_fail_reasonstringDeployment failure reason. Returned only when deployment fails

Examples

Create an HTTP MCP

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": "Weather query 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"
}
Response headers:
Location: /api/v1/mcp/servers/mcp-a1b2c3d4e5f6g7h8
X-Request-Id: 6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11

Create an STDIO MCP

{
  "server_name": "amap-maps",
  "description": "Amap Maps 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"
  }
}

Create an OPENAPI MCP

{
  "server_name": "order-api",
  "description": "Order query API",
  "mcp_type": "OPENAPI",
  "mcp_config": {
    "api_host": "https://api.example.com",
    "headers": {
      "X-Api-Key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "api_list": [
      {
        "name": "getOrder",
        "description": "Queries an order by order ID",
        "path": "/orders/{orderId}",
        "method": "GET",
        "input_params": [
          {
            "name": "orderId",
            "description": "Order ID",
            "location": "Path",
            "type": "String",
            "required": true
          }
        ]
      }
    ]
  }
}

Errors

HTTP statuserror_codeDescription
400InvalidParameterThe request body is missing, a field type is invalid, or a value is invalid
403AccessDeniedFunction Compute is not authorized, or the target address is not allowed
500InternalErrorInternal service error
A private target address returns 403. An invalid or unresolvable address returns 400.