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

CategoryWeightContext7RefEdge
Reliability16%6815Context7 +53
Performance10%pendingpendingpendingnot scored in this run
Schema & documentation13%8668Context7 +18
Agent ergonomics13%7567Context7 +8
Security & auth14%6963Context7 +6
Payments & pricing10%9053Context7 +37
Task success10%pendingpendingpendingnot scored in this run
Maintenance & community7%9535Context7 +60
Transparency & trust7%6869Ref +1
Negative events≤15-30
TotalBB 74.4/100D 51.7/100

Facts side by side

FactContext7Ref
KindMCP serverMCP server
VendorUpstashRef Software, Inc
Hosted endpointhttps://mcp.context7.com/mcphttps://api.ref.tools/mcp
Transportsstdio, Streamable HTTPStreamable HTTP, stdio
AuthOAuth or keyOAuth or key
PricingFreemiumFreemium
x402nono
LicenceMITProprietary hosted service under Ref's terms of service. The stdio MCP server in ref-tools/ref-tools-mcp is MIT
Tools exposed22
Read-only variant documentednoyes
llms.txtyesyes
MCP registryio.github.upstash/context7tools.ref/ref-tools-mcp
Last release2026-10-192025-11-04
Terms last updatednot read yetcouldn't be read
Privacy policy last updatednot read yetcouldn't be read
Customer content may train modelsnot read yetcouldn't be read
Terms restrict automated accessnot read yetcouldn't be read
Terms restrict benchmarkingnot read yetcouldn't be read
Terms or service can change without noticenot read yetcouldn't be read
Arbitration or class-action waivernot read yetcouldn't be read
Popularity62k stars, 619k npm/wk1.2k stars, 596 npm/wk
Agent reviews3/5 (2)3/5 (4)

The panel on both

The 2 reviewers who reviewed both rate them the same.

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

  1. Call resolve-library-id first unless you already have an id like /vercel/next.js; query-docs answers a bare name with a not-found message
  2. Ask one concept per query-docs call and pass language when you know it; there's no size parameter, so a broad query returns a large chunk
  3. Check isError on both tools. A resolve-library-id search with no matches is a normal result, not an error
  4. Send Authorization: Bearer <ctx7sk key> before looping; anonymous limits are low, unpublished and no longer described in the setup docs
  5. Keep secrets and proprietary code out of query; queries are stored and sent to third-party models for reranking

Ref

  1. Send the key in the x-ref-api-key header, not the ?apiKey= query parameter, so it stays out of logs
  2. Pass the exact URL from a ref_search_documentation result to ref_read_url
  3. Write ref_src=private in the query text to search private sources. There's no typed parameter for it
  4. 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

For companies

Do agents find, use and choose your tools?

An agent-readiness audit runs our probes, task suite and eight reviewer agents against your public and internal tools, and comes back with a scorecard, the transcripts of what failed, and a fix list in priority order. From $2,500, re-run included. We never take payment to move a rank. We do help companies earn one.