MCP gateway: add per-tool scopes, tracing, rate limiting, and audit logging (#2850)

* Initial plan

* Add MCP per-tool scopes, tracing, rate limiting, and audit logging

- Add Scopes field to Tool struct for per-tool scope requirements
- Add Auth (auth.Auth) integration to Options for token inspection
- Add trace ID generation (UUID) propagated via metadata to downstream RPCs
- Add per-tool rate limiting with configurable requests/sec and burst
- Add AuditFunc callback for immutable tool-call audit records
- Extract tool scopes from registry endpoint metadata ("scopes" key)
- Update both HTTP and stdio transports with auth/trace/rate/audit
- Add comprehensive tests for all new functionality

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* Revert unrelated example go.mod changes

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* Remove auto-generated example go.sum files

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* Add WithEndpointScopes helper, gateway-level ToolScopes, and documentation

- Add server.WithEndpointScopes() for declaring per-endpoint auth scopes at
  handler registration time
- Add mcp.Options.ToolScopes for gateway-level scope overrides without
  changing individual services
- Update documented example to show WithEndpointScopes usage
- Update examples/mcp/README.md with scopes, tracing, and rate-limiting docs
- Update gateway/mcp/DOCUMENTATION.md with scopes section and FAQ
- Add tests for both new features

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* Fix ToolScopes doc comment: clarify override (not merge) semantics

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* Revert unrelated example go.mod/go.sum changes

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* Rename ToolScopes to Scopes in MCP Options

The field name "Scopes" is more universal and consistent with how
auth scopes are used throughout go-micro. Updated all code references,
tests, and documentation.

Co-authored-by: asim <17530+asim@users.noreply.github.com>

* MCP gateway: add per-tool scopes, tracing, rate limiting, and audit logging

Co-authored-by: asim <17530+asim@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: asim <17530+asim@users.noreply.github.com>

examples/mcp/README.md

@@ -26,6 +26,7 @@ Complete example showing all MCP features with a user service.
 **What it shows:**
 - Multiple endpoints (GetUser, CreateUser)
 - Rich documentation with examples
+- Per-endpoint auth scopes via `server.WithEndpointScopes()`
 - Pre-populated test data
 - Production-ready patterns
 
@@ -139,6 +140,51 @@ micro mcp test <tool-name>   # Test a tool
 - No code generation
 - Just write normal Go code!
 
+### ✅ Per-Tool Auth Scopes
+
+Declare required scopes when registering a handler:
+
+```go
+handler := service.Server().NewHandler(
+    new(BlogService),
+    server.WithEndpointScopes("Blog.Create", "blog:write"),
+    server.WithEndpointScopes("Blog.Delete", "blog:admin"),
+)
+```
+
+Or define scopes at the gateway layer without changing services:
+
+```go
+mcp.Serve(mcp.Options{
+    Registry: reg,
+    Auth:     authProvider,
+    Scopes: map[string][]string{
+        "blog.Blog.Create": {"blog:write"},
+        "blog.Blog.Delete": {"blog:admin"},
+    },
+})
+```
+
+### ✅ Tracing, Rate Limiting & Audit Logging
+
+Every tool call generates a trace ID that propagates through the RPC chain.
+Configure rate limiting and audit logging at the gateway:
+
+```go
+mcp.Serve(mcp.Options{
+    Registry: reg,
+    Auth:     authProvider,
+    RateLimit: &mcp.RateLimitConfig{
+        RequestsPerSecond: 10,
+        Burst:             20,
+    },
+    AuditFunc: func(r mcp.AuditRecord) {
+        log.Printf("[audit] trace=%s tool=%s account=%s allowed=%v",
+            r.TraceID, r.Tool, r.AccountID, r.Allowed)
+    },
+})
+```
+
 ## Documentation
 
 - [Full MCP Documentation](../../internal/website/docs/mcp.md)

examples/mcp/documented/main.go

@@ -12,6 +12,7 @@ import (
 
 	"go-micro.dev/v5"
 	"go-micro.dev/v5/gateway/mcp"
+	"go-micro.dev/v5/server"
 )
 
 // User represents a user in the system
@@ -114,9 +115,13 @@ func main() {
 		},
 	}
 
-	// Register handler - documentation is automatically extracted from method comments
-	// You can also use server.WithEndpointDocs() to manually provide documentation
-	handler := service.Server().NewHandler(usersService)
+	// Register handler - documentation is automatically extracted from method comments.
+	// Use WithEndpointScopes to declare required auth scopes per endpoint.
+	handler := service.Server().NewHandler(
+		usersService,
+		server.WithEndpointScopes("Users.GetUser", "users:read"),
+		server.WithEndpointScopes("Users.CreateUser", "users:write"),
+	)
 
 	if err := service.Server().Handle(handler); err != nil {
 		log.Fatal(err)