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

[JasperZheng99]

Is your feature request related to a problem? Please describe.

The current mcp integration appears to expose a single fixed MCP server instance behind one endpoint.

This makes a few use cases difficult or impossible to support cleanly:

1. exposing different tool lists on different MCP routes, for example:
   • /mcp/a -> tool set A
   • /mcp/b -> tool set B
   • /mcp/:tenant -> tenant-specific tool set
2. using official go-sdk server hooks / middleware / options from the go-zero wrapper
3. leveraging official go-sdk runtime registry capabilities such as AddTool, RemoveTools, and the corresponding tools/list_changed flow in a straightforward way

From reading the current implementation, the HTTP handler callback always returns the same underlying SDK server instance, so request/path-based MCP server selection is not currently supported by the wrapper.

---

Describe the solution you'd like

I would like to propose an opt-in, backward-compatible extension for the mcp package.

A possible direction:

1. Keep current behavior unchanged by default

   • NewMcpServer(c) should continue to work exactly as it does today

2. Expose the underlying official SDK server

   • for example via Server() or Unwrap()
   • this would allow users to directly use official go-sdk capabilities such as:
     • runtime AddTool
     • RemoveTools
     • prompts/resources registration
     • receiving/sending middleware
     • server options / hooks

3. Add an optional request-based server selector (or MCP mux)

   • for example, an option that allows selecting the target *sdkmcp.Server from *http.Request
   • this would make it possible to support route-based MCP server collections, such as:
     • one go-zero REST server
     • multiple MCP endpoints
     • each endpoint mapped to a different MCP server instance

4. Prefer hooks/options over breaking API changes

   • if hooks/options are added, they should be opt-in only
   • existing users should not need to change any code

This would make the wrapper more flexible while preserving compatibility.

---

Describe alternatives you've considered

1. Running a separate MCP server for each scenario

   • this can work as a workaround, but it increases operational complexity
   • depending on deployment style, it may require additional processes, separate endpoints, or extra routing/port management
   • it is not ideal when the goal is to expose multiple MCP server variants from a single go-zero service in a structured way

2. Wrapping every official SDK API individually

   • possible, but likely harder to maintain over time as the upstream SDK evolves

3. Intercepting tools/list in a single fixed server

   • possible in theory, but less clean than request-based server selection
   • the core requirement here seems to be routing / server selection rather than only middleware interception

4. Using only one MCP server and registering everything up front

   • this works for simple cases, but does not help when different routes or tenants need different tool sets

---

Additional context

This request is mainly about enabling advanced MCP integration in a backward-compatible way, especially:

• official SDK hooks / middleware exposure
• runtime tool registry changes (AddTool / RemoveTools)
• route-based MCP server selection / MCP server collection

If this direction sounds acceptable to maintainers, I’d be happy to prepare a PR following the preferred API shape and compatibility requirements.

[kevwan]

Thank you for this well-thought-out feature proposal!

The use cases you described (multi-tenant tool sets, route-based server selection, runtime tool registry updates, request metadata propagation) are all valid and important for production MCP integrations.

PR #5519 has been submitted implementing this proposal. It adds:

• NewMcpServerWithOptions(...) with opt-in extension options
• WithServerOptions, WithServerHook, WithServerSelector constructor options
• SDKServer(server) helper to expose the underlying go-sdk server
• RemoveTools(server, ...) for runtime tool list updates
• WithRequestMetadataExtractor(...) for injecting request-scoped metadata into handler contexts
• Context helpers: RequestMetadataFromContext, HeaderFromContext, QueryFromContext, PathFromContext

The existing NewMcpServer(c) API remains unchanged, so this is fully backward-compatible.

Review in progress on that PR.