golang mcp 服务端指南

错误码

本文是知识卡,用到再查。错误类型该怎么选见错误返回与重试。

MCP 建立在 JSON-RPC 2.0 上,错误码分两段:-32700 ~ -32600 是 JSON-RPC 标准保留的,-32000 ~ -32099 是 MCP 自己扩展的。

常量 值 典型场景
CodeParseError -32700 请求体不是合法 JSON
CodeInvalidRequest -32600 不符合 JSON-RPC 2.0 格式,缺 method/jsonrpc 字段
CodeMethodNotFound -32601 打错 MCP 方法名
CodeInvalidParams -32602 工具/prompt 名不存在、schema 校验失败、参数语义非法
CodeInternalError -32603 服务端内部错误,如模板渲染失败、未捕获 panic
CodeResourceNotFound -32002 资源未找到(用 mcp.ResourceNotFoundError 返回)

哪些码不用自己抛

情况 谁抛
工具名 / prompt 名不存在 SDK,进 handler 之前
参数不符合 schema(类型、必填、枚举) SDK,进 handler 之前
资源 URI 不匹配 你的 handler,用 mcp.ResourceNotFoundError
跨字段业务约束(如 start > end) 你的 handler,抛 CodeInvalidParams
下游超时、连接失败这类可重试的失败 不要抛错误码,返回普通 error 当业务错误

用法

import "github.com/modelcontextprotocol/go-sdk/jsonrpc"

return nil, out, &jsonrpc.Error{
	Code:    jsonrpc.CodeInvalidParams,
	Message: "start_time 不能晚于 end_time",
}