CH 12 · Conectar con el ecosistema MCP

Word count~4,900 wordsTime~20 minPrereqCH 03–05 already runningLevelReproducible

Objetivo del capítulo

Las herramientas integradas de dsh (leer archivos, ejecutar comandos, buscar en la web) bastan para el día a día, pero fuera hay un montón de herramientas dispersas — GitHub, bases de datos, memoria, navegadores, todo tipo de SaaS — no caen solas en tu Agent. Este capítulo enchufa el ecosistema MCP: primero explica qué es MCP, por qué dsh usa un "plugin" para conectarse, y luego conecta en la práctica el servidor MCP de Firecrawl, para que el modelo pueda llamar a sus herramientas como si fueran nativas.

Primero entender: qué es MCP

MCP (Model Context Protocol) es un protocolo abierto que resuelve el problema general de "cómo se conectan las aplicaciones de IA a servidores externos de herramientas". Puedes pensar en MCP como el USB-C del mundo de las herramientas: una interfaz estándar, y puedes enchufar cualquier dispositivo.

El ecosistema MCP ya cuenta con un buen lote de servidores MCP listos:

Servidor MCP	Qué hace
Sistema de archivos	Lee/escribe subdirectorios (expone un directorio local al Agent)
GitHub	Crear issues, abrir PRs, consultar repos
Base de datos	Consultar varias bases de datos
Memoria	Acceso a memoria a largo plazo (volverás a verlo en CH 14)
Navegador	Controlar el navegador, scrapear páginas

La forma de enchufar MCP a dsh va totalmente en línea con su estilo — un plugin: @deepseek-ai/dsh-mcp-client. La función de este plugin oficial es pura: conecta cada servidor MCP que declares y registra las herramientas que proveen en ctx.tools (el registro de herramientas mencionado en CH 11), de modo que a los ojos del modelo no se diferencian de las herramientas nativas. Esto vuelve a confirmar el "todo es un plugin" de CH 08 — la integración de MCP no es la excepción.

Algunos puntos que conviene saber de antemano:

• El nombre de las herramientas es de dos niveles: primero está el servidor MCP (p. ej. Firecrawl) y debajo tiene un lote de herramientas (firecrawl_scrape scrapear página, firecrawl_search buscar, firecrawl_map listar sitemap...). Tras enchufarse, cada herramienta aparece como mcp__<server-name>__<tool-name> — si el servidor se llama firecrawl, su herramienta de scrape es mcp__firecrawl__firecrawl_scrape. Esto coincide con el formato de nombres de Claude Code y Codex. Distintos servidores pueden compartir nombres sin chocar (cada uno tiene su propio prefijo).
• Por defecto no hay ningún servidor habilitado: que el plugin esté instalado es una cosa; a qué servidores conectarse depende por completo de lo que declares. Sin configuración, no se conecta a nada. Una vez declarado, el servidor conectará al arrancar dsh y sus herramientas se registrarán en la lista de herramientas; en cuanto a qué ronda llama a qué herramienta, el modelo decide por sí mismo según la tarea actual — no llama a todas las herramientas cada vez.
• Por ahora solo se puentean las "tools": además de "tools" (Tool, acciones invocables), el protocolo MCP tiene otras dos capacidades — "Resources" (Resource, datos y archivos de solo lectura) y plantillas de "Prompt" (Prompt). El plugin puente de dsh por ahora solo trae las "tools"; los resources y las plantillas de prompt aún no se pueden usar.
• Muchos servidores requieren autenticación: los servidores MCP que se conectan a servicios reales, como GitHub y Firecrawl, suelen necesitar una API Key o token. Las claves se pasan a través del campo headers en la configuración (método HTTP), no las hardcodes en el archivo de configuración — la sección de configuración de abajo amplía esto.

Manos a la obra: conecta tu primer servidor MCP — Firecrawl

A continuación, Firecrawl (un servicio MCP real de web scraping, sitio de Firecrawl) te guía paso a paso. Su servidor MCP ofrece un lote de herramientas web: firecrawl_scrape (scrapear una sola página), firecrawl_search (buscar en la web), firecrawl_map (listar sitemap), firecrawl_crawl (rastrear un sitio entero), firecrawl_extract (extraer campos estructurados), etc.

Paso 1: confirma que el plugin MCP Client está disponible

Primero confirma si dsh-mcp-client está ahí. No hace falta la línea de comandos; mira directamente la lista de plugins en la Web UI: abre Ajustes → Plugins y busca mcp. La imagen de abajo es mi resultado — al escribir mcp en el buscador, la lista de plugins está vacía ("no matching plugins"), lo que significa que no está instalado:

Si no lo encuentras en la lista, vuelve a la línea de comandos e instálalo como dependencia del profile web:

dsh plugin --profile web add @deepseek-ai/dsh-mcp-client

Atención: este comando solo lo empaqueta como dependencia del profile (dsh plugin list --profile web muestra la dependencia), no arranca por sí solo — para que el plugin se cargue realmente necesitas insertarlo en cordis.patch.yml en el paso 3 y configurar los servidores. Hay un escollo de prueba real: si solo insertas el plugin sin configurar el servidor, el arranque de dsh fallará directamente con Cannot read properties of undefined (reading 'serverName') porque serverName es un campo obligatorio.

Tras configurar y reabrir dsh, vuelve a Ajustes → Plugins y verás mcp-client, estado "enabled" (la imagen de abajo es tras la instalación, con el buscador aún mostrando mcp, la lista de plugins con 1 elemento, estado enabled):

Paso 2: obtén una API Key de Firecrawl

Firecrawl requiere autenticación. Entra en el sitio de Firecrawl, regístrate y crea una API Key — el uso oficial es enviarla como token Bearer a https://mcp.firecrawl.dev/v2/mcp. El plan gratuito tiene 1000 créditos al mes.

La imagen de abajo es la página donde la creé: a la izquierda puedes ver los créditos restantes, en el centro la key por defecto listada (prefijo fc-, mitad censurada), arriba a la derecha + Create:

Tras obtener la key, primero configúrala como variable de entorno del sistema (la configuración del paso 3 la referenciará). Aclaro una cosa: las variables de entorno no se escriben en un archivo de texto; son una "lista" mantenida uniformemente en la UI del sistema Windows; la interfaz de ajustes añade una entrada a esa lista. En Windows, usa la GUI; no hacen falta comandos:

1. Pulsa la tecla Win, escribe "environment variables", abre Edit the system environment variables
2. Pulsa el botón Environment Variables abajo a la derecha

3. En la sección User variables pulsa New: en variable name escribe FIRECRAWL_API_KEY, en variable value escribe fc-your-full-key

4. Pulsa OK en todas las ventanas para cerrarlas

Atención: tras configurar, abre una terminal nueva para arrancar dsh — las ventanas ya abiertas no releen automáticamente las nuevas variables de entorno.

Paso 3: declara Firecrawl en la configuración del Profile

La configuración del servidor MCP se escribe en el archivo patch del profile web (el cordis.patch.yml de CH 08):

• Windows: C:\Users\<your-username>\.dsh\profiles\web\cordis.patch.yml
• macOS / Linux: ~/.dsh/profiles/web/cordis.patch.yml

Añade un servidor a la lista insert, usando el método streamable-http recomendado oficialmente (conectar a un endpoint remoto):

En cada entrada insert, serverName es obligatorio (el error de arranque del paso 1 fue por estar vacío) — es el namespace para los nombres de herramientas y decide cómo queda mcp__<aquí>__tool.

El endpoint remoto oficial de Firecrawl es https://mcp.firecrawl.dev/v2/mcp, autenticado con token Bearer:

- insert:
    - id: mcp-firecrawl
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: firecrawl
        transport: streamable-http
        url: https://mcp.firecrawl.dev/v2/mcp
        headers:
          Authorization: !!js '`Bearer ${process.env.FIRECRAWL_API_KEY}`'

La clave se referencia a través de la variable de entorno (process.env.FIRECRAWL_API_KEY), no se hardcodea directamente en el archivo (mira en el paso 2 cómo se configura la variable) — si el archivo se sube a Git podría filtrarse. Para enchufar otros servidores MCP más adelante, basta con añadir otra entrada insert con este mismo formato.

Descripción de los campos más habituales:

Campo	Significado
serverName	Namespace del nombre de herramienta (mcp__<aquí>__tool), 1–32 caracteres alfanuméricos con guion bajo, único en su ámbito
transport	stdio (programa local) o streamable-http (servicio remoto)
command / args / env	Ejecutable, argumentos, variables de entorno extra para stdio
url / headers	Dirección del endpoint HTTP y cabeceras extra de la petición (aquí va el token de auth)
toolCallTimeoutMs	Timeout por llamada de herramienta (por defecto 60 segundos)
reconnect	Política de reconexión al desconectar (por defecto activado, backoff inicial 500ms duplicando, tope 30s, se rinde tras 10 fallos consecutivos)

Tras editar y guardar, el archivo tiene este aspecto — la sección insert recién añadida aparece resaltada:

Paso 4: reinicia y deja que el modelo llame

Reabre dsh y espera a que termine de arrancar. Las herramientas de Firecrawl no tienen una "página de lista de herramientas" dedicada para que las consultes; la forma más directa de confirmar es dejar que el modelo las use una vez:

1. En la sesión, envía: Use Firecrawl to scrape the main content of deepseek.com
2. Observa la respuesta del modelo y la Trayectoria: si la conexión tiene éxito, el modelo llamará a mcp__firecrawl__firecrawl_scrape, aparece una fila TOOL en la Trayectoria y el panel derecho muestra el parámetro url y el resultado markdown scrapeado

3. Si la herramienta no aparece, el modelo dirá explícitamente "I don't have this scraping tool here", o simplemente volverá a la búsqueda web integrada — ambas cosas indican que el servidor no está conectado; vuelve a la sección anterior para diagnosticar

¿Quieres ahorrar trabajo? Instala dos plugins de la comunidad

La build oficial no tiene ni una página de "lista de herramientas" ni una entrada de "explorar plugins"; la comunidad ha cubierto esos dos huecos, ambos con un solo comando:

① Marketplace de plugins dsh-market (987 stars): tras instalarlo, en Ajustes aparece un nuevo "Plugin Market" donde puedes navegar por categorías, buscar e instalar plugins de la comunidad con un clic. La mayoría de los plugins instalados desde el marketplace surten efecto solo con refrescar la página, sin necesidad de reiniciar dsh:

dsh plugin --profile web add dshmarket

② Panel de visualización MCP DSH Skill & MCP Panel (108 stars): tras instalarlo, en Ajustes aparece una nueva "MCP Management"; puedes ver directamente el estado y el número de herramientas de cada servidor, añadir/quitar/editar, arrancar/parar todo desde la UI sin editar cordis.patch.yml. No hace falta escribir comandos — busca directamente dsh-skill-mcp-panel en el marketplace ①, instala con un clic, surte efecto al refrescar la página (algunos plugins a nivel de host indicarán "restart required", sigue las instrucciones):

Estos dos plugins son exactamente la nota a pie de aquella frase al inicio de este capítulo — todo es un plugin: capacidades oficiales de la UI que no existen, los plugins de la comunidad las cubren, y una vez instalados pasan a formar parte de dsh.

Hay muchas más claves sobre cómo instalar y gestionar plugins — instalación por línea de comandos, auto-montaje por bundle, global vs Profile. Este capítulo solo abre una ventana en el escenario MCP; más adelante habrá un capítulo entero que cubrirá sistemáticamente la instalación de plugins, después el desarrollo de plugins, y enlazará hasta la práctica con escenarios.

Preguntas frecuentes

Problema	Cómo manejarlo
Conectado pero no ves la herramienta	Primero mira los logs en busca de errores de conexión/descubrimiento; confirma que el servidor en sí es accesible (usa un navegador o curl para probar el endpoint directamente); confirma que serverName no choca con el de otro servidor; en servidores con auth, comprueba que la clave se pasa correctamente (401/403 suele ser esto)
¿Dónde van las claves de servicios como Firecrawl?	Pásalas vía headers en la configuración (método HTTP), define la clave como variable de entorno antes de arrancar (paso 2), no la hardcodes en cordis.patch.yml — si el archivo se sube a Git podría filtrarse
¿Qué pasa si el servidor se cae?	El plugin reconecta solo (backoff inicial 500ms duplicando), las herramientas siguen listadas durante la reconexión pero las llamadas fallarán; tras 10 fallos consecutivos se eliminan las herramientas hasta recargar configuración o reiniciar. Editar la configuración recarga las conexiones de los servidores en caliente, los nombres que no cambien se mantienen
¿Consume demasiados tokens?	La descripción y el input schema de cada servidor entran en cada petición. Conecta solo lo que realmente uses; no acumules un montón

Qué aprendiste en este capítulo

Apruebas si puedes completar los siguientes puntos:

• [ ] Explicar qué hace MCP y cómo se enchufa en dsh (un plugin dsh-mcp-client)
• [ ] Saber que el nombre de las herramientas es de dos niveles: un servidor MCP tiene varias herramientas, tras enchufarse aparecen como mcp__server-name__tool-name
• [ ] Saber cómo se pasan las claves de servidores MCP que requieren auth (como Firecrawl) y por qué no se hardcodean en el archivo de configuración
• [ ] Poder declarar un servidor MCP en cordis.patch.yml (al menos uno entre stdio o streamable-http)
• [ ] Hacer que el modelo llame de verdad a una herramienta MCP y ver en la Trayectoria la llamada con el prefijo mcp__
• [ ] Cuando el servidor no conecte o se caiga, saber dónde mirar los errores y cómo diagnosticarlos
• [ ] Saber que, por comodidad, puedes instalar dos plugins de la comunidad: dsh-market (Plugin Market) y DSH Skill & MCP Panel (visualización MCP)