Sam Morrow
c2c7edc3f0
perf: add schema caching to avoid repeated reflection (#685)
## Summary
This PR adds schema caching that dramatically reduces the cost of tool
registration in stateless server patterns.
**Contributors:** Thanks to @omgitsads and @almaleksia for collaborating
on and researching this solution!
## Problem
In stateless deployments like `github/github-mcp-server`, a new
`*mcp.Server` is created for each incoming request. This means `AddTool`
is called repeatedly for the same tools, causing:
1. **For typed handlers**: `jsonschema.ForType()` reflection is called
every time
2. **For pre-defined schemas**: `schema.Resolve()` is called every time
## Solution
Add a `schemaCache` that stores:
- Schemas by `reflect.Type` (for auto-generated schemas from typed
handlers)
- Resolved schemas by schema pointer (for pre-defined schemas)
The cache is:
- Concurrent-safe using `sync.Map`
- Unbounded (typical MCP servers have <100 tools)
- Global (lives across server instances)
## Benchmark Results
```
BenchmarkAddToolTypedHandler-22 977080 1223 ns/op 1208 B/op 21 allocs/op
BenchmarkAddToolTypedHandlerNoCache-22 6764 161463 ns/op 39262 B/op 1072 allocs/op
```
| Metric | With Cache | Without Cache | Improvement |
|--------|------------|---------------|-------------|
| Time | 1,223 ns/op | 161,463 ns/op | **132x faster** |
| Allocations | 21 allocs | 1,072 allocs | **51x fewer** |
| Memory | 1,208 B/op | 39,262 B/op | **32x less** |
## Files Changed
- `mcp/schema_cache.go` - New cache implementation
- `mcp/server.go` - Modified `setSchema` to use cache
- `mcp/schema_cache_test.go` - Unit tests for caching behavior
- `mcp/schema_cache_benchmark_test.go` - Benchmarks
## Impact for Integrators
**Automatic** - no code changes required. Integrators using:
- Typed handlers (`AddTool[In, Out]`) → cache by type
- Pre-defined schemas (`Tool{InputSchema: schema}`) → cache by pointer
Both patterns benefit from caching after the first call.
---
## Real-World Performance Validation
The following benchmarks were conducted using `github/github-mcp-server`
(a production MCP server with ~130 tools) to validate the performance
impact in a real-world scenario.
### Test Environment
- **Server:** github-mcp-server (stateless HTTP deployment)
- **Tools registered per request:** ~130 tools
- **Test methodology:** Python benchmark client, 30 iterations
(latency), 100 iterations (stress)
- **Date:** December 4, 2025
### Configurations Tested
| Configuration | Description |
|--------------|-------------|
| **main (mcp-go)** | Original implementation using mcp-go library |
| **go-sdk (no cache)** | go-sdk WITHOUT schema caching (broken) |
| **go-sdk (with cache)** | go-sdk WITH this PR's schema caching fix
|
### Latency Test Results (n=30)
#### Operation: `initialize`
| Configuration | P50 | P99 | Status |
|--------------|-----|-----|--------|
| main (mcp-go) | 11.48ms | 14.00ms | ✅ Baseline |
| go-sdk (no cache) | 20.47ms | 25.30ms | 🔴 **+78% REGRESSION** |
| go-sdk (with cache) | 10.36ms | 14.33ms | ✅ **FIXED (-10%)** |
#### Operation: `tools/list`
| Configuration | P50 | P99 | Status |
|--------------|-----|-----|--------|
| main (mcp-go) | 13.46ms | 22.47ms | ✅ Baseline |
| go-sdk (no cache) | 22.98ms | 29.11ms | 🔴 **+71% REGRESSION** |
| go-sdk (with cache) | 14.15ms | 15.91ms | ✅ **FIXED (+5%)** |
#### Operation: `prompts/list`
| Configuration | P50 | P99 | Status |
|--------------|-----|-----|--------|
| main (mcp-go) | 11.56ms | 13.81ms | ✅ Baseline |
| go-sdk (no cache) | 21.00ms | 26.42ms | 🔴 **+82% REGRESSION** |
| go-sdk (with cache) | 10.77ms | 15.25ms | ✅ **FIXED (-7%)** |
### Stress Test Results (n=100)
| Configuration | P50 (initialize) | P50 (tools/list) | P50
(prompts/list) |
|--------------|------------------|------------------|-------------------|
| main (mcp-go) | 12.06ms | 14.30ms | 11.34ms |
| go-sdk (no cache) | 20.06ms | 23.44ms | 19.59ms |
| go-sdk (with cache) | **11.83ms** | **14.58ms** | **11.05ms** |
### Memory/Allocation Comparison (from pprof)
| Configuration | Total Allocations | Comparison |
|--------------|-------------------|------------|
| main (mcp-go) | 355.91 MB | Baseline |
| go-sdk (no cache) | **1208.70 MB** | 🔴 **3.4x MORE allocations** |
#### Top Allocation Sources - go-sdk WITHOUT cache (broken)
| Function | Size | % | Issue |
|----------|------|---|-------|
| `jsonschema.UnmarshalJSON` | 324.60 MB | 27% | 🚨 Schema re-parsing |
| `encoding/json.Unmarshal` | 341.10 MB | 28% | JSON deserialization |
| `jsonschema.resolve` | 219.51 MB | 18% | 🚨 Schema re-resolution |
| `jsonschema.MarshalJSON` | 92.52 MB | 8% | Schema JSON encoding |
### Root Cause Analysis
The `google/jsonschema-go` library regenerates JSON schemas on every
request instead of caching them. In a server with ~130 tools, this
causes:
- **70-80% latency regression** on all MCP operations
- **3.4x more memory allocations** per request
- **~70% of all allocations** are schema-related operations
### Key Findings
1. ✅ **REGRESSION CONFIRMED:** go-sdk without schema caching is 70-80%
slower than mcp-go
2. ✅ **FIX VERIFIED:** Schema caching restores performance to baseline
(or better)
3. ✅ **MEMORY IMPACT:** 3.4x reduction in allocations with caching
4. ✅ **PRODUCTION READY:** Fixed version performs equivalently to mcp-go
baseline
---------
Co-authored-by: Adam Holt <4619+omgitsads@users.noreply.github.com>
Co-authored-by: Ksenia Bobrova <1885174+almaleksia@users.noreply.github.com>
|
2026-01-20 20:16:46 -05:00 |
| .. |
|
testdata
|
go.mod: upgrade to jsonschema v0.4.2 (#732)
|
2026-01-04 09:18:01 -05:00 |
|
capabilities_go125_test.go
|
mcp: add Capabilities fields to ServerOptions and ClientOptions (#713)
|
2025-12-11 20:17:46 -05:00 |
|
client.go
|
delete the old logger in client (#744)
|
2026-01-05 12:29:40 -05:00 |
|
client_example_test.go
|
mcp: fix goroutine leaks in unit tests (#496)
|
2025-10-16 11:13:30 -04:00 |
|
client_list_test.go
|
mcp: allow any value for schemas (#517)
|
2025-09-26 11:55:54 -04:00 |
|
client_test.go
|
feat: deprecated logger in client & add Logger in ClientOption (#738)
|
2026-01-05 07:41:31 -08:00 |
|
cmd.go
|
mcp: speed up TestCommandTransportDuration
|
2025-09-12 12:00:29 -04:00 |
|
cmd_export_test.go
|
mcp: speed up TestCommandTransportDuration
|
2025-09-12 12:00:29 -04:00 |
|
cmd_test.go
|
mcp: fix goroutine leaks in unit tests (#496)
|
2025-10-16 11:13:30 -04:00 |
|
conformance_go124_test.go
|
internal/mcp: update protocol versions
|
2025-06-18 08:11:16 -07:00 |
|
conformance_go125_test.go
|
internal/mcp: update protocol versions
|
2025-06-18 08:11:16 -07:00 |
|
conformance_test.go
|
mcp: switch icon theme to named string type (#733)
|
2025-12-19 16:44:10 -05:00 |
|
content.go
|
Implement SEP-973 (#570)
|
2025-11-12 16:52:44 -05:00 |
|
content_nil_test.go
|
mcp: add CallToolResult.getError (#481)
|
2025-09-18 08:08:23 -04:00 |
|
content_test.go
|
mcp: switch icon theme to named string type (#733)
|
2025-12-19 16:44:10 -05:00 |
|
elicitation_test.go
|
mcp: add Capabilities fields to ServerOptions and ClientOptions (#713)
|
2025-12-11 20:17:46 -05:00 |
|
error_test.go
|
mcp: add Capabilities fields to ServerOptions and ClientOptions (#713)
|
2025-12-11 20:17:46 -05:00 |
|
event.go
|
mcp: support SSE polling and server disconnects (SEP-1699) (#663)
|
2025-12-01 16:21:37 -05:00 |
|
event_test.go
|
mcp: remove the StreamID type (#490)
|
2025-09-18 12:01:07 -04:00 |
|
features.go
|
mcp: minor cleanup of some TODOs (#332)
|
2025-08-20 12:55:19 -04:00 |
|
features_test.go
|
mcp: change tool handler design (#325)
|
2025-08-20 19:36:34 -04:00 |
|
logging.go
|
mcp/server: enable server logging (#501)
|
2025-10-02 14:44:32 -04:00 |
|
mcp.go
|
mcp: fix inaccurate package doc (#534)
|
2025-09-26 14:16:10 -04:00 |
|
mcp_example_test.go
|
docs: add feature and troubleshooting documentation (#463)
|
2025-09-16 11:13:40 -04:00 |
|
mcp_test.go
|
Export GetError and SetError methods (#753)
|
2026-01-15 11:46:13 -05:00 |
|
prompt.go
|
mcp: align PromptHandler args with other handlers (#348)
|
2025-08-22 10:44:05 -04:00 |
|
protocol.go
|
Export GetError and SetError methods (#753)
|
2026-01-15 11:46:13 -05:00 |
|
protocol_test.go
|
mcp: add CallToolResult.getError (#481)
|
2025-09-18 08:08:23 -04:00 |
|
requests.go
|
mcp: support url mode elicitation (#646)
|
2025-11-23 12:58:28 -05:00 |
|
resource.go
|
all: expose JSON-RPC error codes, and support URLElicitationRequired errors (#655)
|
2025-12-01 11:29:17 -05:00 |
|
resource_go124.go
|
internal/mcp: add the FileResourceHandler method
|
2025-05-19 11:15:23 -07:00 |
|
resource_pre_go124.go
|
internal/mcp: add the FileResourceHandler method
|
2025-05-19 11:15:23 -07:00 |
|
resource_test.go
|
mcp/Resource: Refactor URI Template Matching with uritemplate Library (#100)
|
2025-07-08 15:52:54 -04:00 |
|
schema_cache.go
|
perf: add schema caching to avoid repeated reflection (#685)
|
2026-01-20 20:16:46 -05:00 |
|
schema_cache_test.go
|
perf: add schema caching to avoid repeated reflection (#685)
|
2026-01-20 20:16:46 -05:00 |
|
server.go
|
perf: add schema caching to avoid repeated reflection (#685)
|
2026-01-20 20:16:46 -05:00 |
|
server_example_test.go
|
doc: document logging (#497)
|
2025-09-19 11:58:58 -04:00 |
|
server_test.go
|
perf: add schema caching to avoid repeated reflection (#685)
|
2026-01-20 20:16:46 -05:00 |
|
session.go
|
mcp: support stateless streamable sessions (#277)
|
2025-08-11 16:43:46 -04:00 |
|
shared.go
|
mcp: use args struct for CloseSSEStream (#718)
|
2025-12-11 15:13:38 -05:00 |
|
shared_test.go
|
all: remove ServerRequest[T] for concrete T (#342)
|
2025-08-21 12:10:53 -04:00 |
|
sse.go
|
mcp: fix SSEClientTransport to report HTTP errors properly (#740)
|
2025-12-31 08:16:20 -08:00 |
|
sse_example_test.go
|
SSE: Add support for SSE handler options (#508)
|
2025-09-19 13:01:57 -04:00 |
|
sse_test.go
|
mcp: fix SSEClientTransport to report HTTP errors properly (#740)
|
2025-12-31 08:16:20 -08:00 |
|
streamable.go
|
mcp: add DisableListening option to StreamableClientTransport (#729)
|
2026-01-11 07:56:47 -05:00 |
|
streamable_bench_test.go
|
mcp: don't persist failed streamable sessions (#605)
|
2025-10-27 16:29:16 -04:00 |
|
streamable_client.go
|
mcp: clarify documentation for the streamable transports
|
2025-12-10 10:46:10 -05:00 |
|
streamable_client_test.go
|
mcp: add DisableListening option to StreamableClientTransport (#729)
|
2026-01-11 07:56:47 -05:00 |
|
streamable_example_test.go
|
mcp: fix goroutine leaks in unit tests (#496)
|
2025-10-16 11:13:30 -04:00 |
|
streamable_server.go
|
mcp: simplify stream state management in streamable transport
|
2025-12-10 13:28:25 -05:00 |
|
streamable_test.go
|
mcp: use args struct for CloseSSEStream (#718)
|
2025-12-11 15:13:38 -05:00 |
|
tool.go
|
mcp: validate tool names (#640)
|
2025-11-19 17:01:50 -05:00 |
|
tool_example_test.go
|
mcp: allow any value for schemas (#517)
|
2025-09-26 11:55:54 -04:00 |
|
tool_test.go
|
all: expose JSON-RPC error codes, and support URLElicitationRequired errors (#655)
|
2025-12-01 11:29:17 -05:00 |
|
transport.go
|
mcp: better handling for streamable context cancellation (#677)
|
2025-12-03 12:26:50 -05:00 |
|
transport_example_test.go
|
mcp: fix broken client root capabilities (#698)
|
2025-12-11 10:16:56 -05:00 |
|
transport_test.go
|
fix: handle Windows CRLF in MCP client(#664) (#665)
|
2025-12-01 12:16:39 -05:00 |
|
util.go
|
mcp: allow any value for schemas (#517)
|
2025-09-26 11:55:54 -04:00 |