perf: share one SSL context across MCP calls
Summary
- Every MCP exchange (each
tool.execute(), listing and search) built a newhttpx.AsyncClient, and each one built its own SSL context, loading the whole CA bundle. That took about 7ms per call. - The SDK now builds one context on first use (
httpx.create_ssl_context(), the same factory and defaults httpx uses forverify=True) and passes it to every MCP client and to theGET /accountsclient.
Why, with evidence
Measured against the local MCP mock (tests/mocks/serve.ts), 100 calls of tool.execute({}) after a warm-up:
| median per call | listing | |
|---|---|---|
| main (e403357) | 19.7 to 20.4 ms | 20.5 to 21.2 ms |
| this branch | 11.8 to 13.6 ms | 12.4 to 12.9 ms |
httpx.AsyncClient() takes 7.4 ms to construct by default and 0.03 ms when it is given an existing context (httpx 0.28.1).
I also tried keeping a persistent event loop with pooled clients so that TCP and TLS connections could be reused across calls. It gave the same gain, but the connection trace showed every request still opening a new connection. The mcp client stops reading each SSE response before the closing chunk, so httpcore drops the connection. The gain came entirely from not rebuilding the SSL context, so this PR keeps only that. Reusing connections would also need the mcp client to drain SSE responses, which is out of scope here.
Trade-offs to know about
SSL_CERT_FILE/SSL_CERT_DIRand the CA bundle are read once per process instead of once per call. A CA removed from the bundle at runtime stays trusted until the process restarts, which is how a long-livedhttpx.Clientorrequests.Sessionalready behaves.- httpcore sets ALPN on the context for each connection. Every MCP client here is HTTP/1.1, so it always writes the same value.
How verified
- New test
test_calls_share_one_ssl_contextcountsSSLContext.load_verify_locationsacross account discovery, a listing and two real calls to the mock. It fails on main and passes here with exactly one load. uv run ruff check .,uv run ruff format --check .anduv run ty check stackone_ai examplesall pass.uv run pytest: 872 passed.
Gates (head fb4976c)
| Gate | Result |
|---|---|
| Repo skills | none in repo |
| /forge:forge | ran on 41a8965 (a client pool was built, measured and dropped for this 10-line version); 96d729d made the test exact and cache-clearing; re-run on fb4976c: 2 comment lines, 0 copies |
| Security scan | security-reviewer agent: no finding at confidence 70 or above. Aikido: 31 open issues on main (lockfile CVEs, workflow SAST, one old test-fixture secret), none on lines this PR changes |
| Codex security | 41a8965 (job 7fea0304): one medium trade-off, the CA bundle and SSL_CERT_FILE are read once per process (disclosed above); clean on fb4976c (job 3d0eeb35): CERT_REQUIRED and hostname checks stay on for both clients, proxy env handling unchanged |
| /security-review | ran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK |
| /code-review | medium on 96d729d, 7 candidates. Fixed 2: GET /accounts now uses the shared context too (the test discovers accounts and failed with 2 CA loads before the fix), and the test clears the cache on teardown. Declined 5: reading the CA bundle once per process is the disclosed trade-off, httpcore sets ALPN to the same value on every connection, client reuse was measured with no gain because the MCP client abandons each SSE response, the first-call race costs only duplicate work, and counting CA loads tests the intent directly |
| CI | green on fb4976c: 10 pass, 3 skipped |
| Unresolved review threads | 0 |
Requested by guillaume@stackone.com in Slack (repo audit thread).
š¤ Generated with Claude Code
Summary by cubic
Shares one SSL context across all MCP calls so the CA bundle loads once per process instead of once per call, cutting median tool execution from about 20ms to 12ms.
The new test clears the context cache, then expects exactly one CA bundle load across a listing and two calls; it fails on the old per-call behavior.