ref-tools

Ref MCP runs as a Node.js-based server package (ref-tools-mcp) that provides tools for accessing up-to-date documentation for APIs, services, libraries, and more, in a token-efficient way. Once running, you can leverage the built-in tools like ref_search_documentation to query and locate relevant docs, and ref_read_url to fetch and convert web pages into readable Markdown for your agent. The server is designed to minimize context usage by filtering and trimming results, returning only the most pertinent sections to support your coding tasks with fewer tokens. You can use these tools directly in your prompts to gather targeted documentation and then read through the most relevant sources without flood the model with unnecessary content.

Prerequisites:

• Node.js and npm installed on your system
• Basic familiarity with running commands in your shell

Installation and setup (npm/npx):

1. Ensure you have an API key for the Ref API and set it as an environment variable when starting the server:

   REF_API_KEY=<your_api_key> npx ref-tools-mcp@latest

2. If you prefer to run without exposing your API key in the shell, you can export it beforehand:

   export REF_API_KEY=<your_api_key> npx ref-tools-mcp@latest

3. Optional: Verify the server starts and listens for MCP requests. You should see logs indicating the MCP server is running and ready to handle requests.

4. For local development, you can install dependencies and build if necessary (depending on your setup):

   npm install npm run dev

Notes:

• The recommended approach is the Streamable HTTP option via the provided package; this guide focuses on the stdio approach using npx as shown in the repository README.

Tips and common considerations:

• Always supply REF_API_KEY as an environment variable; without it, the MCP server may not authenticate requests.
• The npm package name is ref-tools-mcp; ensure you’re fetching the latest version with @latest.
• If you’re integrating with OpenAI or other agents, you can map ref_search_documentation to search(query) and ref_read_url to fetch(id) as part of your prompt tooling.
• Be mindful of token usage: Ref aims to minimize context taken from documentation by filtering results and prioritizing relevant sections.
• If you encounter networking issues, verify your API key permissions and network access to the Ref API endpoint.
• When using streamable HTTP, you would configure an http-based MCP server endpoint; this entry focuses on the stdio/npx setup.