Skip to main content

Recommend tools

Recommends MCP tools based on a natural-language request and returns tool names, descriptions, and input schemas.

Endpoint

GET /api/v1/mcp/servers/tools/recommend

Request parameters

ParameterTypeRequiredDefaultDescription
querystringYes-Natural-language request. Cannot be blank
topNintNo10Suggested number of results. Values less than or equal to 0 use the default 10
topN is a target count. The actual number of results is not guaranteed to equal it.

Response

data is an array of tools. Each item contains four fields:
FieldTypeDescription
mcp_codestringMCP code. Can be used as the mcpCode path parameter
tool_namestringTool name. Can be used as the tool_name when calling a tool
tool_descriptionstring / nullTool description
tool_input_schemaobject / nullTool input schema. The structure is the same as inputSchema in List tools

Example

curl -G "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/mcp/servers/tools/recommend" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data-urlencode "query=Query an order by order ID" \
  --data-urlencode "topN=5"
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": [
    {
      "mcp_code": "mcp-a1b2c3d4e5f6g7h8",
      "tool_name": "getOrder",
      "tool_description": "Queries an order by order ID",
      "tool_input_schema": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "Order ID"
          }
        },
        "required": ["orderId"],
        "additionalProperties": false
      }
    }
  ],
  "request_id": "6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11"
}

Errors

HTTP statuserror_codeDescription
400InvalidParameterquery is missing or blank, or an unsupported query parameter is provided
502McpUpstreamErrorThe downstream MCP operation failed
A recommendation does not mean the service is activated. Calling a One Key MCP tool may activate the service automatically and incur charges.