MCP Go SDK 官方文档总览包结构、功能地图与实战导航【免费下载链接】go-sdkThe official Go SDK for Model Context Protocol servers and clients. Maintained in collaboration with Google.项目地址: https://gitcode.com/GitHub_Trending/gosdk23/go-sdk导读本文以 docs/README.md 为骨架系统梳理 Model Context ProtocolMCP官方 Go SDK 的可导入包结构与功能文档地图。你将掌握mcp、jsonrpc、auth、oauthex四大包的职责边界了解 SDK 对 MCP 基础协议、客户端特性与服务端特性的完整实现路径并借助快速开始、故障排查、兼容性与已知边界文档快速定位到实战所需的关键代码与配置。阅读完成后你将能按图索骥地找到「如何实现一个工具」「如何配置传输层」「如何接入 OAuth」等具体问题的答案。一、SDK 包结构总览MCP Go SDK 由若干个可独立导入的包组成每个包对应协议栈中的一个层次。理解这些包的边界是使用 SDK 的第一步包职责mcp定义构建与使用 MCP 客户端、服务端的核心 API包括Client、Server、ClientSession、ServerSession以及各类传输Transport实现jsonrpc面向需要自行实现传输层的用户提供 JSON-RPC 2.0 基础协议支持auth提供支撑 OAuth 的原语例如RequireBearerToken中间件与AuthorizationCodeHandleroauthex提供对 OAuth 协议的扩展例如ProtectedResourceMetadata受保护资源元数据从 go.mod 可以看到SDK 基于 Go 1.25并依赖github.com/google/jsonschema-go工具输入输出 schema 推断、golang.org/x/oauth2OAuth 流程、github.com/golang-jwt/jwt/v5JWT 校验等关键第三方库。SDK 的目标是完整实现 MCP 规范specdocs/目录下的功能文档将 MCP 规范逐项映射到上述包与具体 API 上。以下章节即按 docs/README.md 的索引顺序逐一给出各功能领域的要点与文档导航。二、Base Protocol基础协议支持基础协议部分由 docs/protocol.md 详细展开覆盖生命周期、传输、授权、安全与工具五个主题。生命周期LifecycleSDK 同时支持 MCP 规范的两种生命周期模型并根据协商出的协议版本自动切换传统initialize握手用于2025-11-25及更早的协议版本。服务端会话只有在客户端发送notifications/initialized之后才算初始化完成可通过ServerOptions.InitializedHandler监听。无状态模型2026-07-28起由 SEP-2575 引入不再有initialize/notifications/initialized握手每个请求通过_meta携带协议版本与客户端能力。两种模型下 API 保持一致Client通过ClientOptions配置调用Client.Connect后创建ClientSessionServer通过ServerOptions配置调用Server.Connect后创建ServerSession两个 Session 都提供Close终止会话与Wait等待对端终止会话方法通常由客户端负责结束会话。2026-07-28还引入了server/discoverRPC服务端在Server.Connect时自动注册该 handler客户端则先调用它来协商双方都支持的协议版本协商失败时回退到传统握手。如需收窄服务端支持的协议版本集合可设置ServerOptions.SupportedProtocolVersions该集合只能收窄、不能扩大server : mcp.NewServer(mcp.Implementation{Name: server, Version: v1.0.0}, mcp.ServerOptions{ SupportedProtocolVersions: []string{2026-07-28, 2025-11-25}, })每请求元数据当协商版本为2026-07-28及以上时每个请求的_meta会携带以下键常量定义在 mcp/protocol.go常量线上键名类型是否必填MetaKeyProtocolVersionio.modelcontextprotocol/protocolVersionstring是MetaKeyClientCapabilitiesio.modelcontextprotocol/clientCapabilities*ClientCapabilities是MetaKeyClientInfoio.modelcontextprotocol/clientInfo*Implementation否MetaKeyLogLevelio.modelcontextprotocol/logLevelLoggingLevel已被 SEP-2577 废弃否响应侧服务端应通过MetaKeyServerInfoio.modelcontextprotocol/serverInfo在每条响应中标识自身。服务端 handler 可通过ServerRequest[P].ProtocolVersion()、ClientInfo()、ClientCapabilities()读取这些值。订阅Subscriptions2026-07-28用subscriptions/listen取代了传统的resources/subscribeRPC 与 GET 型 SSE 端点。客户端在一个长连接请求中声明关注项toolsListChanged、promptsListChanged、resourcesListChanged及具体资源 URI服务端先以notifications/subscriptions/acknowledged回报采纳的子集再在同一请求上流式推送变更通知。传输层Transports传输层通过实现Transport接口JSON-RPC 消息的逻辑双向流来工作。注意传输实例不应被多个连接复用多连接请使用不同的传输。SDK 内置以下实现Stdio客户端侧由CommandTransport实现启动exec.Cmd子进程并与其 stdin/stdout 通信服务端侧由StdioTransport实现连接当前进程的os.Stdin/os.Stdout。这是本地 MCP server 最常用的模式。Streamable HTTP由三个类型协同实现——StreamableHTTPHandlerHTTP handler、StreamableServerTransport服务端传输、StreamableClientTransport客户端传输。客户端侧只需指定Endpointtransport : mcp.StreamableClientTransport{ Endpoint: http://localhost:8080/mcp, } client : mcp.NewClient(mcp.Implementation{Name: client, Version: v1.0.0}, nil) session, err : client.Connect(ctx, transport, nil)Streamable 传输在2026-07-28会话上还会校验一组 MCP 专属 HTTP 头SEP-2243Mcp-Protocol-Version、Mcp-Session-Id、Mcp-Method、Mcp-Name以及工具参数透传的Mcp-Param-{Header}。当Mcp-Method/Mcp-Name与 JSON-RPC 请求体不一致时服务端返回-32020CodeHeaderMismatch。工具可用x-mcp-header注解其InputSchema属性使 SDK 在 HTTP 调用时自动将参数序列化为请求头。Legacy SSE为兼容2024-11-05协议的旧对端而保留SSEHandler/SSEServerTransport/SSEClientTransport新部署应改用 Streamable。自定义传输实现Transport接口即可完整示例见 examples/server/custom-transport/main.go。关于 Streamable 的几个关键选项StreamableHTTPOptions.EventStore用于开启消息的可恢复性resumability/重投递SDK 内置MemoryEventStore供测试与简单场景使用StreamableHTTPOptions.Stateless开启无状态模式不校验 session id临时会话处理请求此时服务端无法主动向客户端发请求。注意2026-07-28版本请求仅在Stateless true时才被 Streamable HTTP 传输接受。分布式无状态服务端示例见 examples/server/distributed/main.go。授权Authorization服务端使用auth.RequireBearerToken中间件包裹 HTTP handler例如NewStreamableHTTPHandler返回的 handler它会校验每个请求的Authorization: Bearer token头并把 token 解析与校验委托给TokenVerifier过期与 scope 检查由中间件完成通过RequireBearerTokenOptions.Scopes。若设置了ResourceMetadataURL且校验失败中间件会按 RFC 9728 设置WWW-Authenticate头。服务端 handler 可通过req.Extra.TokenInfo或auth.TokenInfoFromContext获取TokenInfo。OAuth 2.0 资源服务器还应暴露受保护资源元数据端点RFC 9728SDK 提供ProtectedResourceMetadataHandler自动设置Access-Control-Allow-Origin: *metadata : oauthex.ProtectedResourceMetadata{ Resource: https://example.com/mcp, AuthorizationServers: []string{ https://auth.example.com/.well-known/openid-configuration, }, ScopesSupported: []string{read, write}, } http.Handle(/.well-known/oauth-protected-resource, auth.ProtectedResourceMetadataHandler(metadata))JWT 与 API Key 的完整授权示例见 examples/server/auth-middleware/main.go。客户端将StreamableClientTransport.OAuthHandler配置为auth.AuthorizationCodeHandler传输层会自动为每个请求附加Authorization: Bearer token并在收到401/403时调用 handler 的Authorize方法以完成授权或 scope 提升。该 handler 支持 Client ID Metadata 文档、预注册客户端、动态客户端注册DCR以及 RFC 9207 的授权服务器 Issuer 识别authHandler, _ : auth.NewAuthorizationCodeHandler(auth.AuthorizationCodeHandlerConfig{ RedirectURL: https://myapp.com/oauth2-callback, // 三选一配置 // ClientIDMetadataDocumentConfig: ... // PreregisteredClientConfig: ... // DynamicClientRegistrationConfig: ... AuthorizationCodeFetcher: func(ctx context.Context, args *auth.AuthorizationArgs) (*auth.AuthorizationResult, error) { // 在浏览器打开 args.URL从回调中取回 code、state、iss // 完整示例见 examples/auth/client/main.go return auth.AuthorizationResult{Code: code, State: state, Iss: iss}, nil }, })此外auth/extauth包提供了面向企业 SSO 的EnterpriseHandlerSEP-990自动完成「OIDC 登录 → RFC 8693 Token Exchange → RFC 7523 JWT Bearer Grant」三步流程注意它有意不支持 refresh tokentoken 过期后重走完整授权流程以保证企业策略一致。示例见 examples/auth/enterprise/main.go。安全Securitydocs/protocol.md 对照 MCP 官方安全最佳实践逐项说明了 SDK 的处理方式Confused DeputySDK 客户端默认每次授权请求都生成密码学安全的随机state并在授权码返回时校验不匹配即报错。Token Passthrough依赖TokenVerifier校验 token 是否签发给本服务端。SSRFOAuth 发现辅助函数默认强制 HTTPS、拦截私有 IP 段含169.254.169.254元数据端点、校验重定向目标并限制重定向次数。注意传入自定义http.Client自定义DialContext、非*http.Transport、配置了Proxy或自定义CheckRedirect会绕过这些防护此时需自行实现 IP 拦截、重定向校验与 DNS 固定。Session HijackingSDK 默认生成密码学安全的会话 ID若通过ServerOptions.GetSessionID自定义建议使用crypto/rand.Text。当TokenVerifier在TokenInfo.UserID中设置用户标识时Streamable 传输会把用户 ID 绑定到会话后续请求 token 的用户 ID 不一致则返回403——这能有效防止攻击者用合法 token 劫持他人会话。Issuer Mix-Up客户端按 RFC 9207 校验授权响应中的iss参数若授权服务器元数据声明authorization_response_iss_parameter_supported: true而响应缺失iss则拒绝该响应。工具Utilities取消Cancellation基于 context 取消实现。取消ClientSession/ServerSession方法所用的 context 会终止 RPC 并向对端发送notifications/cancelled。PingClientSession.Ping与ServerSession.Ping对称支持设置ClientOptions.KeepAlive或ServerOptions.KeepAlive可自动周期 ping 并关闭失联会话。注意2026-07-28起 ping 已从协议中移除双方协商该版本时服务端对 ping 返回-32601此时不应启用 KeepAlive。进度Progress从请求元数据读取 progress token通过NotifyProgress上报通过ProgressNotificationHandler监听。错误码SDK 使用标准 JSON-RPC 基础错误码外加 MCP 专属码-32020CodeHeaderMismatchHTTP 头与请求体不匹配、-32021CodeMissingRequiredClientCapabilities缺少必需客户端能力、-32022CodeUnsupportedProtocolVersion不支持的协议版本附带UnsupportedProtocolVersionData、-32602CodeResourceNotFound资源 URI 未找到。2026-07-28起-32020~-32099被保留给 MCP 规范使用。三、Client Features客户端特性客户端特性由 docs/client.md 详细展开。Roots根目录客户端用Client.AddRoots/Client.RemoveRoots管理文件系统根根列表变化会向每个已连接的服务端发送notifications/roots/list_changed服务端通过ServerOptions.RootsListChangedHandler感知变更并用ServerSession.ListRoots读取最新列表。注意roots 特性自协议版本2026-07-28起被 SEP-2577 废弃仍会在至少 12 个月的废弃窗口内保持可用。新代码应改用工具参数、资源 URI 或配置来传递路径。Sampling采样采样允许服务端复用客户端的 AI 能力。客户端设置ClientOptions.CreateMessageHandler即可声明sampling能力服务端通过ServerSession.CreateMessage发起请求。该特性同样已被 SEP-2577 废弃需要 LLM 补全的服务端应直接调用 LLM 提供方 API。Elicitation引导输入引导允许服务端向用户请求输入。客户端设置ClientOptions.ElicitationHandler返回值必须匹配请求的 schema否则报错服务端通过ServerSession.Elicit发起。关键细节Schema 默认值与枚举ElicitParams.RequestedSchema是扁平的原语字段 schema。字段的DefaultSEP-1034会在用户未填时自动填充无开关、无条件生效标记为Required的默认字段反而会因先校验后填充而被拒绝EnumSEP-1330仅支持string类型字段可选值标签通过Schema.Extra中的enumNames提供数量必须与枚举值一一对应。URL 模式完成URL 模式下用户在浏览器中带外完成输入服务端通过ServerSession.NotifyElicitationComplete携带相同的ElicitationID通知客户端客户端通过ClientOptions.ElicitationCompleteHandler接收。当 handler 返回URLElicitationRequiredError时客户端会挂起原请求直到收到该ElicitationID的完成通知后自动重试。Multi Round-Trip RequestsMRTRSEP-2322 引入的 MRTR 模式服务端对采样、引导、roots 的请求不再作为独立 JSON-RPC 请求发出而是携带在tools/call、prompts/get、resources/read的进行中回复里CallToolResult.InputRequests字段客户端必须携带生成的响应重试原请求。SDK 默认给每个客户端安装clientMultiRoundTripMiddleware它并发地 fan-out 每个InputRequests条目、调用对应 handlerelicit、createMessage、listRoots、原样回传服务端提供的RequestState然后重试原请求直到结果不再需要输入。如需退出该机制设置ClientOptions.MultiRoundTrip.Disabled true此时客户端会把需要输入的InputRequiredResult直接暴露给调用方由你的代码自行完成往返。客户端能力Capabilities推断默认情况下 SDK 客户端广告rootslistChanged: true能力设置ClientOptions上的 handler 会自动补齐对应能力如CreateMessageHandler增加sampling、ElicitationHandler增加elicitation。未显式配置时引导能力默认只启用 form 模式URL 模式需显式声明。显式配置设置ClientOptions.Capabilities可覆盖推断结果。例如传入空ClientCapabilities{}禁用全部默认能力设置ListChanged: false关闭根列表变更通知指定引导模式组合client : mcp.NewClient(impl, mcp.ClientOptions{ Capabilities: mcp.ClientCapabilities{ Elicitation: mcp.ElicitationCapabilities{ Form: mcp.FormElicitationCapabilities{}, URL: mcp.URLElicitationCapabilities{}, }, }, ElicitationHandler: handler, })扩展ExtensionsSEP-2133 为ClientCapabilities增加了extensions映射允许在线上声明核心协议之外的可选能力键名采用{vendor-prefix}/{extension-name}命名空间。四、Server Features服务端特性服务端特性由 docs/server.md 详细展开。Prompts提示模板服务端用Server.AddPrompt(prompt, handler)注册提示模板在连接前注册任何 prompt或显式设置ServerOptions.HasPrompts即可获得prompts能力。客户端用ClientSession.Prompts迭代器或ListPrompts列出用GetPrompt按名获取并展开参数。PromptMessage由Roleuser或assistant与单个Content组成与工具结果共用同一内容接口因此一条 prompt 消息可以携带文本、图片、音频或资源内容EmbeddedResource内联资源内容可省去客户端单独的resources/readResourceContents.URI仅记录来源不会被校验。媒体内容本身不表达模型应如何处理建议同时附一条文本消息说明用途。Resources资源资源是「由 URI 引用的数据」可单个注册Server.AddResource或以 URI 模板注册集合Server.AddResourceTemplate例如file:///dir/{f}。客户端用ReadResource读取SDK 保证只有精确匹配的 URI 或匹配模板的 URI 才能读成功、用Resources/ResourceTemplates迭代器列出。二进制资源ResourceContents通过Text或Blob携带数据二进制放BlobSDK 在线上自动 base64 编码。资源订阅客户端用ClientSession.Subscribe/Unsubscribe订阅/退订某个 URI服务端设置SubscribeHandler/UnsubscribeHandler跟踪订阅者并因此获得resources.subscribe能力。内容变更时用Server.ResourceUpdated广播——通知只携带 URI 不携带内容客户端需要自行重新读取。在2026-07-28及以后的会话上这些通知改经subscriptions/listen流投递见基础协议章节。Tools工具Server.AddTool是注册工具的对称 API但它要求你自行实现输入输出 schema、参数校验、编解码、结果打包等大量细节。为此 SDK 提供了泛型mcp.AddTool函数可将工具绑定到如下形状的普通 Go 函数func(_ context.Context, request *CallToolRequest, input In) (result *CallToolResult, output Out, _ error)该函数自动完成从In类型推断输入 schema未显式设置时、从Out类型推断输出 schema非any时、校验并反序列化参数、把Out序列化进StructuredContent与非结构化的Content、校验输出 schema、普通 error 会被打包进CallToolResult并置IsError true。可选的jsonschema结构体标签提供字段描述。天气工具的完整示例含自定义jsonschema.ForOptions.TypeSchemas复用自定义 schema、微调推断出的 schema 约束见 mcp/tool_example_test.go 与 examples/server/toolschemas/main.go。工具结果内容CallToolResult.Content可以混合多种内容块类型携带内容TextContent纯文本ImageContent图片数据 MIME 类型AudioContent音频数据 MIME 类型EmbeddedResource内联的资源内容ResourceLink资源引用客户端可单独读取ImageContent.Data/AudioContent.Data是裸[]byteSDK 线上自动 base64 编码从其他 SDK 迁来的 base64 数据需先解码再赋值。当客户端可能不需要内容时优先用ResourceLink因为内联资源无论是否使用都会被传输。无状态服务端部署若每个请求都新建Server并重新注册工具可创建并共享一个mcp.SchemaCache来避免重复的 schema 生成var schemaCache mcp.NewSchemaCache() // 启动时创建一次 func handleRequest(w http.ResponseWriter, r *http.Request) { s : mcp.NewServer(impl, mcp.ServerOptions{SchemaCache: schemaCache}) mcp.AddTool(s, myTool, myHandler) // ... }列表变更通知List changed notifications在已连接的 server 上增删特性会向所有客户端发送对应的notifications/*/list_changed客户端通过ToolListChangedHandler、PromptListChangedHandler、ResourceListChangedHandler接收。通知只表示「列表变了」客户端需重新拉取。注意这些通知依赖能力声明而能力由连接前注册的内容推断——如果你在Server.Connect之后才动态注册特性必须自行声明ServerOptions.HasTools/HasPrompts/HasResources该字段现已废弃推荐改用Capabilities显式声明。服务端 MRTR 与旧客户端兼容服务端自动安装serverMultiRoundTripMiddleware对协议版本早于2026-07-28的旧客户端中间件会拦截 handler 返回的InputRequiredResult自行调用旧式服务端发起请求 APIElicit、CreateMessage、ListRoots完成每个输入请求再携带响应重新调用一次 handler。因此用 MRTR 风格编写的 handler 无需改动即可同时服务新旧客户端。一个典型的 MRTR 风格「greet」工具handler 运行两次——第一次返回InputRequests中的引导请求与不透明RequestState第二次消费响应生成最终结果完整示例见 docs/server.md 的Example_mrtr客户端调用侧看到的是单个CallTool返回最终结果。可缓存的列表结果Cacheable list resultsSEP-2549 为tools/list、prompts/list、resources/list、resources/templates/list与resources/read的结果增加ttlMs新鲜度提示客户端据此减少轮询与cacheScopepublic/private控制共享中间件是否可缓存。SDK 在结果留空时自动填CacheScope publicServerOptions.SetCacheable可为每条结果统一设置策略server : mcp.NewServer(impl, mcp.ServerOptions{ SetCacheable: func(_ context.Context, req mcp.Request, c *mcp.Cacheable) { // 30 秒新鲜度提示除非 handler 自己设置了值 if c.TTLMs 0 { c.TTLMs 30_000 } }, })注意SetCacheable可能在持有 server 锁时执行因此回调中不得再调用Server的方法增删特性、遍历Server.Sessions都会死锁。服务端工具Utilities与能力Completion设置ServerOptions.CompletionHandler即声明completions能力并响应补全请求客户端通过ClientSession.Complete调用。Logging已按 SEP-2577 废弃。服务端可用低层ServerSession.Log或基于slog的NewLoggingHandler向客户端发送日志LoggingHandlerOptions.MinInterval可限流客户端用LoggingMessageHandler接收、用ClientSession.SetLevelSetLoggingLevel调整最小日志级别。状态会话默认不发任何日志直到客户端SetLevel无状态会话默认级别为info。能力推断与显式声明服务端默认只广告logging能力注册特性如AddTool增加tools或设置 handler如SubscribeHandler/CompletionHandler会自动推断对应能力默认值为{listChanged:true}。用ServerOptions.Capabilities可显式覆盖// 关闭 tools 的 listChanged 通知 server : mcp.NewServer(impl, mcp.ServerOptions{ Capabilities: mcp.ServerCapabilities{ Logging: mcp.LoggingCapabilities{}, Tools: mcp.ToolCapabilities{ListChanged: false}, }, })传入空ServerCapabilities{}可禁用全部默认能力。ServerCapabilities同样支持extensions映射SEP-2133。分页Pagination服务端分页默认开启ServerOptions.PageSize可自定义页大小客户端侧ClientSession提供iter.Seq2[Feature, error]迭代器Prompts、Resources、ResourceTemplates、Tools与更细粒度的ListXXX方法。五、快速开始Quick Startdocs/quick_start.md 给出了安装与首个端到端示例。安装只需go get github.com/modelcontextprotocol/go-sdk/mcp一个最小 MCP server注册单个工具经 stdin/stdout 运行package main import ( context log github.com/modelcontextprotocol/go-sdk/mcp ) type Input struct { Name string json:name jsonschema:the name of the person to greet } type Output struct { Greeting string json:greeting jsonschema:the greeting to tell to the user } func SayHi(ctx context.Context, req *mcp.CallToolRequest, input Input) ( *mcp.CallToolResult, Output, error, ) { return nil, Output{Greeting: Hi input.Name}, nil } func main() { // 创建一个带单个工具的服务端。 server : mcp.NewServer(mcp.Implementation{Name: greeter, Version: v1.0.0}, nil) mcp.AddTool(server, mcp.Tool{Name: greet, Description: say hi}, SayHi) // 通过 stdin/stdout 运行直到客户端断开。 if err : server.Run(context.Background(), mcp.StdioTransport{}); err ! nil { log.Fatal(err) } }对应的客户端创建mcp.Client用CommandTransport启动服务端子进程并连接然后调用工具func main() { ctx : context.Background() // 创建不带任何特性的客户端。 client : mcp.NewClient(mcp.Implementation{Name: mcp-client, Version: v1.0.0}, nil) // 通过 stdin/stdout 连接服务端。 transport : mcp.CommandTransport{Command: exec.Command(myserver)} session, err : client.Connect(ctx, transport, nil) if err ! nil { log.Fatal(err) } defer session.Close() // 调用服务端上的工具。 params : mcp.CallToolParams{ Name: greet, Arguments: map[string]any{name: you}, } res, err : session.CallTool(ctx, params) if err ! nil { log.Fatalf(CallTool failed: %v, err) } if res.IsError { log.Fatal(tool failed) } for _, c : range res.Content { log.Print(c.(*mcp.TextContent).Text) } }更多客户端与服务端示例见 examples/ 目录涵盖 basic、completion、custom-method、distributed、everything、memory、middleware、proxy、sse、toolschemas 等场景以及本仓库根目录 README.md 的版本兼容性表格SDK 各版本对应的 MCP 规范版本支持范围。六、故障排查指南Troubleshootingdocs/troubleshooting.md 建议遇到问题时请在 bug report 中尽可能提供下述调试信息以帮助维护者快速定位。使用 MCP inspector用于测试你的 server 与 TypeScript SDK 的互操作性并检查 MCP 流量。收集 MCP 日志stdio用LoggingTransport包裹任意传输即可把线上 JSON-RPC 消息写入bytes.Buffer、文件或os.StderrlogTransport : mcp.LoggingTransport{Transport: t2, Writer: b} clientSession, err : client.Connect(ctx, logTransport, nil)检查 HTTP 流量一是用标准 HTTP 中间件包裹StreamableHTTPHandler打印方法与请求体后再转发二是使用 wireshark、tcpdump 等通用抓包工具。七、向后兼容性与 MCPGODEBUGdocs/mcpgodebug.md 解释了 SDK 的兼容性策略为修复 bug 或安全问题某些行为变更以「临时兼容参数」的形式提供通过MCPGODEBUG环境变量逗号分隔的参数值列表开启旧行为通常保留两个 minor 版本周期后移除MCPGODEBUGparameter1value1,parameter2value2以 1.8.0 引入、计划于 1.9.0 移除的选项为例plaintextstatefulrejection置1时有状态StreamableHTTPHandler收到携带每请求元数据的请求时恢复为纯文本 400 响应默认行为改为返回-32022JSON-RPC 错误使客户端可重协商、避免连接被整体拆除。blockingcancelnotify置1时被取消的调用同步等待notifications/cancelled送达上限 5 秒再返回默认行为改为调用立即返回、通知异步发送避免被慢对端拖住调用方返回路径。其余历史选项含已按计划移除的seterroroverwrite、enableoriginverification、disablecontenttypecheck、disablelocalhostprotection以及 1.7.0/1.6.x/1.4.x 引入的customresnotfounderrcode、hintomitempty、allowsessionsinstateless、nomethodnotfoundcodeinerror、noprotocolerrorbody、nowrapinvalidparams、disablecompleteparamsvalidation、jsonescaping、disablecrossoriginprotection等的完整说明与移除计划请直接查阅 docs/mcpgodebug.md。八、已知粗糙边缘Rough Edgesdocs/rough_edges.md 记录了 v1.0.0 之后发现的、因兼容性承诺而无法修复的 API 疏漏计划在 v2 中重新审视。理解这些点有助于避免踩坑EventStore.Open无必要早期版本的产物可空实现。Event本不应导出其Name字段命名有误应为event。工具名校验SEP-986 落地时 SDK 已到 v1无法对非法工具名 panic只能输出错误日志v2 将改为 panic。命名不一致ResourceUpdatedNotificationsParams、ProgressNotificationParams等命名冗长AudioContent.MarshalJSON应使用指针接收者。ClientCapabilities.Roots应为有区分的结构体指针见 issue #607变通方案是使用RootsV2。默认能力本应为空服务端默认广告logging、客户端默认广告roots{listChanged:true}导致 nilCapabilities并不等于「无能力」。变通方案是显式传入空的ServerCapabilities{}/ClientCapabilities{}。CreateMessageResult.Content为单个Content而 2025-11-25 规范允许单块或数组CreateMessageResultWithToolsContent []Content是变通方案。StreamableHTTPOptions.CrossOriginProtection不应属于 SDK API跨源防护是通用 HTTP 关注点应作为标准中间件处理。ToolAnnotations的所有字段应类型化为*bool以精确控制线上发送内容不同 MCP 客户端要求不同部分客户端要求所有字段显式为true/false。结语docs/README.md 是整个 SDK 文档体系的入口它先勾勒出mcp、jsonrpc、auth、oauthex四个包的分工再把 MCP 规范的每一部分映射到具体的功能文档与 API。配合 docs/protocol.md、docs/client.md、docs/server.md 三份核心文档以及 docs/quick_start.md、docs/troubleshooting.md、docs/mcpgodebug.md、docs/rough_edges.md 四份配套文档开发者可以在几分钟内从「SDK 有哪些包」走到「如何实现一个带授权、走 Streamable 传输、支持 MRTR 引导的工具服务端」。建议按「快速开始 → 服务端特性 → 基础协议 → 客户端特性」的顺序阅读实践遇到行为异常时再回到故障排查与兼容性章节定位。【免费下载链接】go-sdkThe official Go SDK for Model Context Protocol servers and clients. Maintained in collaboration with Google.项目地址: https://gitcode.com/GitHub_Trending/gosdk23/go-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考