# 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](/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](/api-guide#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](/library-updates) for how documentation staleness and refresh scheduling work.