Ref MCP

What it does

Ref MCP connects a coding agent to Ref, a hosted documentation index run by the same team. The agent searches technical documentation for APIs, libraries and services, then reads a chosen result as markdown. Searches cover public docs by default; adding ref_src=private to the query searches the docs, repositories and PDFs a user has uploaded to their Ref account.

The point is token economy: Ref trims a long docs page down to the parts that match the session's earlier searches (the README puts this at about 5k tokens), and it does not return the same result twice when the agent repeats similar searches in one session.

This npm package is a thin client: every search and read is an HTTP call to https://api.ref.tools (overridable with REF_URL), so all the work happens on Ref's servers. Its makers now call this stdio package the legacy route and recommend their hosted endpoint instead. Besides its two tools, the code (index.ts) also registers two prompts the README does not mention, search_docs and my_docs, the second aimed at a user's private docs. When a client identifies itself as openai-mcp, the same two tools are offered as search and fetch for OpenAI deep research.

What it needs

Node.js with npx for the local package. A Ref account and API key from ref.tools, given as REF_API_KEY; the service also asks you to verify your email in the Ref dashboard before searches and reads work. Network access to api.ref.tools. The hosted endpoint needs the same key, sent in the X-Ref-Api-Key header or as the apiKey query parameter.

Limits

It only reaches what Ref has indexed or can fetch; it has no offline mode and no local index. Without an API key the server still starts, but both tools return only a 'not correctly configured' message (index.ts). Results come back as an overview, URL and module id per hit, not full text; reading needs a second call. The README marks this stdio package as legacy in favour of the hosted endpoint. With TRANSPORT=http the package serves on PORT (8080 by default) on all interfaces with CORS open to any origin (index.ts).

Who it suits

Developers using Claude Code, Cursor or similar agents who want current library and API docs pulled into context with fewer tokens than a plain web fetch, and who are fine with a Ref account and sending their queries to Ref. Teams with private docs or repos uploaded to Ref get those searched too. Since the local package only forwards calls to Ref's API, the hosted endpoint gives the same result with nothing to install. Anyone who needs offline docs or does not want queries leaving their machine should pick something else.