Skip to main content
This page describes the network behavior of the hosted Context7 MCP server and REST API, so you can reason about timeouts, error handling, and client configuration without reading source code.

​
Endpoints

The MCP endpoint serves POST and GET requests and rejects session-style GET/DELETE operations with 405. Everything else returns a JSON 404. OAuth discovery metadata is available at /.well-known/oauth-protected-resource (RFC 9728).

​
Stateless HTTP serving

The hosted HTTP server serves each MCP request with a fresh server instance: there is no Mcp-Session-Id, no session store, and no Redis-backed state. The 2025-era legacy clients are answered through a stateless fallback. This means the server holds no per-session state between requests.

​
API call timeout

Every call the MCP server makes to the Context7 API (both library search and context fetch) applies a 60-second timeout via AbortSignal.timeout(). These are vector queries with a p99.9 of ~3.2 seconds and no observed request exceeding 30 seconds, so 60s is generous; a stalled backend call fails at 60s instead of riding the fetch default.

​
SSE heartbeats

HTTP serving disables SSE keepalive heartbeats (keepAliveMs: 0). Tools are millisecond vector queries, so no legitimate exchange needs a heartbeat to stay alive. A hung exchange therefore goes silent and is reaped by the gateway’s stream idle timeout rather than being kept alive until the gateway’s hard cap.

​
Transport differences

  • stdio — authenticates with --api-key or CONTEXT7_API_KEY; --port is not allowed.
  • http — --api-key is not allowed; authenticate with an HTTP header instead (Authorization: Bearer ..., or the X-Context7-API-Key / X-API-Key variants). --port selects the listen port; the server tries successive ports when one is in use.

​
Tool argument aliasing

On tools/call, the server rewrites hallucinated argument names to their canonical names before validation, so clients that echo tool-description phrasing still work: libraryName is only rewritten on query-docs calls, since it is the canonical argument for resolve-library-id. The schemas published via tools/list are unchanged — canonical names remain the documented required fields.

​
Downtime and error handling

Transient failures surface as HTTP status codes (503 when the gateway connection pool overflows, 5xx otherwise). Retry with backoff; see the API Guide error handling for the full status-code table. Hung exchanges (for example, a batch that carries its own notifications/cancelled) receive no response by spec; with heartbeats disabled they go idle and are reaped by the gateway instead of leaking an upstream connection.

​
Query behavior

  • Keep each query to a single concept — separate queries give better results than one combined query.
  • resolve-library-id and query-docs each allow at most 3 calls per question.
  • Search results may be filtered by your teamspace’s public library access settings; the API reports this via the searchFilterApplied flag.
  • See Keeping Libraries Fresh for how documentation staleness and refresh scheduling work.