Ref

https://docs.ref.tools/
Admin
Ref provides an MCP server, offering tools and resources for managing and interacting with the MCP...
Tokens:12,260
Snippets:65
Trust Score:5.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Ref MCP with Amp CLI

Source: https://docs.ref.tools/install/amp

Installs the Ref MCP (Message Content Provider) using the Amp CLI. This command adds a new provider named 'Ref' pointing to the Ref Tools API, requiring your API key for authentication. Ensure you replace '<YOUR_API_KEY>' with your actual API key.

```bash
amp mcp add Ref https://api.ref.tools/mcp --header "x-ref-api-key: <YOUR_API_KEY>"
```

--------------------------------

### Ref MCP Server API

Source: https://docs.ref.tools/install

The Ref MCP Server provides documentation search capabilities via a streamable HTTP server. Authentication can be handled through API keys in headers or query parameters, or via OAuth.

```APIDOC
## GET /mcp

### Description
Connect to Ref's documentation search capabilities using the Model Context Protocol (MCP).

### Method
GET

### Endpoint
`https://api.ref.tools/mcp`

### Parameters
#### Query Parameters
- **apiKey** (string) - Optional - Your Ref API key for authentication.

### Request Example
`GET https://api.ref.tools/mcp?apiKey=YOUR_API_KEY`

### Response
#### Success Response (200)
- **(Streamed MCP Data)** - Description varies based on the MCP client request.

### Authentication Methods
Ref's API accepts authentication in three ways:
1. **As a header**: `x-ref-api-key: YOUR_API_KEY`
2. **As a query parameter**: `?apiKey=YOUR_API_KEY`
3. **OAuth**: Include neither header or query param and your MCP client will initiate OAuth sign-in.

**Note**: You can find your API key at [ref.tools/keys](https://ref.tools/keys).

### OAuth and Teams
If using OAuth with Teams, you may need to specify the team scope. Ref attempts to intelligently pick the scope but manual specification is possible.

**Scope Algorithm**: 
- If the user belongs to no teams: user scope.
- If the user belongs to one team: team scope for that single team.
- If the user belongs to multiple teams: user scope, requires specifying the team.

**Specifying Scope in OAuth URL**: `https://api.ref.tools/mcp?scope=(user|{team_id})`
- `scope=user`: grants user scope.
- `scope={team_id}`: grants team scope for the specified team.

Team IDs have the format `t-<hash>`. Team OAuth URLs can be found at [ref.tools/install](https://ref.tools/install).
```

--------------------------------

### Configure Roo Code MCP Servers

Source: https://docs.ref.tools/install/roo-code

This JSON configuration sets up the 'Ref' MCP server for Roo Code. It specifies the command to run, arguments including the package to install, and environment variables like the API key required for authentication.

```json
{
  "mcpServers": {
    "Ref": {
      "command": "npx",
      "args": ["ref-tools-mcp@latest"],
      "env": {
        "REF_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

--------------------------------

### Verify Amp MCP Connection

Source: https://docs.ref.tools/install/amp

Verifies the connection and status of installed Message Content Providers (MCPs) with the Amp CLI. This command checks if Ref and its associated tools (ref_search_documentation, ref_read_url) are correctly connected and configured in both user and workspace settings.

```bash
amp mcp doctor
```

--------------------------------

### Ref MCP Server Authentication Methods

Source: https://docs.ref.tools/install

Demonstrates the three ways to authenticate with Ref's MCP server: as a header, a query parameter, or via OAuth. The streamable HTTP endpoint is available at https://api.ref.tools/mcp.

```plaintext
1. As a header: x-ref-api-key: YOUR_API_KEY
2. As a query parameter: ?apiKey=YOUR_API_KEY
3. OAuth: Include neither header or query param and your MCP client will initiate OAuth sign-in.
```

--------------------------------

### Install Stdio Server for Older Codex CLI Versions

Source: https://docs.ref.tools/install/codex

For older Codex CLI versions encountering configuration errors, this TOML snippet installs the `stdio` server for Ref Tools integration. It specifies the command to execute (`npx`), arguments, and environment variables, including the API key.

```toml
[mcp_servers.ref]
command = "npx"
args = ["-y", "ref-tools-mcp@latest"]
env = { "REF_API_KEY" = "<your-api-key>" }
```

--------------------------------

### Install Ref Tools MCP Configuration via Direct Link

Source: https://docs.ref.tools/install/kiro

This HTML snippet provides a clickable link to automatically add the Ref Tools MCP configuration to Kiro. It includes the necessary URL and headers, with a placeholder for the API key. Ensure you replace `<YOUR_API_KEY>` with your actual API key.

```html
<a href="kiro://kiro.mcp/add?name=Ref&config=%7B%22url%22%3A%22https%3A%2F%2Fapi.ref.tools%2Fmcp%22%2C%22headers%22%3A%7B%22x-ref-api-key%22%3A%22%3CYOUR_API_KEY%3E%22%7D%2C%22autoApprove%22%3A%5B%22ref_search_documentation%22%2C%22ref_read_url%22%5D%7D">
  <img noZoom src="https://kiro.dev/images/add-to-kiro.svg" alt="Add Ref to Kiro" />
</a>
```

--------------------------------

### Configure OpenCode MCP Connection (JSON)

Source: https://docs.ref.tools/install/opencode

This JSON configuration file sets up a connection to the ref.tools MCP service within OpenCode. It specifies the service type, URL, and includes an API key for authentication. Ensure you replace 'YOUR_API_KEY' with your actual API key obtained from ref.tools/keys.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Ref": {
      "type": "remote",
      "url": "https://api.ref.tools/mcp",
      "enabled": true,
      "headers": {
        "x-ref-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

--------------------------------

### Verify Claude Code MCP Installation

Source: https://docs.ref.tools/install/claude-code

Verifies that the Claude Code MCP has been successfully installed and configured. Running this command lists the currently configured MCPs and their transport details.

```bash
claude mcp list
```

--------------------------------

### Install Claude Code MCP

Source: https://docs.ref.tools/install/claude-code

Installs the Claude Code MCP (Model Communication Protocol) for Ref Tools. This command requires your API key, which can be obtained from ref.tools/keys. The MCP is added using an HTTP transport to the specified API endpoint.

```bash
claude mcp add --transport http Ref https://api.ref.tools/mcp --header "x-ref-api-key: <YOUR_API_KEY>"
```

--------------------------------

### Get Ref's MCP Registry Data

Source: https://docs.ref.tools/mcp/registry

This command retrieves the complete server metadata for Ref from the MCP registry. It uses curl to make an HTTP GET request to the registry API, filtering by the specific Ref registry name. The output is JSON containing server details that can be imported into a custom registry.

```bash
curl "https://registry.modelcontextprotocol.io/v0/servers?search=tools.ref/ref-tools-mcp"
```

--------------------------------

### Ref OAuth Scope Algorithm

Source: https://docs.ref.tools/install

Details the algorithm Ref uses to determine the user or team scope for OAuth authentication. It explains how scope is selected based on the number of teams a user belongs to and how to manually specify scope in the OAuth URL.

```plaintext
For base OAuth url https://api.ref.tools/mcp if the user belongs to:
  - no teams -> user scope
  - one team -> team scope for the users single team
  - multiple teams -> user scope, require specifying team

When specifying scope in OAuth url https://api.ref.tools/mcp?scope=(user|{team_id})
  - scope=user -> user scope
  - scope={team_id} -> team scope
```

--------------------------------

### Manual MCP Server Configuration for Ref Tools

Source: https://docs.ref.tools/install/kiro

This JSON configuration is used to manually set up the Ref Tools MCP server within Kiro. It specifies the server URL, necessary headers (including your API key), and auto-approved actions. Replace `<YOUR_API_KEY>` with your actual API key.

```json
{
  "mcpServers": {
    "Ref": {
      "url": "https://api.ref.tools/mcp",
      "headers": {
        "x-ref-api-key": "<YOUR_API_KEY>"
      },
      "disabled": false,
      "autoApprove": ["ref_search_documentation", "ref_read_url"]
    }
  }
}
```

--------------------------------

### Configure Gemini CLI with Ref settings.json

Source: https://docs.ref.tools/install/gemini-cli

Update the `settings.json` file for Gemini CLI to include the Ref MCP server configuration. This involves adding an entry to the `mcpServers` object with the `httpUrl` pointing to the Ref API and your API key. Ensure your API key is correctly placed in the URL.

```json
{
  "mcpServers": {
    "ref": {
      "httpUrl": "https://api.ref.tools/mcp?apiKey=<your-api-key>"
    }
  }
}
```

--------------------------------

### ref_search_documentation

Source: https://docs.ref.tools/mcp/tools

Searches across your indexed documentation resources. Provide relevant keywords for more accurate results.

```APIDOC
## ref_search_documentation

### Description
Search across your indexed documentation resources.

### Method
POST

### Endpoint
/websites/ref_tools/ref_search_documentation

### Parameters
#### Query Parameters
- **query** (string) - Required - Your search query. Include programming language, framework, or library names for best results.

### Request Example
```json
{
  "query": "react state management"
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results.
  - **title** (string) - The title of the documentation entry.
  - **url** (string) - The URL of the documentation entry.
  - **snippet** (string) - A brief snippet of the content.

#### Response Example
```json
{
  "results": [
    {
      "title": "Understanding React State",
      "url": "https://reactjs.org/docs/state-a",
      "snippet": "State allows React components to remember information between renders..."
    }
  ]
}
```
```

--------------------------------

### Configure MCP Servers in cline_mcp_settings.json

Source: https://docs.ref.tools/install/cline

This JSON configuration snippet defines how Cline should interact with MCP servers. It specifies the command to run, its arguments, and environment variables, including the crucial `REF_API_KEY`.

```json
{
  "mcpServers": {
    "Ref": {
      "command": "npx",
      "args": ["ref-tools-mcp@latest"],
      "env": {
        "REF_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

--------------------------------

### Configure Ref MCP Server for Codex CLI

Source: https://docs.ref.tools/install/codex

This TOML configuration snippet shows how to add Ref Tools as an MCP server to your Codex CLI. It requires your Ref API key and specifies the server URL. Ensure the `apiKey` is correctly inserted.

```toml
[mcp_servers.ref]
url = "https://api.ref.tools/mcp?apiKey=<your-api-key>"
```

--------------------------------

### Configure Ref MCP Server in mcp.json

Source: https://docs.ref.tools/install/cursor

Manually configure the mcp.json file to connect Cursor to the Ref MCP server. This involves specifying the server type, URL, and authentication headers including your Ref API key. Ensure your API key is kept confidential.

```json
{
  "mcpServers": {
    "Ref": {
      "type": "http",
      "url": "https://api.ref.tools/mcp",
      "headers": {
        "x-ref-api-key": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### ref_read_url

Source: https://docs.ref.tools/mcp/tools

Reads the full content of a documentation URL. This can be used for URLs obtained from search results or any other web URL.

```APIDOC
## ref_read_url

### Description
Read the full content of a documentation URL. Can read URLs from search results or any URL from the web.

### Method
POST

### Endpoint
/websites/ref_tools/ref_read_url

### Parameters
#### Query Parameters
- **url** (string) - Required - The exact URL from a search result or any web URL.

### Request Example
```json
{
  "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript"
}
```

### Response
#### Success Response (200)
- **content** (string) - The full text content of the specified URL.

#### Response Example
```json
{
  "content": "JavaScript is a programming language that... (full content of the page)"
}
```
```

--------------------------------

### Ref MCP Registry Name

Source: https://docs.ref.tools/mcp/registry

This snippet shows the specific identifier for the Ref MCP registry. This name is used when searching for or referencing Ref within the MCP registry system.

```text
tools.ref/ref-tools-mcp
```
Tokens:
Raw