> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor Olostep MCP

> Proporciona a cualquier cliente AI compatible con MCP herramientas de scraping web, búsqueda, rastreo y respuestas AI en menos de un minuto

El servidor Olostep MCP ofrece a cualquier cliente AI compatible con MCP (Claude, Cursor, Windsurf, VS Code, Claude Code, etc.) 10 herramientas listas para usar en la web en vivo: scraping, búsqueda, respuestas AI con citas, trabajos por lotes, rastreo de sitios y descubrimiento de URLs.

<CardGroup cols={2}>
  <Card title="Raspar y extraer" icon="file-lines">
    Extrae markdown, HTML, JSON o texto de cualquier URL con renderizado JS opcional
  </Card>

  <Card title="Respuestas AI" icon="sparkles">
    Respuestas fundamentadas en la web con fuentes y salida estructurada
  </Card>

  <Card title="Lote y rastreo" icon="layer-group">
    Hasta 10k URLs en paralelo, o descubre un sitio completo de manera autónoma
  </Card>

  <Card title="Mapa y búsqueda" icon="map">
    Encuentra cada URL en un sitio, o ejecuta una búsqueda web basada en parser
  </Card>
</CardGroup>

## Antes de comenzar

Necesitas una clave API de Olostep. Consigue una desde el [tablero de Olostep](https://www.olostep.com/dashboard/api-keys) — el nivel gratuito cubre el uso personal.

## Elige una ruta de configuración

La ruta más rápida para cada cliente es el **endpoint alojado** en `https://mcp.olostep.com/mcp`. Sin instalaciones, sin Node, sin Docker — solo pega una URL y tu clave API.

Si necesitas que funcione completamente local (uso offline, proxy corporativo, aislado), cada cliente también admite una instalación **local stdio** a través de `npx`. Cada sección a continuación muestra ambos.

<Note>
  **Endpoint alojado** usa `Authorization: Bearer YOUR_API_KEY`. **Local stdio** usa `OLOSTEP_API_KEY` como una variable de entorno. No los mezcles — el modo de autenticación incorrecto es el error de incorporación número 1.
</Note>

## Configuración del cliente

<Tabs>
  <Tab title="Cursor">
    **Instalación con un clic (recomendada):**

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=olostep&config=eyJ1cmwiOiJodHRwczovL21jcC5vbG9zdGVwLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19">
      <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="Agregar servidor Olostep MCP a Cursor" style={{ maxHeight: 32 }} />
    </a>

    Reemplaza `YOUR_API_KEY` en la configuración resultante con tu clave real.

    **Configuración manual:**

    Crea o edita `.cursor/mcp.json` en la raíz de tu proyecto (o `~/.cursor/mcp.json` para global):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Instalación local stdio (opcional)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      Requiere Node.js 18+ en tu máquina.
    </Accordion>

    **Verificar:** Abre Cursor → Configuración → MCP. Deberías ver `olostep` listado con **10 herramientas** incluyendo `scrape_website`. Si ves "Conectado, 0 herramientas", tu clave API es incorrecta.
  </Tab>

  <Tab title="Claude Code">
    **Instalación CLI (recomendada):**

    ```bash theme={null}
    claude mcp add --transport http olostep https://mcp.olostep.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    **Configuración manual:**

    Agrega a tu configuración MCP de Claude Code (`.mcp.json` en la raíz del proyecto, o `~/.claude.json` globalmente):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Instalación local stdio (opcional)">
      ```bash theme={null}
      claude mcp add --transport stdio --env OLOSTEP_API_KEY=YOUR_API_KEY olostep \
        -- npx -y olostep-mcp
      ```

      O como JSON:

      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verificar:** Ejecuta `/mcp` en Claude Code. Deberías ver `olostep` conectado con 10 herramientas.
  </Tab>

  <Tab title="Claude Desktop">
    **Ubicación del archivo de configuración:**

    | OS      | Ruta                                                              |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    **Alojado (recomendado):**

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Instalación local stdio (opcional)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      O instala a través de Smithery:

      ```bash theme={null}
      npx -y @smithery/cli install @olostep/olostep-mcp-server --client claude
      ```
    </Accordion>

    <Warning>
      Claude Desktop debe ser **completamente cerrado y reiniciado** para que los cambios de configuración surtan efecto — cerrar la ventana no es suficiente (permanece ejecutándose en la barra de menú / bandeja del sistema).
    </Warning>

    **Verificar:** Abre Claude Desktop → busca el icono de 🔨 (martillo) en el campo de entrada de chat. Haz clic en él — deberías ver 10 herramientas de Olostep listadas.
  </Tab>

  <Tab title="VS Code">
    El soporte MCP de VS Code está integrado en GitHub Copilot (modo Agente). Agrega esto a `.vscode/mcp.json` en tu proyecto, o en tu `settings.json` de usuario:

    ```json theme={null}
    {
      "servers": {
        "olostep": {
          "type": "http",
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Instalación local stdio (opcional)">
      ```json theme={null}
      {
        "servers": {
          "olostep": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verificar:** Abre el panel de chat de Copilot → cambia a modo Agente → el popover de herramientas debería listar las herramientas de Olostep.
  </Tab>

  <Tab title="Windsurf">
    Agrega a `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "serverUrl": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Instalación local stdio (opcional)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verificar:** Cascade → Configuración → MCP. `olostep` debería aparecer con 10 herramientas.
  </Tab>

  <Tab title="Docker">
    Si prefieres ejecutar el servidor en un contenedor (CI, entorno aislado, sin Node en el host):

    ```bash theme={null}
    docker pull olostep/mcp-server

    docker run -i --rm \
      -e OLOSTEP_API_KEY="YOUR_API_KEY" \
      olostep/mcp-server
    ```

    En una configuración de cliente MCP (stdio):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-e", "OLOSTEP_API_KEY=YOUR_API_KEY",
            "olostep/mcp-server"
          ]
        }
      }
    }
    ```

    Soporta `linux/amd64` y `linux/arm64`. Fuente en [GitHub](https://github.com/olostep/olostep-mcp-server).
  </Tab>

  <Tab title="Metorial">
    1. Abre el [tablero de Metorial](https://metorial.com)
    2. Navega a **Servidores MCP**
    3. Busca **Olostep**
    4. Haz clic en **Instalar** y pega tu clave API

    Para configuración manual:

    ```json theme={null}
    {
      "olostep": {
        "command": "npx",
        "args": ["-y", "olostep-mcp"],
        "env": {
          "OLOSTEP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Elegir la herramienta adecuada

El servidor MCP expone 10 herramientas. Usa este árbol de decisiones para elegir la correcta — el agente usa el mismo razonamiento:

| Quieres...                                        | Usa                                       | Notas                                                |
| ------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
| El contenido de una página específica             | `scrape_website` o `get_webpage_content`  | Establece `wait_before_scraping=2000–5000` para SPAs |
| Una respuesta web en lenguaje natural con fuentes | `answers`                                 | Devuelve síntesis AI + citas                         |
| Resultados de búsqueda para una consulta          | `search_web`                              | Basado en parser, no AI, estructurado                |
| Una lista de URLs en un sitio                     | `create_map`                              | Solo descubrimiento de URLs — NO raspa               |
| URLs filtradas por consulta                       | `get_website_urls`                        | Clasificadas por relevancia a tu `search_query`      |
| Muchas URLs conocidas a la vez                    | `batch_scrape_urls` + `get_batch_results` | Asíncrono — inicia, luego consulta                   |
| Un sitio completo o sección                       | `create_crawl` + `get_crawl_results`      | Asíncrono — sigue enlaces desde una URL de inicio    |

<Tip>
  **¿Raspar un sitio completo?** Usa `create_crawl`, no `batch_scrape_urls`. Crawl descubre Y raspa. Batch es para una lista conocida de URLs que ya tienes.
</Tip>

### Detalles de las herramientas

<Accordion title="scrape_website">
  Extrae contenido de una sola URL. Soporta `markdown`, `html`, `json`, `text`. Opcional `country` para solicitudes geo-dirigidas, `wait_before_scraping` (0–10000 ms) para sitios pesados en JS, y `parser` (por ejemplo, `@olostep/amazon-product`) para extracción estructurada.
</Accordion>

<Accordion title="get_webpage_content">
  Versión ligera solo markdown de `scrape_website`. Úsalo cuando solo quieras markdown limpio y no necesites opciones de formato.
</Accordion>

<Accordion title="search_web">
  Resultados de búsqueda web estructurados (basados en parser) para una consulta. Opcional `country` para resultados localizados. Devuelve JSON, no prosa AI.
</Accordion>

<Accordion title="answers">
  Respuesta impulsada por AI a una `task` con fuentes y citas. Pasa un argumento `json` para obtener la respuesta en una forma específica — ya sea un esquema JSON o una breve descripción en lenguaje natural.
</Accordion>

<Accordion title="batch_scrape_urls">
  Raspa asíncronamente de 2–10k URLs que ya tienes. Devuelve un `batch_id` — luego llama a `get_batch_results` para obtener el contenido. Establece `wait_for_completion_seconds` (hasta 900) si deseas una sola llamada bloqueante en lugar de consultar. Recomendado: 60 para lotes de menos de 50 URLs, 300–600 para 50–1k, 0 (consulta por separado) para lotes más grandes.
</Accordion>

<Accordion title="get_batch_results">
  Obtiene el estado y el contenido raspado para un `batch_id`. Devuelve `processing` hasta que esté completo, luego `completed` con el array de elementos.
</Accordion>

<Accordion title="create_crawl">
  Rastreo asíncrono que sigue enlaces desde un `start_url`. Usa `include_url_patterns` / `exclude_url_patterns` (sintaxis glob como `/blog/**`) para definir el alcance. Devuelve un `crawl_id` — luego llama a `get_crawl_results`.
</Accordion>

<Accordion title="get_crawl_results">
  Obtiene el estado y las páginas para un `crawl_id`. Soporta paginación a través de `cursor` y `items_limit` (máximo 100 por llamada). Devuelve `in_progress` hasta que esté completo.
</Accordion>

<Accordion title="create_map">
  Obtén una lista de URLs en un sitio. Solo descubrimiento de URLs — no raspa. Úsalo cuando quieras mostrar URLs candidatas (por ejemplo, dejar que el usuario elija un subconjunto). Soporta `include_url_patterns` / `exclude_url_patterns` y `search_query`.
</Accordion>

<Accordion title="get_website_urls">
  Como `create_map`, pero las URLs se clasifican por relevancia a una `search_query` requerida. Úsalo cuando quieras los N enlaces más relevantes en un sitio.
</Accordion>

## Solución de problemas

<Accordion title="El servidor aparece pero muestra 0 herramientas">
  Tu clave API es inválida o está limitada por tasa. Abre el [tablero de claves API](https://www.olostep.com/dashboard/api-keys) y verifica la clave. Si usas el endpoint alojado, el encabezado debe ser **exactamente** `Authorization: Bearer sk_...` — sin comillas alrededor del valor, sin espacios adicionales.
</Accordion>

<Accordion title="`npx: command not found` o `command not found: olostep-mcp`">
  Node.js no está instalado (o no está en tu PATH). Instala Node 18+ desde [nodejs.org](https://nodejs.org/), luego reinicia tu terminal **y** tu cliente MCP. En Windows, cambia a un CMD/PowerShell que tenga Node en el PATH.
</Accordion>

<Accordion title="Conexión rechazada o errores de DNS en `mcp.olostep.com`">
  Probablemente estés detrás de un proxy corporativo o firewall que bloquea el host. Cambia a la instalación local stdio (`npx -y olostep-mcp`) — realiza solicitudes salientes a `api.olostep.com` en su lugar, lo cual generalmente está permitido.
</Accordion>

<Accordion title="Configuración editada pero la lista de herramientas está desactualizada">
  El cliente almacenó en caché la configuración antigua. Cierra completamente y reinicia — no solo cierres la ventana. Claude Desktop en particular sigue ejecutándose en la barra de menú / bandeja del sistema.
</Accordion>

<Accordion title="Fallos específicos de Windows con `npx`">
  Si `npx` falla al iniciar el servidor en Windows, usa la forma envuelta en CMD:

  ```json theme={null}
  {
    "command": "cmd",
    "args": ["/c", "npx", "-y", "olostep-mcp"],
    "env": { "OLOSTEP_API_KEY": "YOUR_API_KEY" }
  }
  ```
</Accordion>

<Accordion title="`401 Missing Authorization: Bearer <OLOSTEP_API_KEY>`">
  Accediste al endpoint alojado sin un encabezado de autenticación (o con el formato incorrecto). Agrega el encabezado a la configuración de tu cliente exactamente como se muestra en la pestaña de configuración.
</Accordion>

## Recetas

Prompts para copiar y pegar que funcionan bien con las herramientas:

* **Raspar una lista de URLs de productos:** *"Tengo un CSV de 200 URLs de productos de Amazon. Ráspalos por lotes con `parser=@olostep/amazon-product` y devuelve como JSON."*
* **Rastrear un sitio de documentación:** *"Rastrea [https://stripe.com/docs](https://stripe.com/docs) con `max_pages=50` y `include_url_patterns=['/docs/**']`. Resume cada sección como markdown."*
* **Encontrar competidores:** *"Usa `answers` para encontrar los 5 principales competidores de Notion para sitios de documentación técnica. Devuelve nombre, página de inicio y una línea de posicionamiento."*
* **Mapear y luego raspar:** *"Ejecuta `create_map` en [https://example.com](https://example.com) filtrado a `/blog/**`, luego `batch_scrape_urls` en los 20 mejores resultados."*

## Fuente y versiones

* [Repositorio en GitHub](https://github.com/olostep/olostep-mcp-server)
* [Paquete npm](https://www.npmjs.com/package/olostep-mcp)
* [Docker Hub](https://hub.docker.com/r/olostep/mcp-server)
* [Registro MCP](https://registry.modelcontextprotocol.io/)