Your agent needs up-to-date library documentation, and you have picked Context7 to supply it. Context7 ships two ways in: an official hosted MCP server at a single endpoint, and a REST API your pipeline can call directly. They read from the same documentation index, but they are not the same object. They expose different surfaces, put you on slightly different auth paths, and hand you different work to own in production. Here is how to pick.
Context7 is Upstash's documentation-retrieval platform: it fetches version-specific docs and code snippets straight from the source and injects them into an LLM's context. The MCP server code is open source under the MIT license; the backend, parsing, and crawling engines are proprietary. Two access paths sit on top of that index.
The official Context7 MCP server is hosted at https://mcp.context7.com/mcp over Streamable HTTP, with an SSE variant and a local npx @upstash/context7-mcp option. It exposes exactly two tools: resolve-library-id, which maps a library name to a Context7 ID, and query-docs, which returns version-specific documentation for that ID. Authentication is an API key passed as an Authorization: Bearer header, and the remote server also supports OAuth 2.0 for MCP clients. See the official Context7 repository for the tool contract and client setup.
The Context7 API is a REST interface rooted at https://context7.com/api/v2/. GET /libs/search mirrors library resolution and GET /context mirrors document retrieval, so the read core matches the MCP server. Beyond that, the API exposes what the MCP server does not: POST /add/* endpoints for GitHub, GitLab, Bitbucket, OpenAPI specs, websites, llms.txt, Confluence, and Notion, plus refresh, usage metrics, and teamspace policy endpoints. Auth is the same ctx7sk- key as a Bearer token. The full surface is in the Context7 API guide.
The two paths overlap on retrieval and diverge on everything operational. For a coding agent that only needs current docs, they are close to interchangeable. For a pipeline that curates its own documentation index, they are not.
The MCP server is the retrieval slice; the API is retrieval plus library management. The table below maps the actions that matter for agent use cases.
The gap is not about retrieval quality; both paths hit the same index. It is about ownership of the index. Anything that curates documentation, adding a private repo, submitting an OpenAPI spec, refreshing a stale library, or reading usage metrics, lives only in the API. An agent built on the MCP server can read the world's docs but cannot add your own. That is a design boundary, not a tool that ships next month.
Here Context7 breaks the usual pattern. Both the MCP server and the API authenticate with the same key: a ctx7sk- secret from the Context7 dashboard, sent as Authorization: Bearer. There is no bot-versus-user token split to reason about.
The one divergence is OAuth. The remote MCP server supports OAuth 2.0 following the MCP OAuth specification, which lets an interactive client have the end user sign in rather than paste a key. The API is key-only. Without any key, requests fall into a low, shared anonymous rate-limit pool; a key grants dedicated quota by plan. For agents, the practical takeaway is simple: whichever path you choose, a ctx7sk- key is the credential you have to protect.
On the MCP path, Upstash hosts the server, maintains the two tool schemas, and owns the crawl and index. You own key custody, rate-limit handling, and caching. On the API path, you own the resolve-then-context two-step, request construction, error handling, and the LLM tool schemas if an agent calls it.
Both paths return 429 with Retry-After and RateLimit-* headers, so exponential backoff is your job either way, and the docs recommend caching responses for hours since documentation changes infrequently. Watch the maintenance trajectory too: the MCP tool set has already been renamed across versions, so pin the package and re-discover tools; the API is versioned at v2 and the old api.context7.com host has been retired. Agent tool observability and rate-limit backoff patterns go hand in hand when running tools reliably in production.
Both lists below are specific to Context7, not generic MCP advice. Match the path to what your agent is actually doing.
Use Context7 MCP when:
Use the Context7 API when:
Scalekit ships a single Context7 connector, and it resolves the part both direct paths leave to you: where the ctx7sk- key lives and who is allowed to call which tool. The Context7 MCP connector docs cover the full setup; the shape is below.
The connector is named context7mcp, authenticates with the Context7 API key, and exposes the two retrieval tools as context7mcp_resolve_library_id and context7mcp_query_docs. Because Context7 uses an API key rather than OAuth, you register the key once per identifier instead of running a browser consent flow. The credential is held in Scalekit's token vault and injected server side; it never reaches your agent runtime or the model context.
A connected account links a user identifier in your system to a Context7 key. Create it once, from your own authenticated backend, using the Scalekit Python SDK.
Before the code, be precise about what happens. The agent does not load a Context7 catalog. actions.langchain.get_tools calls list_scoped_tools under the hood for one identifier and returns only the tools that identifier's connected account is authorized to call, each already bound to that identifier. You choose the surface; for a pure documentation agent, the two retrieval tools are the whole set.
Execution runs inside the agent loop: the model decides which tool to call, the adapter executes it with the bound identifier through Scalekit, and the Context7 key never enters the exchange. The same connected-account pattern works with the Claude SDK, CrewAI, Google ADK, and Mastra.
Context7 alone is only two tools, so this is not a tool-bloat story on its own. It becomes one the moment Context7 sits inside a multi-tool agent, next to GitHub, Slack, or Jira surfaces, where the aggregate tool count climbs. A pure retrieval agent can be scoped to context7mcp_query_docs alone, cutting the decision space to one tool. Surface reduction is the lever for tool-calling accuracy here; model upgrades help, but they are not the lever. For index management endpoints the connector does not wrap, you still call the Context7 API directly, with the same vaulted key.
Both direct paths hand you a ctx7sk- key and stop there. Neither gives you a vault, per-caller attribution, or a revocation flow. Context7 is a shared service, so the failure mode is not the usual per-user OAuth sprawl; it is quieter and easier to ship by accident.
Drop one key into the agent runtime and it works in a demo. In production, that key ends up in environment dumps and logs, every caller draws down one shared rate-limit budget so a single runaway agent can 429 the whole product, and there is no way to attribute a call back to the user who triggered it. Rotating the key to cut off one bad actor rotates it for everyone.
The picture changes for teams on Context7 plans that index private repositories or set teamspace policies. Now each tenant has its own ctx7sk- key, and you are back to the N-credential problem: N keys to store, attribute, and revoke independently. The token type never changed; the number of them did. This is the same multi-tenant credential problem explored in depth in how tool calling auth changes when you move from single-tenant to multi-tenant.
Scalekit's Context7 connector holds each key in the token vault, resolves the right one per identifier at call time, and never exposes it to agent code. Every execute_tool call is recorded with the identifier, the connected account, and an execution ID, so agent tool observability and downstream auth logs answer "what did this agent do for this user" as one query. For multi-tool and multi-tenant agents, Virtual MCP Servers expose only the Context7 tools you allow and mint a short-lived, per-user session token before each run, with no MCP server to deploy, host, or maintain.
If your agent is an interactive coding assistant that just needs current docs, the MCP server is the faster route: two tools, hosted, LLM-ready, with OAuth available for end users. If your agent curates a documentation index, adding private sources, refreshing them, reading metrics, build against the API, because those actions live nowhere else.
The credential question is the same regardless of which you pick. One ctx7sk- key protects the whole path, and whether you run one shared key or one per tenant, custody, attribution, and revocation are infrastructure you own. That is the part worth solving once, so the MCP-vs-API decision never touches your auth layer again. Understanding credential ownership across agent tool-calling patterns is the first step to getting this right.
Read the Context7 MCP connector docs or the Scalekit Context7 connector page to wire it up, and browse the full connector catalog to bundle Context7 with the rest of your agent's tools. If you are building a developer-facing agent, the DevOps assistant agent template is a working starting point, and pricing is usage-based with a free tier to start.
Building a Context7 agent and want a second pair of eyes on the auth model? Join the Scalekit Slack community, or use the talk to us page for immediate help.
