docs: Address CodeRabbit review feedback

- Strengthen dynamic auth test to assert exact token value
- Add thread-safety documentation for AuthorizationProvider
- Improve docstring coverage for MCP server facilitator types

Author: Z-M-Huang

http/facilitator.go

@@ -18,6 +18,11 @@ import (
 
 // AuthorizationProvider is a function that returns an Authorization header value.
 // This is useful for dynamic tokens (e.g., JWT refresh) where the value may change.
+//
+// Thread-safety: The provider function is called on each HTTP request, including
+// during retry attempts. If your provider accesses shared state or performs I/O
+// (e.g., token refresh), ensure it is safe for concurrent use. The FacilitatorClient
+// does not serialize calls to the provider.
 type AuthorizationProvider func() string
 
 // FacilitatorClient is a client for communicating with x402 facilitator services.
@@ -39,6 +44,8 @@ type FacilitatorClient struct {
 }
 
 // setAuthorizationHeader sets the Authorization header on the request if configured.
+// If AuthorizationProvider is set, it is called to get the current token value;
+// otherwise, the static Authorization string is used. This is called per-request.
 func (c *FacilitatorClient) setAuthorizationHeader(req *http.Request) {
 	var authValue string
 	if c.AuthorizationProvider != nil {

http/facilitator_test.go

@@ -128,6 +128,9 @@ func TestFacilitatorClient_Verify_WithAuthorizationProvider(t *testing.T) {
 		return "Bearer dynamic-token-" + string(rune('0'+callCount))
 	}
 
+	// Expected token for the first call
+	expectedAuth := "Bearer dynamic-token-1"
+
 	// Create a mock facilitator server that validates the Authorization header
 	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		authHeader := r.Header.Get("Authorization")
@@ -137,6 +140,13 @@ func TestFacilitatorClient_Verify_WithAuthorizationProvider(t *testing.T) {
 			return
 		}
 
+		// Verify the dynamic token value is used and static is ignored
+		if authHeader != expectedAuth {
+			t.Errorf("Expected Authorization header %q, got %q", expectedAuth, authHeader)
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+
 		response := facilitator.VerifyResponse{
 			IsValid: true,
 			Payer:   "0x857b06519E91e3A54538791bDbb0E22373e36b66",
@@ -174,8 +184,8 @@ func TestFacilitatorClient_Verify_WithAuthorizationProvider(t *testing.T) {
 		t.Fatalf("Verify failed: %v", err)
 	}
 
-	if callCount == 0 {
-		t.Error("Expected AuthorizationProvider to be called")
+	if callCount != 1 {
+		t.Errorf("Expected AuthorizationProvider to be called exactly once, got %d calls", callCount)
 	}
 }
 

mcp/server/facilitator.go

@@ -1,3 +1,5 @@
+// Package server provides MCP server integration for x402 payment gating.
+// It enables payment-gated AI tools via the Model Context Protocol.
 package server
 
 import (
@@ -10,7 +12,9 @@ import (
 	"github.com/mark3labs/x402-go/http"
 )
 
-// Facilitator interface for payment verification and settlement
+// Facilitator defines the interface for payment verification and settlement.
+// Implementations communicate with an x402 facilitator service to verify
+// payment authorizations and execute settlements on the blockchain.
 type Facilitator interface {
 	// Verify verifies a payment without settling it
 	Verify(ctx context.Context, payment *x402.PaymentPayload, requirement x402.PaymentRequirement) (*facilitator.VerifyResponse, error)
@@ -19,12 +23,14 @@ type Facilitator interface {
 	Settle(ctx context.Context, payment *x402.PaymentPayload, requirement x402.PaymentRequirement) (*x402.SettlementResponse, error)
 }
 
-// HTTPFacilitator implements Facilitator using the http.FacilitatorClient
+// HTTPFacilitator implements the Facilitator interface using the http.FacilitatorClient.
+// It communicates with an x402 facilitator service over HTTP to verify and settle payments.
 type HTTPFacilitator struct {
 	client *http.FacilitatorClient
 }
 
-// HTTPFacilitatorOption configures an HTTPFacilitator
+// HTTPFacilitatorOption is a functional option for configuring an HTTPFacilitator.
+// Use WithAuthorization or WithAuthorizationProvider to set authentication.
 type HTTPFacilitatorOption func(*http.FacilitatorClient)
 
 // WithAuthorization sets a static Authorization header value for the facilitator.
@@ -44,7 +50,14 @@ func WithAuthorizationProvider(provider http.AuthorizationProvider) HTTPFacilita
 	}
 }
 
-// NewHTTPFacilitator creates a new HTTP facilitator client
+// NewHTTPFacilitator creates a new HTTP facilitator client with the given URL and options.
+// The facilitator is used to verify and settle payments for payment-gated MCP tools.
+//
+// Example:
+//
+//	facilitator := NewHTTPFacilitator("https://api.x402.coinbase.com",
+//	    WithAuthorization("Bearer my-api-key"),
+//	)
 func NewHTTPFacilitator(facilitatorURL string, opts ...HTTPFacilitatorOption) *HTTPFacilitator {
 	timeouts := x402.DefaultTimeouts
 	client := &http.FacilitatorClient{