Skip to main content

Call a tool

Calls a specified tool in an MCP service and passes the tool parameters.

Endpoint

POST /api/v1/mcp/servers/{mcpCode}/tools/call

Request parameters

ParameterTypeRequiredDescription
mcpCodestringYesMCP code
Request body:
FieldTypeRequiredDescription
tool_namestringYesTool name. Use a name returned by List tools
tool_paramsobjectNoTool parameters. Keys and values follow the tool schema. Treated as an empty object when omitted
For a tool without parameters, still send {"tool_name":"tool_name"}. The request body cannot be omitted.

Response

FieldTypeDescription
isErrorboolean / nullWhether the tool failed
contentarray<Content> / nullTool output
content[].typestring / nullContent type, such as text
content[].textstring / nullText content

Example

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/mcp/servers/mcp-a1b2c3d4e5f6g7h8/tools/call" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "get_weather",
    "tool_params": {
      "city": "Hangzhou"
    }
  }'
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "Hangzhou is sunny today, 18-26°C"
      }
    ]
  },
  "request_id": "6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11"
}

Errors

HTTP statuserror_codeDescription
400InvalidParametertool_name is missing, or tool_params is not a JSON object
400-The MCP service call failed. The error code is returned by the service
When the tool itself fails, the API may return 200 with success=true and data.isError=true. Check both the HTTP status and data.isError.