feat(mcp): add request metadata helpers and server extension optionsFeature/mcp option by JasperZheng99 · Pull Request #5519 · zeromicro/go-zero

JasperZheng99 · 2026-03-29T03:32:36Z

Closes #5514
Closes #5516

Summary

This PR extends the mcp package with backward-compatible, opt-in extension points for more advanced MCP integrations.

It adds two groups of capabilities:

previously proposed server extension points such as SDK access helpers and request-based server selection
opt-in request metadata extraction so MCP handlers can access selected HTTP request context without changing existing handler signatures

What changed

Server extension points

added NewMcpServerWithOptions(...)
added opt-in constructor options:
- WithServerOptions(...)
- WithServerHook(...)
- WithServerSelector(...)
added SDKServer(server) helper to expose the underlying official go-sdk server
added RemoveTools(server, ...) helper for runtime tool list updates
updated internal request handling to resolve the target SDK server through a shared selector path instead of always returning a single fixed server instance

Request metadata support

added WithRequestMetadataExtractor(...)
added RequestMetadata as a small request-scoped metadata container
added context helpers:
- RequestMetadataFromContext(ctx)
- HeaderFromContext(ctx, key)
- QueryFromContext(ctx, key)
- PathFromContext(ctx, key)
wrapped MCP HTTP handlers so selected request metadata can be extracted once at the route boundary and then consumed from handler context
automatically preserves go-zero path variables via rest/pathvar when path metadata is not explicitly provided by the extractor

Documentation

updated mcp/readme.md
updated mcp/MIGRATION.md

Motivation

The current mcp wrapper is useful for simple MCP integration, but several advanced scenarios were still difficult to support cleanly:

exposing different tool sets on different MCP routes
selecting different MCP server instances based on request context
using official go-sdk capabilities such as hooks/middleware and dynamic tool registry updates
accessing request-scoped metadata such as tenant ID, trace ID, query context, or path variables inside tools, prompts, and resources

This is especially relevant in multi-tenant scenarios, where nearly every tool may need tenant context. Repeating tenant fields in every tool schema is noisy and error-prone, and it treats request context like normal business input.

This PR keeps the existing API surface stable while adding opt-in support for those advanced cases.

Compatibility

This change is intended to be backward-compatible.

existing NewMcpServer(c) behavior remains unchanged
existing tool handler signatures remain unchanged
existing McpServer interface remains unchanged
the new behavior is opt-in only
no existing caller needs to change code unless they want to use the new options/helpers

Tests

Validated with:

gofmt on modified files
go test ./mcp
go test -coverprofile=coverage.out ./mcp && go tool cover -func=coverage.out
diagnostics on mcp/*.go

The mcp package coverage is 100.0%.

In addition, I validated the feature with a standalone sample project outside the repository (go-zero-mcp-test) that exercises:

SSE transport
streamable HTTP transport
request-based server selection
dynamic tool updates
request metadata extraction through actual HTTP requests into MCP handlers

Commits

feat(mcp): add request metadata context helpers
docs(mcp): document request metadata extraction

codecov · 2026-03-30T23:27:22Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR extends the mcp package with opt-in extension points for advanced MCP integrations while keeping the existing NewMcpServer(c) behavior and handler signatures intact. It adds constructor options for SDK server customization/selection and introduces request-metadata extraction that can be consumed from context.Context within MCP handlers.

Changes:

Added NewMcpServerWithOptions and option hooks for SDK server options, hooks, and request-based server selection.
Added SDK access helpers (SDKServer, RemoveTools) and request metadata extraction + context helpers.
Updated docs and expanded mcp package tests to cover the new opt-in features.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
mcp/server.go	Adds option-based constructor, server selector path, and request-metadata injection wrapper for HTTP handlers.
mcp/options.go	Introduces options API, request metadata types/extractor, and context helper functions.
mcp/helpers.go	Adds helpers to expose the underlying SDK server and remove tools at runtime.
mcp/types.go	Updates `AddTool` helper to route through `SDKServer` instead of relying on concrete type assertions + logging.
mcp/server_test.go	Adds test coverage for options, selector behavior, SDK server access, and metadata injection/helpers.
mcp/readme.md	Documents advanced configuration, SDK access helpers, dynamic tool updates, and metadata-in-context usage.
mcp/MIGRATION.md	Updates migration guidance to reference the new helpers/options and metadata approach.

Copilot · 2026-03-30T23:28:42Z

+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		metadata := s.metadata(r)
+		if len(metadata.Path) == 0 {


wrapHandler treats an explicitly provided but empty metadata.Path map the same as “not provided” and overwrites it with pathvar.Vars(r) (because it checks len(metadata.Path) == 0). If callers want to deliberately suppress path propagation, they currently can’t. Consider checking metadata.Path == nil (or adding an explicit opt-out flag) so only an omitted Path is auto-filled, while an explicit empty map remains empty.

Suggested change

if len(metadata.Path) == 0 {

if metadata.Path == nil {

Copilot · 2026-03-30T23:28:43Z

+// HeaderFromContext returns a single extracted header value.
+func HeaderFromContext(ctx context.Context, key string) string {
+	metadata := RequestMetadataFromContext(ctx)
+	if len(metadata.Headers) == 0 {
+		return ""
+	}


HeaderFromContext calls RequestMetadataFromContext, which clones all metadata maps before returning. Since this helper only needs a single string, it could read the RequestMetadata directly from ctx.Value(...) (and skip cloning) to avoid per-call allocations; same applies to QueryFromContext and PathFromContext.

Copilot · 2026-03-30T23:28:43Z

 func AddTool[In, Out any](server McpServer, tool *Tool, handler func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)) {
-	// Access internal server - only works with mcpServerImpl
-	if impl, ok := server.(*mcpServerImpl); ok {
-		sdkmcp.AddTool(impl.mcpServer, tool, handler)
-	} else {
-		logx.Error("AddTool: server must be of type *mcpServerImpl to use this helper")
+	if sdkServer := SDKServer(server); sdkServer != nil {
+		sdkmcp.AddTool(sdkServer, tool, handler)
 	}
 }


AddTool now silently becomes a no-op when server is not the go-zero implementation (i.e., SDKServer(server) == nil). Previously this logged an error, which helped catch misuse. Either restore a warning/error log, or update the doc comment to explicitly call out that AddTool is a no-op for non-go-zero McpServer implementations so failures aren’t silent.

Copilot · 2026-03-30T23:28:43Z

 Added the official MCP SDK:
 ```bash
-go get github.com/modelcontextprotocol/go-sdk@v1.2.0
+go get github.com/modelcontextprotocol/go-sdk@latest
 ```


The migration guide now recommends go get ...@latest, which makes builds non-reproducible and can pull in breaking upstream changes. Prefer documenting a minimum known-good version (or a version range policy) and, if needed, mention that users can choose to upgrade beyond that.

I changed the migration example to pin the SDK version to v1.4.0, which matches the version currently used by the repository.

kevwan · 2026-04-30T00:28:34Z

Review

An excellent, well-documented feature PR that closes #5514 and #5516. The implementation is thoughtful and production-quality.

Architecture:

The PR follows a clean functional options pattern (Option func(*serverOptions)) applied to a new NewMcpServerWithOptions(c, ...Option) constructor, while NewMcpServer(c) becomes a thin wrapper with no options. This is exactly the right approach for backward compatibility.

Feature-by-feature analysis:

Server extension options (`options.go`)

WithServerOptions — passes *sdkmcp.ServerOptions to the underlying SDK constructor. ✅
WithServerHook — applies a callback to the *sdkmcp.Server post-construction (for middleware, dynamic tools). Nil-safe. ✅
WithServerSelector — allows routing different requests to different SDK server instances. Falls back to the default server when the selector returns nil. ✅

Request metadata (`options.go` + `server.go`)

RequestMetadata is a simple, copyable value type — no pointers, no sync. ✅
wrapHandler correctly short-circuits when s.metadata == nil (zero-overhead path for users not opting in). ✅
Defensive cloning in cloneRequestMetadata / cloneStringMap prevents handler mutation of the stored metadata. ✅
Auto-populates Path from pathvar.Vars(r) when the extractor doesn't set it explicitly — very practical. ✅
Context key uses private struct type (requestMetadataContextKey{}) — correct pattern to avoid key collisions. ✅

SDK access helpers (`helpers.go`)

SDKServer(server) uses type assertion — returns nil for non-go-zero implementations. The docstring makes this explicit. ✅
RemoveTools is nil-safe. ✅
AddTool in types.go correctly refactored to use the new SDKServer() helper. ✅

Test coverage: The test file is comprehensive (269 additions), covering:

NewMcpServerWithOptions hook invocation
Server selector fallback behavior
RequestMetadata context isolation (mutation after extraction doesn't affect stored value)
wrapHandler with/without extractor, with/without path vars
Nil context safety

The author claims 100% coverage for mcp/ — impressive.

Minor suggestions (non-blocking):

WithServerHook appends to a slice but callers typically expect a single hook. Multiple hooks is fine, but the naming WithServerHook (singular) might suggest only one is supported. Consider documenting that multiple calls accumulate.
The ServerSelector type returns *sdkmcp.Server but the go-zero MCP server wraps *sdkmcp.Server — if a user accidentally passes a *sdkmcp.Server created outside the selector, it won't have the request metadata context injection. A comment clarifying this would help advanced users.
When the extractor returns an empty RequestMetadata (all nil maps), wrapHandler skips injecting the context value. This means RequestMetadataFromContext returns zero value — consistent and correct, but worth noting in docs for users debugging "why isn't my metadata available."

Overall: This is a high-quality feature contribution. Clean API, correct implementation, thorough tests, and clear documentation. LGTM.

kevwan requested a review from Copilot March 30, 2026 23:24

Copilot started reviewing on behalf of kevwan March 30, 2026 23:25 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

JasperZheng99 force-pushed the feature/mcp-option branch from 85273d6 to ebbae57 Compare April 4, 2026 04:50

JasperZheng99 added 6 commits April 4, 2026 13:03

feat(mcp): add opt-in server selector and sdk helpers

850ef53

docs(mcp): align MCP docs with sdk-based server options

cc25437

feat(mcp): add request metadata context helpers

9bcceae

docs(mcp): document request metadata extraction

27285b6

Merge branch 'master' into feature/mcp-option

a7e5a5c

test(mcp): avoid nil context literals in metadata helpers test

56c20d7

JasperZheng99 force-pushed the feature/mcp-option branch from ebbae57 to 56c20d7 Compare April 4, 2026 05:04

JasperZheng99 added 2 commits April 4, 2026 13:44

fix(mcp): preserve explicit empty path metadata

0ee5801

docs(mcp): clarify AddTool behavior and pin sdk version

0b7a36d

JasperZheng99 force-pushed the feature/mcp-option branch from 20994a5 to 0b7a36d Compare April 4, 2026 05:46

Merge branch 'master' into feature/mcp-option

62a28a6

kevwan mentioned this pull request Apr 30, 2026

Support opt-in MCP server hooks and route-based server selection #5514

Open

kevwan added the enhancement New feature or request label Apr 30, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(mcp): add request metadata helpers and server extension optionsFeature/mcp option#5519

feat(mcp): add request metadata helpers and server extension optionsFeature/mcp option#5519
JasperZheng99 wants to merge 9 commits into
zeromicro:masterfrom
JasperZheng99:feature/mcp-option

JasperZheng99 commented Mar 29, 2026

Uh oh!

codecov Bot commented Mar 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

Copilot AI Mar 30, 2026

Uh oh!

JasperZheng99 Apr 4, 2026

Uh oh!

kevwan commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

JasperZheng99 commented Mar 29, 2026

Summary

What changed

Server extension points

Request metadata support

Documentation

Motivation

Compatibility

Tests

Commits

Uh oh!

codecov Bot commented Mar 30, 2026

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

JasperZheng99 Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

kevwan commented Apr 30, 2026

Review

Server extension options (options.go)

Request metadata (options.go + server.go)

SDK access helpers (helpers.go)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Server extension options (`options.go`)

Request metadata (`options.go` + `server.go`)

SDK access helpers (`helpers.go`)