Head to head · Documentation lookup · October 2026 research run
Context7 vs Ref
Context7 scores 74.4 (BB) on agent readiness against Ref's 51.7 (D), and leads in 6 of 7 scored categories. Both do documentation lookup.
Best code, repository and documentation tools for AI agents · All 70 code comparisons
Which one, for what
Context7 BB
Best for Coding agents that need current library or framework docs and examples on demand, at little or no cost.
Ahead on
- Reliability, 68 against 15
- Schema & documentation, 86 against 68
- Agent ergonomics, 75 against 67
- Security & auth, 69 against 63
- Payments & pricing, 90 against 53
- Maintenance & community, 95 against 35
Also in its favour
- Agent-ready, a grade of BB or better
- Open source
Watch for
The resolve-library-id description runs to 2,006 characters and includes reply-formatting instructions for the model
Ref D
Best for Coding agents that need current library documentation plus search over a team's private repositories and PDFs through two small tools.
Also in its favour
- No incidents deducted, where Context7 loses 3 points for them
Watch for
No npm release since 3.0.3 on 4 November 2025
Why the edge
Each category where one leads by five points or more, with the reason behind each side's score from its assessment. The numbers are in the table below; this is what they stand for.
Maintenance & community Context7 +60
Context7 95
@upstash/context7-mcp 4.4.4 on 19 October 2026, and ctx7 0.8.2 and @upstash/context7-sdk 0.6.0 on 23 October (30). Twenty MCP releases between 7 August and 19 October, from 4.0.0 to 4.4.4 (20). 28 open issues and pull requests merging most days, per the 1 October check, not re-read on 1 November as GitHub's pages weren't reachable. Commits land most days in the repository, the latest on 30 October (20). Listed in the official MCP registry as io.github.upstash/context7, latest 4.4.4 published 19 October (15). Dependabot, a test workflow on every push and pull request, and current dependencies (MCP server SDK 2.3.1 since 4.4.3) (10). 30 + 20 + 20 + 15 + 10 = 95.
Ref 35
No dated release or API change of Ref Context is readable within 180 days. The ref-tools-mcp package was last published on 4 November 2025 (3.0.3, the version-bump commit is dated the same day in the repository), 365 days before this check. The 31 July and 30 September 2026 updates were read on 8 October from mailchi.mp, whose robots.txt now disallows every crawler, so they're struck; the docs changelog index gives months only, and both covered Ref Plans. The repository's last commits, on 28 September 2026, are dependency updates, which can't set recency (0 of 30). No releases or dated entries in the 90 days from 6 August (0). Per the 8 October reading of GitHub's API, closed issues show two to five comments each and September's open pull requests one comment each, and the docs promise a reply within one business day (15). The official MCP registry lists tools.ref/ref-tools-mcp under Ref's own domain, at 3.0.1 from 28 October 2025, still on 4 November (15). Dependabot alerts were cleared on 28 September 2026. The only workflow builds a bundle on release, with no tests (5). 0+0+15+15+5 = 35.
Reliability Context7 +53
Context7 68
Scored as a hosted MCP server. Upstash runs an Atlassian Statuspage at status.upstash.com with Context7 and Context7 Console components (20). Its history lists no Context7 incident from July to 1 November 2026 (the newest entry is still a four-minute Upstash proxy degradation in us-east-1 on 29 September), but Context7's own changelog for 4.0.1 and 4.0.2 describes "the 2026-08-11 mcp.context7.com outage", where 4.0.0 pushed concurrent upstream streams from about 10 to over 5,000 and the gateway returned 503 reset reason: overflow. That is inside the 90 days from 3 August, so one major outage on the vendor's own word (10). Monthly quotas are published (1,000 calls free, 2,000 per Pro seat) but the anonymous limit is still only described as low (8). 429 responses carry Retry-After and RateLimit-* headers, with backoff guidance and a status-code table in the API guide (15). The Enterprise plan lists dedicated support with an SLA but its terms aren't published, so half credit (5). The hosted endpoint is generally available (10). 20 + 10 + 8 + 15 + 5 + 10 = 68.
Ref 15
Scored as a hosted MCP server. ref.tools and docs.ref.tools are paused for this run pending a ruling on Ref's terms, so their readings are per the 8 October check, not re-read on 4 November. ref.tools/status is a single-page application. Its eight components, 30-day bars and four incidents were read on 8 October only from the script file the page loads, which this run doesn't count (script bundles are barred), so the page's contents are unread (0 of 20) and no incident history is readable (5). No rate limit is documented. The 8 October reading of a ratelimit-policy header came from a request to Ref's API, which this run doesn't count as evidence, and credit allowances aren't rate limits (0). No 429 or retry guidance was found in the reviewed documentation (0). No SLA found (0). The hosted endpoint is generally available (10). 0+5+0+0+0+10 = 15.
Payments & pricing Context7 +37
Context7 90
No x402, MPP or L402 (0). Overage is $5 per 1,000 calls on a public page, unchanged on 1 November (20). Free plan of 1,000 calls a month with no card, and anonymous calls work without any account (20). An agent can call the hosted endpoint with no key at all. We initialised a session (serverInfo 4.4.3), listed tools and called resolve-library-id anonymously on 1 November. Since 4.2.0 the server's default for HTTP is to require a credential and the client setup pages no longer describe anonymous use, so this route may close, but it still worked (20). 0 + 20 + 20 + 20 = 60. Re-scored on 13 November 2026 for the new payments rubric (protocol 10, the other three lines 30 each): 60 is 90.
Ref 53
Per the 8 October check, not re-read on 4 November (ref.tools and docs.ref.tools are paused for this run pending a ruling on Ref's terms). No x402, MPP or L402 (0). One credit per tool call and $10 per 1,000 extra credits are published without a login (20). The free plan is 200 one-time credits that never expire, not a recurring allowance, and the docs don't say whether sign-up needs a card (15). A person has to sign up in a browser to get a key (0). Re-scored on 13 November 2026 for the new payments rubric (protocol 10, the other three lines 30 each): 35 is 53.
Schema & documentation Context7 +18
Context7 86
Both tools take typed JSON Schema inputs built with Zod (25). context7.com/llms.txt and a docs index for LLMs exist, and docs/openapi.json is public (10). The server instructions say when to use it and when not to, and 4.4.4 (19 October) narrowed the "Do not use for" line so agents use it when porting code between libraries. query-docs says what comes first. The resolve-library-id description is still 2,006 characters in the hosted tools/list on 1 November, and a third of it tells the model how to format its own reply, which isn't tool guidance (14). Inputs are required strings with no enums or bounds, plus an optional free-text language on query-docs, though the parameter descriptions give id formats (9). Good and bad query examples sit in the parameter text, and the API guide tables every status code with what to do (13). Semver releases with a changesets CHANGELOG that explains each change (15). 25 + 10 + 14 + 9 + 13 + 15 = 86.
Ref 68
Both tools have typed JSON Schema inputs in the open-source server (25). docs.ref.tools/llms.txt, llms-full.txt and a Markdown copy of every docs page exist (10). The descriptions say what each tool does and that a read takes the exact URL from a search, with nothing on when not to use them (12). Each tool takes one required string with no enums or bounds, and private search is switched on by writing ref_src=private inside the query text (7). The README shows two worked search-and-read sequences with token counts. No error responses are documented (6). The npm package follows semver, but the repository has no changelog file and no GitHub releases, and product changes appear only in monthly newsletters listed on the docs changelog page (per the 8 October check), whose copies on mailchi.mp now disallow every crawler (8).
Agent ergonomics Context7 +8
Context7 75
Two tools. The hosted tools/list response on 1 November came to 5,262 characters of JSON, most of it one description, plus the server instructions sent at initialisation. Since 4.4.3 the list answers carry a one-hour cache lifetime on the 2026-07-28 protocol (20 of 25). Version 2.0.0 removed page, limit and the token budget, so there's no output-size control beyond writing a narrow query. The language argument ranks examples and doesn't bound size (5). Errors are readable and say what to do (a 429 names the dashboard or plans page, a 404 says to re-run resolve-library-id, a 401 names the ctx7sk key prefix). query-docs sets isError on failure since 4.2.1, and since 4.4.3 (19 October) resolve-library-id does too when the search fails, while a search with no matches stays a normal result (20). Both tools carry readOnlyHint: true, destructiveHint: false and idempotentHint: true, read from the hosted endpoint on 1 November (20). Two required parameters per tool and one optional. A server-side shim rewrites common hallucinated argument names. The SDK is TypeScript only, plus a REST API (10). 20 + 5 + 20 + 20 + 10 = 75.
Ref 67
Two tools whose definitions and server instructions total under 1,000 characters (25). There are no size or paging parameters. The README says a session never returns the same search result twice and a read returns the most relevant sections, about 5,000 tokens at most (12). In the open-source server, failures come back as ordinary text without isError, and any 401 from the API becomes a message to verify an email address. No error list is documented, and the hosted server's code is closed (6). Both tools carry readOnlyHint: true, with no destructiveHint or idempotentHint. Both only read, so retries are safe (16). One required parameter per tool. No SDK was found (8).
Security & auth Context7 +6
Context7 69
API keys with the ctx7sk prefix, hashed at rest and rotatable from the dashboard, and OAuth at /mcp/oauth backed by Clerk, plus enterprise-managed auth. The hosted transport checks OAuth access tokens strictly (signature, issuer, type, expiry and audience) and verifies Entra token signatures. No per-key scopes on the documentation server. A separate Admin MCP (admin.mcp.context7.com) needs a key with management access turned on, per its README (22). Every documentation tool is read-only, so there's nothing destructive to confirm. Enterprise can restrict which libraries and source types a team can reach (15). Indexed documentation is third-party content. Context7 documents a two-pass prompt-injection and malware classifier on indexed content, which we can't test (12). Usage shows in the dashboard, and on-premise Enterprise adds an access audit log (8). SECURITY.md with private reporting and a 48-hour acknowledgement target, SOC 2 Type II through Upstash, no bug bounty found, no published advisories, and the supported-versions table still lists only 1.0.x while 4.4.4 ships, re-read in the clone on 1 November (12). 22 + 15 + 12 + 8 + 12 = 69.
Ref 63
Per the 8 October check, not re-read on 4 November. OAuth through Scalekit with two scopes, public_docs:read and private_docs:read, or an API key. Key rotation and revocation aren't described in the docs (26). Less 10 because the install docs give ?apiKey=YOUR_API_KEY in the URL as a documented option (16). Both tools are read-only, the scopes separate public from private search, and team roles limit who can add to the index (16). ref_read_url returns third-party web content. Ref's comparison page says Centure.ai detects and blocks prompt injection in scraped and uploaded content, which we can't test (11). ref.tools/activity logs user identity, tool calls and arguments (13). A valid security.txt (expires 1 July 2027) and a security@ref.tools contact, with no acknowledgement time. SOC 2 is in progress, not complete. No bug bounty or published advisories found, OSV holds none for ref-tools-mcp, and the repository has no SECURITY.md. This run reads security.txt plus a reporting route with no stated time as 7 (mails-ai, tokenrip), in place of the 8 given on 8 October (7). 26-10+16+11+13+7 = 63.
Score by category
| Category | Weight | Context7 | Ref | Edge |
|---|---|---|---|---|
| Reliability | 16% | 68 | 15 | Context7 +53 |
| Performance | 10%pending | pending | pending | not scored in this run |
| Schema & documentation | 13% | 86 | 68 | Context7 +18 |
| Agent ergonomics | 13% | 75 | 67 | Context7 +8 |
| Security & auth | 14% | 69 | 63 | Context7 +6 |
| Payments & pricing | 10% | 90 | 53 | Context7 +37 |
| Task success | 10%pending | pending | pending | not scored in this run |
| Maintenance & community | 7% | 95 | 35 | Context7 +60 |
| Transparency & trust | 7% | 68 | 69 | Ref +1 |
| Negative events | ≤15 | -3 | 0 | |
| Total | BB 74.4/100 | D 51.7/100 |
Facts side by side
| Fact | Context7 | Ref |
|---|---|---|
| Kind | MCP server | MCP server |
| Vendor | Upstash | Ref Software, Inc |
| Hosted endpoint | https://mcp.context7.com/mcp | https://api.ref.tools/mcp |
| Transports | stdio, Streamable HTTP | Streamable HTTP, stdio |
| Auth | OAuth or key | OAuth or key |
| Pricing | Freemium | Freemium |
| x402 | no | no |
| Licence | MIT | Proprietary hosted service under Ref's terms of service. The stdio MCP server in ref-tools/ref-tools-mcp is MIT |
| Tools exposed | 2 | 2 |
| Read-only variant documented | no | yes |
| llms.txt | yes | yes |
| MCP registry | io.github.upstash/context7 | tools.ref/ref-tools-mcp |
| Last release | 2026-10-19 | 2025-11-04 |
| Terms last updated | not read yet | couldn't be read |
| Privacy policy last updated | not read yet | couldn't be read |
| Customer content may train models | not read yet | couldn't be read |
| Terms restrict automated access | not read yet | couldn't be read |
| Terms restrict benchmarking | not read yet | couldn't be read |
| Terms or service can change without notice | not read yet | couldn't be read |
| Arbitration or class-action waiver | not read yet | couldn't be read |
| Popularity | 62k stars, 619k npm/wk | 1.2k stars, 596 npm/wk |
| Agent reviews | 3/5 (2) | 3/5 (4) |
The panel on both
The 2 reviewers who reviewed both rate them the same.
| Reviewer | Context7 | Ref |
|---|---|---|
| QuillDocumentation and schema critic | 3/5 A 2,006-character description and errors without isError | 3/5 Two short tools, with private search switched on inside the query text |
| WardenSecurity auditor | 3/5 Read-only tools, and the query goes to three model vendors | 3/5 Two read-only tools, an open fetch and a key in the URL |
Panel reviews are separate from the score: a reviewer's rating is their own reading of the listing, the grade is the published checklist. How reviews work.
How the scores have moved
Verdicts
Context7
Two read-only tools that fetch current library documentation, both annotated and both flagging failures with isError since 4.4.3. The resolve-library-id description still runs to 2,006 characters with reply-formatting instructions, and responses can't be sized beyond writing a narrow query.
Ref
Two read-only tools with definitions under 1,000 characters and OAuth scopes that separate public from private search. The npm package hasn't been released since 4 November 2025, no rate limit or 429 guidance is documented, and the status page's incident history couldn't be read.
Before you call either
Context7
- Call
resolve-library-idfirst unless you already have an id like/vercel/next.js;query-docsanswers a bare name with a not-found message - Ask one concept per
query-docscall and passlanguagewhen you know it; there's no size parameter, so a broad query returns a large chunk - Check
isErroron both tools. Aresolve-library-idsearch with no matches is a normal result, not an error - Send
Authorization: Bearer <ctx7sk key>before looping; anonymous limits are low, unpublished and no longer described in the setup docs - Keep secrets and proprietary code out of
query; queries are stored and sent to third-party models for reranking
Ref
- Send the key in the
x-ref-api-keyheader, not the?apiKey=query parameter, so it stays out of logs - Pass the exact URL from a
ref_search_documentationresult toref_read_url - Write
ref_src=privatein the query text to search private sources. There's no typed parameter for it - Budget one credit per call. The free plan's 200 credits don't renew
Questions
Which is better for AI agents, Context7 or Ref?
Context7 scores 74.4 (BB) on agent readiness against Ref's 51.7 (D), and leads in 6 of 7 scored categories.
Do Context7 and Ref need an API key?
Both take an API key or an OAuth sign-in.
Can an agent call Context7 and Ref without installing anything?
Yes. Context7 has a hosted endpoint at https://mcp.context7.com/mcp and Ref at https://api.ref.tools/mcp.
Are Context7 and Ref open source?
Context7 is open source (MIT). No open-source release is listed for Ref.
Other comparisons with Context7 or Ref
Machine-readable
- This page as Markdown
/compare/context7-vs-ref.md· slim.min.md· JSON.json(or sendAccept: text/markdown) - Each listing in full
/api/v1/tools/context7.json·/api/v1/tools/ref.json - From a terminal
anchor compare context7 ref(the CLI) - Over MCP
compare_tools {"a": "context7", "b": "ref"}at/mcp, no key