{
  "id": "art_BCRnt8kPpkcI",
  "slug": "mcp-jsonrpc-32602-parameter-validation-error-solution-guide",
  "author": "goumang",
  "title": "MCP JSONRPC-32602 参数验证错误解决指南",
  "summary": "详解 MCP 工具调用中最常见的参数验证错误 -32602，包含错误原因、排查流程和解决方案。适用于 AI Agent 调用 MCP 工具时遇到参数问题的场景。",
  "content": "# MCP-JSONRPC-32602 错误排查指南\n\n## 概述\n\n**MCP-JSONRPC-32602** 是 MCP（Model Context Protocol）工具调用中最常见的错误之一。当 AI Agent 调用 MCP 工具时，如果提供的参数不符合工具定义的 schema 要求，服务器将返回此错误。\n\n这个错误通常意味着：\n- ❌ 缺少必填参数\n- ❌ 参数类型不匹配\n- ❌ 参数值超出有效范围\n- ❌ 参数格式不正确\n\n## 错误响应格式\n\n当发生此错误时，MCP 服务器返回的标准错误响应结构如下：\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 42,\n  \"error\": {\n    \"code\": -32602,\n    \"message\": \"Invalid params\",\n    \"data\": {\n      \"param\": \"connection_string\",\n      \"reason\": \"missing required parameter\"\n    }\n  }\n}\n```\n\n## 常见原因与解决方案\n\n### 原因 1：缺少必填参数\n\n**解决方案：** 检查工具定义中的 `required` 字段，确保所有必填参数都已提供。\n\n### 原因 2：参数类型不匹配\n\n**解决方案：** 确保传递的参数类型与工具定义一致。\n\n### 原因 3：参数名拼写错误\n\n**解决方案：** 仔细核对参数名，注意大小写敏感。\n\n### 原因 4：参数值超出范围\n\n**解决方案：** 调整参数值到有效范围内。\n\n## 参考来源\n\n- JSON-RPC 2.0 Specification\n- MCP Error Codes - mcpevals.io\n- MCP Schema Reference",
  "lang": "zh",
  "domain": "error_codes",
  "tags": [
    "mcp",
    "error_codes",
    "jsonrpc",
    "invalid_params",
    "troubleshooting",
    "parameter_validation",
    "tool_calling"
  ],
  "keywords": [
    "mcp",
    "jsonrpc",
    "-32602",
    "invalid-params",
    "parameter-validation",
    "tool-calling",
    "error-handling",
    "schema-validation",
    "ai-agent"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 98,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "如何快速定位是哪个参数出了问题？",
      "answer": "查看错误响应中的 `data` 字段，通常会包含 `param` 和 `reason` 字段指明具体参数和原因。"
    },
    {
      "id": "qa_002",
      "question": "参数名拼写错误会导致什么错误？",
      "answer": "参数名拼写错误通常返回 -32602，但有时 Claude Desktop 会误报为 \"No such tool available\"。建议仔细核对参数名的大小写和拼写。"
    },
    {
      "id": "qa_003",
      "question": "可选参数可以传 null 吗？",
      "answer": "取决于工具的具体实现。有些工具接受 `null` 作为可选参数的占位值，有些则要求完全省略该参数。建议查看工具文档或测试确认。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmoev2qr0003pdw9ng4yp0ua",
      "articleId": "art_BCRnt8kPpkcI",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-13T04:42:54.243Z"
    },
    {
      "id": "cmmoeuvbi0001pdw9fs1xspu1",
      "articleId": "art_BCRnt8kPpkcI",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-13T04:42:44.623Z"
    }
  ],
  "relatedIds": [
    "art_oZd42bjUpMtw"
  ],
  "publishedAt": "2026-03-13T04:42:42.244Z",
  "updatedAt": "2026-04-04T18:24:59.017Z",
  "createdAt": "2026-03-13T04:42:41.036Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=mcp-jsonrpc-32602-parameter-validation-error-solution-guide",
      "json": "/api/v1/articles/mcp-jsonrpc-32602-parameter-validation-error-solution-guide?format=json&lang=zh",
      "markdown": "/api/v1/articles/mcp-jsonrpc-32602-parameter-validation-error-solution-guide?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/mcp-jsonrpc-32602-parameter-validation-error-solution-guide?format=json&lang=zh\""
  }
}