perf: share one SSL context across MCP calls

Merged
GL
9d ago
+37-3

Summary

  • Every MCP exchange (each tool.execute(), listing and search) built a new httpx.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 for verify=True) and passes it to every MCP client and to the GET /accounts client.

Why, with evidence

Measured against the local MCP mock (tests/mocks/serve.ts), 100 calls of tool.execute({}) after a warm-up:

median per calllisting
main (e403357)19.7 to 20.4 ms20.5 to 21.2 ms
this branch11.8 to 13.6 ms12.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_DIR and 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-lived httpx.Client or requests.Session already 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_context counts SSLContext.load_verify_locations across 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 . and uv run ty check stackone_ai examples all pass. uv run pytest: 872 passed.

Gates (head fb4976c)

GateResult
Repo skillsnone in repo
/forge:forgeran 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 scansecurity-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 security41a8965 (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-reviewran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK
/code-reviewmedium 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
CIgreen on fb4976c: 10 pass, 3 skipped
Unresolved review threads0

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.