ref-tools-mcp MCP — Casos de uso, Instalar & Demo en vivo

Name: ref-tools-mcp MCP Server
Author: ref-tools

Por qué usarlo

Características clave

Busca documentación técnica en la web pública con conciencia de librerías
Busca en repositorios privados de GitHub y PDFs internos (indexados por Ref)
ref_read_url devuelve markdown limpio, no sopa HTML
Eficiente en tokens — diseñado para minimizar contexto desperdiciado
Instalación simple con npx

Demo en vivo

Cómo se ve en la práctica

ref-tools.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ref-tools": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "_inferred": true
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "ref-tools": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "ref-tools": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "_inferred": true
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ref-tools": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "ref-tools",
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "ref-tools": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "ref-tools-mcp"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add ref-tools -- npx -y ref-tools-mcp

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: ref-tools-mcp

Cómo evitar que el agente alucine APIs de librerías

👤 Usuarios de agentes de codificación ⏱ ~10 min beginner

Cuándo usarlo: El agente escribe código confiadamente que no coincide con la versión actual de la librería.

Requisitos previos

Cuenta de Ref + REF_API_KEY — Regístrate en ref.tools (o la URL de registro de Ref actual)

Flujo

Haz una pregunta fundamentada en la documentación

Usa ref_search_documentation para encontrar cómo usar consultas SQL sin procesar de Prisma en v5, luego escribe un ejemplo.✓ Copiado

→ Resultados de búsqueda con URLs; el código los cita
Verifica

ref_read_url en el resultado principal para confirmar la forma de la API.✓ Copiado

→ Markdown limpio de la página de documentación

Resultado: Código que se compila contra la versión actual de la librería.

Errores comunes

La búsqueda devuelve documentación desactualizada para v-X obsoleto — Incluye la versión en la consulta: 'Prisma v5 raw SQL'

Combinar con: github

Cómo buscar documentación de ingeniería interna / PDFs con un agente

👤 Equipos de plataforma con procedimientos internos ⏱ ~15 min intermediate

Cuándo usarlo: El agente necesita seguir patrones específicos de la empresa, no lo que dice StackOverflow.

Requisitos previos

Fuentes privadas de Ref indexadas — Carga repositorios/PDFs a tu espacio de trabajo de Ref (ver documentación de Ref)

Flujo

Limita la búsqueda a privado

ref_search_documentation 'patrón de autenticación interno' solo con fuentes privadas.✓ Copiado

→ Solo resultados internos
Lee el procedimiento

ref_read_url en el resultado interno principal.✓ Copiado

→ Texto limpio del procedimiento

Resultado: Salida conforme a estándares internos.

Errores comunes

La documentación interna se vuelve obsoleta — el agente todavía la cita — Dile al agente que verifique los metadatos de 'última actualización' y marque contenido antiguo

Cómo obtener URLs arbitrarias como markdown limpio

👤 Cualquiera que haga investigación + resumen ⏱ ~5 min beginner

Cuándo usarlo: Quieres el texto del artículo sin nav/anuncios/basura JS.

Flujo

Lee la URL

ref_read_url https://some-blog.com/post — dame markdown limpio.✓ Copiado

→ Texto del cuerpo como markdown
Resume

Ahora dame un resumen de 5 puntos.✓ Copiado

→ Resumen

Resultado: Contenido limpio, rápido.

Combinar con: markdownify

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

ref-tools + github

Fundamenta una revisión de PR con citas de documentación oficial

Para la migración de Prisma en PR #1234, usa ref_search_documentation para verificar que cada API coincida con la documentación v5, luego comenta en el PR.✓ Copiado

ref-tools + markdownify

Combina la búsqueda de documentación de Ref con markdownify para PDFs locales no en Ref

Busca en Ref nuestra guía de autenticación interna, luego convierte con markdownify el /specs/auth-v3.pdf adicional que aún no está indexado.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
ref_search_documentation	query: str, sources?: str[]	Fundamenta una pregunta de librería o documentación interna	1 llamada API de Ref
ref_read_url	url: str	Obtén una página como markdown limpio	1 llamada API de Ref

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Por nivel de plan de Ref
Tokens por llamada: Resultados de búsqueda: 500-2000 tokens. Lecturas de URL: pueden ser 5k-20k
Monetario: Ref es un servicio de pago (nivel gratuito disponible); verifica el precio actual
Consejo: Busca primero, luego lee solo el resultado principal — las lecturas encadenadas son costosas.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: REF_API_KEY almacenada en env

Almacenamiento de credenciales: Variable de entorno REF_API_KEY

Salida de datos: Las consultas van al servicio de Ref; que a su vez accede a la web pública y tus fuentes privadas indexadas

No conceder nunca: No compartas tu clave de espacio de trabajo ampliamente; usa claves por usuario si Ref las soporta

Las fuentes privadas cargadas en Ref viven en su infraestructura — revisa su DPA para contenido sensible.

Resolución de problemas

Errores comunes y soluciones

401 No autorizado

REF_API_KEY faltante o inválida.

Verificar: echo $REF_API_KEY

La búsqueda devuelve resultados obsoletos

La reindexación de fuentes privadas puede retrasarse; fuerza la reindexación desde el panel de Ref.

ref_read_url devuelve vacío

Algunos sitios bloquean el raspado. Usa webpage-to-markdown a través de markdownify como alternativa.

Cuota excedida

Actualiza el plan de Ref o espacía el uso de búsqueda.

Alternativas

ref-tools-mcp vs otros

Alternativa	Cuándo usarla	Contrapartida
Context7 MCP	Quieres recuperación gratuita de documentación de librerías públicas	Sin indexación de fuentes privadas
Apple Docs MCP / pg-aiguide	Solo te importa la documentación de una plataforma específica	Limitado; no es de propósito general

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills