experimental-ext-interceptors/go/sdk/doc/PERFORMANCE.md

Go SDK Interceptors — Performance

Analysis of per-request costs and allocation patterns.

---

Design Rationale: JSON-RPC Invocation

The interceptor chain follows the SEP execution model: each interceptor is invoked via interceptor/invoke JSON-RPC calls through an MCP client session. For in-process interceptors, Server.LocalChain() creates an in-memory transport, so the JSON-RPC overhead is minimal (no network I/O).

Payloads are json.RawMessage at the protocol level. The middleware marshals request params and response results once per phase, and interceptor handlers unmarshal the specific fields they need.

---

Per-Request Cost Model

Every intercepted request passes through gomiddleware.Middleware. The cost depends on whether interceptors match the event.

Fast Path (skipped methods)

The middleware skips initialize, notifications/*, interceptors/list, and interceptor/invoke with a map lookup. Zero allocations, zero JSON operations.

Intercepted Path

With interceptors active, each active phase incurs:

Step	Operation	Allocations	JSON ops
1	Marshal request params / response result	1 json.RawMessage	1 marshal
2	ChainExecutionResult struct (with pre-allocated Results slice)	1 struct + 1 slice	0
3	Per-interceptor interceptor/invoke RPC	1 InvokeParams + 1 InvokeResult per interceptor	1 marshal + 1 unmarshal per interceptor (handled by go-sdk JSON-RPC layer)
4	Validator execution (N=1 inline, N>1 goroutines)	0 (N=1) / goroutines (N>1)	Handler-specific
5	Mutator payload threading	0	Payload passed as json.RawMessage between mutators
6	Unmarshal mutated payload back to params/result	0	1 unmarshal (if mutated)

In-Memory Transport Overhead

When using LocalChain(), the in-memory transport uses newline-delimited JSON over a net.Pipe(). Each interceptor/invoke call involves:

1. JSON marshal of InvokeParams (client side)
2. Write to pipe
3. JSON unmarshal of InvokeParams (server side)
4. Handler execution
5. JSON marshal of InvokeResult (server side)
6. Write to pipe
7. JSON unmarshal of InvokeResult (client side)

The JSON-RPC overhead is bounded by the payload size and is negligible for typical MCP payloads. The in-memory pipe avoids network I/O entirely.

Audit Mode

Audit-mode mutators run normally but their mutated payload is not propagated to subsequent interceptors. No deep-copy is needed — the chain simply skips updating FinalPayload for audit-mode entries.

---

Optimization Opportunities

1. Batch invoke: A future interceptor/invokeValidators method could reduce round-trips for validators that run in parallel.
2. Payload caching: For validators that don't need the full payload, a lightweight invoke variant could skip payload serialization.
3. Connection pooling: For remote interceptor servers, reusing client sessions across requests avoids connection setup overhead.