Architecture & Operational Behavior

How the Context7 MCP server and REST API behave on the network — endpoints, timeouts, streams, and argument names

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-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:

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 searchFilterApplied flag 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.