Context7 vs Ref

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.

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