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#
| Service | URL |
|---|---|
| Hosted MCP server | https://mcp.context7.com/mcp |
| MCP OAuth endpoint | https://mcp.context7.com/mcp/oauth |
| REST API (v2) | https://context7.com/api/v2/... |
| Health check | GET https://mcp.context7.com/ping |
Send MCP requests to the MCP endpoint with POST. The server does not maintain
persistent HTTP sessions; legacy session GET and DELETE operations receive
405. Unknown routes return 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#
The MCP server applies a 60-second timeout to each library search and context request it sends to the Context7 API. A stalled API request fails when that timeout expires. Your client or network proxy may apply a shorter timeout.
SSE heartbeats#
The HTTP server does not send SSE keepalive heartbeats. An exchange with no response can therefore reach a network proxy's idle timeout. The MCP server also disables notification subscriptions for tool, prompt, and resource lists, which do not change while the server is running.
Transport differences#
- stdio — authenticates with
--api-keyorCONTEXT7_API_KEY;--portis not allowed. - http —
--api-keyis not allowed; authenticate with an HTTP header instead (Authorization: Bearer ..., or theX-Context7-API-Key/X-API-Keyvariants).--portselects 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:
| Tool | Canonical argument | Accepted aliases |
|---|---|---|
resolve-library-id | query | userQuery, question |
query-docs | query | userQuery, question |
query-docs | libraryId | context7CompatibleLibraryID, libraryID, libraryName |
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#
Temporary service or gateway failures can return 5xx HTTP responses. Retry
with backoff and a limit on retry attempts. See API Guide error handling
for API error codes and retry guidance.
Query behavior#
- Use a separate query for each topic, unless the question is about how the topics interact.
- Tool descriptions instruct agents to call each tool no more than 3 times per question. This is agent guidance, not a server-enforced per-question counter. Account and request rate limits apply separately.
- The
searchFilterAppliedflag reports active source-access or library-filter settings for your teamspace. It does not indicate whether any results were excluded. - See Keeping Libraries Fresh for how documentation staleness and refresh scheduling work.