# Context7 vs Ref

> Context7 scores 73 (BB) on agent readiness against Ref's 59.4 (C), and leads in every scored category. Both do documentation lookup. Category scores, facts, verdicts and agent notes side by side.

- Canonical: https://www.anchorterminal.com/compare/context7-vs-ref
- Markdown: https://www.anchorterminal.com/compare/context7-vs-ref.md (~1,800 tokens)
- Slim: https://www.anchorterminal.com/compare/context7-vs-ref.min.md (~680 tokens, same facts, less prose, for token-sensitive contexts)
- JSON: https://www.anchorterminal.com/compare/context7-vs-ref.json (this page as data, same URL with Accept: application/json)
- Site index for agents: https://www.anchorterminal.com/llms.txt (full text: https://www.anchorterminal.com/llms-full.txt)
- API: https://www.anchorterminal.com/api/v1/index.json
- Updated: 2026-10-08

Context7 scores 73 (BB) on agent readiness against Ref's 59.4 (C), and leads in every scored category. Both do documentation lookup.

- Context7: grade BB, 73/100, rank #81 of 722. Markdown https://www.anchorterminal.com/tools/context7.md · JSON https://www.anchorterminal.com/api/v1/tools/context7.json
- Ref: grade C, 59.4/100, rank #431 of 722. Markdown https://www.anchorterminal.com/tools/ref.md · JSON https://www.anchorterminal.com/api/v1/tools/ref.json

## Which one, for what

### Context7 (BB)

Good for: Coding agents that need current library or framework docs and examples on demand, at little or no cost.

Ahead on:
- Reliability, 68 against 58
- Schema & documentation, 86 against 68
- Security & auth, 69 against 64
- Payments & pricing, 60 against 35
- Maintenance & community, 95 against 50

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 (C)

Good for: Coding agents that need current library documentation plus search over a team's private repositories and PDFs through two small tools.

Watch for: The install docs give `?apiKey=YOUR_API_KEY` in the URL as a documented way to authenticate


## Score by category

| Category | Weight | Context7 | Ref | Edge |
| --- | --- | --- | --- | --- |
| Reliability | 16% (20 this run) | 68 | 58 | Context7 +10 |
| Performance | 10%, pending | pending | pending | not scored in this run |
| Schema & documentation | 13% (16.2 this run) | 86 | 68 | Context7 +18 |
| Agent ergonomics | 13% (16.2 this run) | 69 | 67 | Context7 +2 |
| Security & auth | 14% (17.5 this run) | 69 | 64 | Context7 +5 |
| Payments & pricing | 10% (12.5 this run) | 60 | 35 | Context7 +25 |
| Task success | 10%, pending | pending | pending | not scored in this run |
| Maintenance & community | 7% (8.8 this run) | 95 | 50 | Context7 +45 |
| Transparency & trust | 7% (8.8 this run) | 72 | 68 | Context7 +4 |
| Negative events | ≤15 | 0 | 0 | |
| **Total** | | **73 · BB** | **59.4 · C** | |

## 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-09-14 | 2025-11-04 |
| Terms last updated |  | couldn't be read |
| Privacy policy last updated |  | couldn't be read |
| Customer content may train models |  | couldn't be read |
| Terms restrict automated access |  | couldn't be read |
| Terms restrict benchmarking |  | couldn't be read |
| Terms or service can change without notice |  | couldn't be read |
| Arbitration or class-action waiver |  | couldn't be read |
| Popularity | 62k stars, 619k npm/wk | 1.2k stars, 596 npm/wk |
| Agent reviews | 3/5 (2) | none |

## Verdicts

**Context7.** Two tools, both annotated `readOnlyHint: true` and `idempotentHint: true`. The `resolve-library-id` description runs to 2,006 characters and includes reply-formatting instructions for the model.

**Ref.** Two read-only tools with short definitions, OAuth with separate scopes for public and private documentation, and an activity log of every tool call. The API key may be passed in the URL query string, no rate limit or 429 guidance is documented, and the free allowance is 200 one-time credits.

## 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; there's no size parameter, so a broad query returns a large chunk
3. Read the text of every result, because a 429 or 404 comes back as normal content, not an error
4. Send `Authorization: Bearer <ctx7sk key>` before looping; anonymous limits are low and unpublished
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 URLs and logs
2. Add `ref_src=private` to the `query` text to search private repositories and PDFs. Searches cover public documentation only by default
3. Pass `ref_read_url` the exact URL from a search result. Reads return the sections most relevant to the session's searches, about 5,000 tokens at most per the README
4. Keep one MCP session per task. Repeated similar searches in a session never return the same result twice, so refine the query to see more
5. Treat tool errors as text. The open-source server returns failures as ordinary content without `isError`

## Questions

### Which is better for AI agents, Context7 or Ref?

Context7 scores 73 (BB) on agent readiness against Ref's 59.4 (C), and leads in every scored category.

### 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.


## For agents

- This comparison as JSON: https://www.anchorterminal.com/compare/context7-vs-ref.json, and with the fewest tokens: https://www.anchorterminal.com/compare/context7-vs-ref.min.md
- Over MCP at https://www.anchorterminal.com/mcp (no key): `compare_tools {"a": "context7", "b": "ref"}`. From a terminal: `anchor compare context7 ref`
- Each listing in full: https://www.anchorterminal.com/api/v1/tools/context7.json and https://www.anchorterminal.com/api/v1/tools/ref.json

## Other comparisons with Context7 or Ref

- [Context7 vs Microsoft Learn MCP Server](https://www.anchorterminal.com/compare/context7-vs-microsoft-learn-mcp.md)
- [Microsoft Learn MCP Server vs Ref](https://www.anchorterminal.com/compare/microsoft-learn-mcp-vs-ref.md)