What is Ref Tools Mcp

Ref-tools-mcp is a ModelContextProtocol server that provides AI coding tools or agents with access to documentation for APIs, services, libraries, and more, ensuring they stay updated in a fast and token-efficient manner.

Use cases

Use cases include helping developers find specific API documentation, enabling AI agents to read and understand web content, and providing fallback search capabilities for comprehensive technical inquiries.

How to use

To use ref-tools-mcp, set it up either via the legacy stdio server or the experimental streamable-http server. Configuration involves specifying the command and arguments in your environment, including an authentication token.

Key features

Key features include ref_search_documentation for searching technical documentation, ref_read_url for reading full web page content, and an optional ref_search_web tool as a fallback for when specific documentation is not found.

Where to use

Ref-tools-mcp can be utilized in software development, AI applications, and any scenario where access to up-to-date technical documentation is essential.

Ref MCP

A ModelContextProtocol server that gives your AI coding tool or agent access to documentation for APIs, services, libraries etc. It’s your one-stop-shop to keep your agent up-to-date on documentation in a fast and token-efficient way.

For more see info ref.tools

Setup

There are two options for setting up Ref as an MCP server, either via the streamable-http server (experimental) or local stdio server.

This repo contains the legacy stdio server.

stdio

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

Streamable HTTP (experimental)

"Ref": {
    "command": "npx",
    "args": [
      "-y",
      "[email protected]",
      "https://api.ref.tools/mcp"
      "--header",
      "x-ref-api-key:<sign up to get an api key>"
    ]
  }
}

As of April 2025, MCP supports streamable HTTP servers. Ref implements this but not all clients support it yet so the most reliable approach is to use mcp-remote as a local proxy. If you know your client supports streamable HTTP servers, feel free to use https://api.ref.tools/mcp directly.

Note for former alpha users: REF_ALPHA config is still supported. You’ll be notified if you need to update.

Tools

Ref MCP server provides all the documentation related tools for your agent needs.

ref_search_documentation

A powerful search tool to check technical documentation. Use this tool whenever you need information about any technical platform, framework, API, service, database, or library. It searches through relevant documentation and finds exactly what you need, down to the specific section of the page.

ref_read_url

A tool to read the full content of a web page. This allows your agent to follow links in documentation and web searches.

ref_search_web (optional)

A fallback web search tool to cover cases when ref_search_documentation doesn’t find what you need. It will find links to relevant pages on the web and the ref_read_url tool can be used to read the relevant ones.

We include this tool so that Ref can cover all your search needs in one MCP server but if you prefer another search provider you can disable ref_search_web by setting the DISABLE_SEARCH_WEB environment variable to true or by setting the disable_search_web=false url param in the streamable-http server.

Development

npm install
npm run dev

Running with Inspector

For development and debugging purposes, you can use the MCP Inspector tool. The Inspector provides a visual interface for testing and monitoring MCP server interactions.

Visit the Inspector documentation for detailed setup instructions.

To test locally with Inspector:

npm run inspect

Or run both the watcher and inspector:

npm run dev

Local Development

1. Clone the repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

4. For development with auto-rebuilding:

npm run watch

License

MIT