design: add design for rate limiting

I added an example for how rate limiting should be implemented using
middleware.

Author: samthanawalla

design/design.md

@@ -472,32 +472,7 @@ server.AddReceivingMiddleware(withLogging)
 
 #### Rate Limiting
 
-Rate limiting can be configured using middleware.
-
-As an example, this code adds a per-session rate limiter using the [golang.org/x/time/rate](https://pkg.go.dev/golang.org/x/time/rate) package.
-
-```go
-// PerSessionRateLimiterMiddleware creates a middleware that applies rate limiting
-// on a per-session basis for receiving requests.
-func PerSessionRateLimiterMiddleware[S Session](limit rate.Limit, burst int) Middleware[S] {
-  var sessionLimiters sync.Map // map[*jsonrpc2.Connection]*rate.Limiter
-
-  return func(h MethodHandler[S]) MethodHandler[S] {
-    return func(ctx context.Context, session S, method string, params Params) (Result, error) {
-      conn := session.getConn()
-
-      limiter, _ := sessionLimiters.LoadOrStore(conn, rate.NewLimiter(limit, burst))
-      rateLimiter := limiter.(*rate.Limiter)
-
-      if !rateLimiter.Allow() {
-        return nil, jsonrpc2.ErrServerOverloaded
-      }
-      return h(ctx, session, method, params)
-    }
-  }
-}
-server.AddReceivingMiddleware(PerSessionRateLimiterMiddleware[*ServerSession](rate.Every(time.Second * 2), Burst: 5))
-```
+Rate limiting can be configured using middleware. Please see [examples/rate-limiting](<https://github.com/modelcontextprotocol/go-sdk/tree/main/examples/rate-limiting>] for an example on how to implement this.
 
 ### Errors
 

examples/rate-limiting/go.mod

@@ -0,0 +1,8 @@
+module github.com/modelcontextprotocol/go-sdk/examples/rate-limiting
+
+go 1.25
+
+require (
+	github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89
+	golang.org/x/time v0.12.0
+)

examples/rate-limiting/go.sum

@@ -0,0 +1,8 @@
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89 h1:kUGBYP25FTv3ZRBhLT4iQvtx4FDl7hPkWe3isYrMxyo=
+github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89/go.mod h1:DcXfbr7yl7e35oMpzHfKw2nUYRjhIGS2uou/6tdsTB0=
+golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
+golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
+golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=

examples/rate-limiting/main.go

@@ -0,0 +1,68 @@
+// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"golang.org/x/time/rate"
+)
+
+// GlobalRateLimiterMiddleware creates a middleware that applies a global rate limit.
+// Every request attempting to pass through will try to acquire a token.
+// If a token cannot be acquired immediately, the request will be rejected.
+func GlobalRateLimiterMiddleware[S mcp.Session](limit rate.Limit, burst int) mcp.Middleware[S] {
+	limiter := rate.NewLimiter(limit, burst)
+
+	return func(next mcp.MethodHandler[S]) mcp.MethodHandler[S] {
+		return func(ctx context.Context, session S, method string, params mcp.Params) (mcp.Result, error) {
+			if !limiter.Allow() {
+				return nil, errors.New("JSON RPC overloaded")
+			}
+			return next(ctx, session, method, params)
+		}
+	}
+}
+
+// PerMethodRateLimiterMiddleware creates a middleware that applies rate limiting
+// on a per-method basis.
+// `methodLimits` maps method names to their specific rate limit configurations.
+// Methods not specified in `methodLimits` will not be rate limited by this middleware.
+func PerMethodRateLimiterMiddleware[S mcp.Session](methodLimits map[string]struct {
+	Limit rate.Limit
+	Burst int
+}) mcp.Middleware[S] {
+	limiters := make(map[string]*rate.Limiter)
+	for method, cfg := range methodLimits {
+		limiters[method] = rate.NewLimiter(cfg.Limit, cfg.Burst)
+	}
+
+	return func(next mcp.MethodHandler[S]) mcp.MethodHandler[S] {
+		return func(ctx context.Context, session S, method string, params mcp.Params) (mcp.Result, error) {
+			if limiter, ok := limiters[method]; ok {
+				if !limiter.Allow() {
+					return nil, errors.New("JSON RPC overloaded")
+				}
+			}
+			return next(ctx, session, method, params)
+		}
+	}
+}
+
+func main() {
+	server := mcp.NewServer("greeter1", "v0.0.1", nil)
+	server.AddReceivingMiddleware(GlobalRateLimiterMiddleware[*mcp.ServerSession](rate.Every(time.Second/5), 10))
+	server.AddReceivingMiddleware(PerMethodRateLimiterMiddleware[*mcp.ServerSession](map[string]struct {
+		Limit rate.Limit
+		Burst int
+	}{
+		"callTool":  {Limit: rate.Every(time.Second), Burst: 5},  // 5 callTool requests/sec
+		"listTools": {Limit: rate.Every(time.Minute), Burst: 20}, // 20 listTools requests/min
+	}))
+	// Run Server logic.
+}