Norsk English (UK) English (US) Svenska Deutsch Français Español 中文 (简体)

// GUIDES

Isabyte MCP Server

Isabyte MCP Server

Un servidor autónomo de Model Context Protocol que convierte cualquier cliente de IA compatible con MCP en un experto en Isabyte Power Tools.

El Isabyte MCP Server integra todo el corpus de skills de Isabyte Power Tools en una imagen Linux ligera (~50 MB) y lo expone mediante el transporte Streamable-HTTP del Model Context Protocol. Conecta Claude Desktop, Cline, Cursor, Continue o cualquier otro cliente MCP y tu asistente de IA se convertirá en un especialista en Isabyte, con un conocimiento fundamentado de cada componente, parámetro y patrón del catálogo.

Un servidor, un catálogo. Los archivos de skills describen el propio sistema de diseño (el catálogo de componentes, los parámetros y los tokens de diseño comunes a todos los paquetes de Isabyte Power Tools), así que el mismo servidor le da una base sólida a tu asistente sea cual sea el paquete con el que trabajes.

Cómo ejecutarlo

  1. Descarga el zip y descomprímelo.
  2. Carga la imagen en tu motor de Docker local: bash load.sh
  3. Inicia el servidor: docker run --rm -p 7180:7180 isabyte-mcp-server:<version>
  4. Comprueba que funciona correctamente: curl http://localhost:7180/health devuelve {"status":"ok","skills":10}.
  5. Conecta cualquier cliente MCP a http://localhost:7180/mcp.

Configuración del cliente MCP

Cada cliente tiene su propio formato de configuración, y una clave incorrecta hace que el cliente ignore la entrada o recurra a un transporte más antiguo. En Cómo hacer que el servidor MCP funcione, más abajo, encontrarás la entrada exacta para cada cliente. La forma más habitual es esta, la que usa Cursor:

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

Los demás clientes difieren: VS Code usa la clave servers con "type": "http", Windsurf serverUrl, Gemini CLI httpUrl, Cline "type": "streamableHttp" y opencode una clave mcp con "type": "remote". Claude Code y OpenAI Codex añaden el servidor con un comando.

Una vez conectado, tu asistente puede leer todas las skills de Isabyte como recursos MCP (isabyte-skill://) o mediante las herramientas MCP list_isabyte_skills y read_isabyte_skill, que devuelven el mismo texto para los clientes que admiten herramientas pero no recursos. El prompt isabyte_expert_guidance inyecta todas las skills como contexto de referencia.

Seguridad

De forma predeterminada, el servidor escucha en 0.0.0.0 sin autenticación, lo cual está bien para un único puesto de trabajo local. Si el contenedor es accesible más allá de localhost:

  • Limítalo a localhost: -p 127.0.0.1:7180:7180
  • O exige un token bearer: -e MCP_AUTH_TOKEN="$(openssl rand -hex 24)" y añade "headers": { "Authorization": "Bearer YOUR_TOKEN" } a la configuración de tu cliente.

Cómo hacer que el servidor MCP funcione

Un agente de programación con IA necesita dos cosas para aprovechar bien el servidor: una conexión (el servidor en la configuración MCP de tu cliente) y un archivo de instrucciones en tu proyecto que le indique al agente cuándo usarlo. Sin el archivo de instrucciones, el agente ve el servidor pero no sabe que debe leer la documentación de Isabyte antes de escribir código de Isabyte, así que improvisa.

El archivo de instrucciones. Su contenido es el mismo para todos los clientes; solo cambian el nombre del archivo y la carpeta, así que descárgalo más abajo para tu cliente. Está en inglés a propósito: lo lee el agente, no tu equipo. Una descarga desde el navegador no puede crear carpetas, así que mueve el archivo a la ruta indicada para tu cliente. Si tu proyecto ya tiene un archivo con ese nombre, añade el contenido al final en lugar de sustituirlo. Los archivos de Cursor, Windsurf y Continue empiezan con una breve cabecera que hace que el cliente cargue el archivo en cada sesión; mantenla al principio del archivo.

Antes de empezar. El servidor debe estar en ejecución (consulta Cómo ejecutarlo). Todos los ejemplos siguientes lo registran con el nombre isabyte-expert en http://localhost:7180/mcp. Si iniciaste el servidor con MCP_AUTH_TOKEN, añade también la cabecera Authorization: Bearer de Seguridad en el campo de cabeceras de la configuración de tu cliente.

Recursos o herramientas: funciona de las dos formas. El servidor ofrece la documentación de Isabyte dos veces, con el mismo texto: como recursos MCP (isabyte-skill://…) y mediante dos herramientas MCP, list_isabyte_skills y read_isabyte_skill. Algunos clientes leen recursos, y todos los clientes siguientes pueden llamar a herramientas, así que el agente siempre tiene una forma de leer la documentación. El archivo de instrucciones le indica que use la herramienta cuando su cliente no puede leer recursos.

Un prompt de prueba para todos los clientes. Cuando el cliente esté conectado, abre una sesión nueva en tu proyecto y pide: "Añade un selector de fecha de Isabyte al formulario de registro." El agente debería leer isabyte-skill://isabyte-controls.md, o llamar a read_isabyte_skill para isabyte-controls, antes de escribir código. Si escribe código de Isabyte sin leer antes la documentación de Isabyte, el archivo de instrucciones no se está cargando.

Claude Code

Configuración MCP: este comando escribe .mcp.json en la raíz del proyecto, de modo que todo el que abra el proyecto obtiene el servidor:

claude mcp add --transport http --scope project isabyte-expert http://localhost:7180/mcp

Archivo de instrucciones: CLAUDE.md en la raíz del proyecto. Descargar CLAUDE.md

Comprueba que funciona: ejecuta /mcp en una sesión; isabyte-expert debería aparecer como conectado. Después usa el prompt de prueba.

Problemas habituales: la primera vez que Claude Code se inicia en el proyecto, te pide que apruebes los servidores de .mcp.json; si lo rechazaste, el servidor queda desactivado. Claude Code solo lee AGENTS.md cuando el proyecto no tiene CLAUDE.md, así que pon el contenido en CLAUDE.md.

OpenAI Codex

Configuración MCP: codex mcp add isabyte-expert --url http://localhost:7180/mcp, que añade esto a ~/.codex/config.toml:

[mcp_servers.isabyte-expert]
url = "http://localhost:7180/mcp"

Archivo de instrucciones: AGENTS.md en la raíz del proyecto. Descargar AGENTS.md

Comprueba que funciona: codex mcp list, o /mcp en la interfaz de terminal de Codex. Después usa el prompt de prueba.

Si iniciaste el servidor con MCP_AUTH_TOKEN, guarda el token en una variable de entorno y añade bearer_token_env_var = "ISABYTE_TOKEN" (el nombre de la variable) a la entrada; Codex lo envía como cabecera Authorization: Bearer.

Problemas habituales: un .codex/config.toml a nivel de proyecto solo se lee en un proyecto que hayas marcado como de confianza. La documentación de Codex no menciona los recursos MCP, así que el agente lee la documentación de Isabyte con las herramientas list_isabyte_skills y read_isabyte_skill. Si un resultado largo de una herramienta llega recortado, aumenta output_token_limit para read_isabyte_skill en config.toml, o pide al agente que lea la skill sección a sección.

GitHub Copilot

Configuración MCP: en VS Code, .vscode/mcp.json:

{
  "servers": {
    "isabyte-expert": {
      "type": "http",
      "url": "http://localhost:7180/mcp"
    }
  }
}

Archivo de instrucciones: .github/copilot-instructions.md. Descargar copilot-instructions.md

Comprueba que funciona: ejecuta MCP: List Servers desde la paleta de comandos; isabyte-expert debería estar en ejecución, y MCP: Browse Resources muestra sus recursos isabyte-skill://. Usa el prompt de prueba en modo agente.

Problemas habituales: este archivo usa la clave servers, no mcpServers. El agente en la nube de Copilot en GitHub.com se ejecuta en la nube, así que no puede acceder a un servidor en tu localhost. Solo usa herramientas MCP, no recursos; por eso, con un servidor al que sí pueda acceder, lee la documentación con list_isabyte_skills y read_isabyte_skill.

Cursor

Configuración MCP: .cursor/mcp.json en el proyecto:

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

Archivo de instrucciones: .cursor/rules/isabyte-mcp.mdc. Descargar isabyte-mcp.mdc

Comprueba que funciona: la sección MCP de la configuración de Cursor debería mostrar isabyte-expert activado; los errores de conexión aparecen en el panel Output, en "MCP Logs". Después usa el prompt de prueba.

Problemas habituales: una regla en .cursor/rules/ debe terminar en .mdc; un archivo .md normal en esa carpeta se ignora. Cursor también lee un AGENTS.md en la raíz del proyecto, así que, si tu proyecto ya tiene uno, puedes añadir el contenido ahí.

Windsurf

Configuración MCP: abre la sección MCPs desde el menú "…" de Cascade y edita la configuración en bruto (mcp_config.json):

{
  "mcpServers": {
    "isabyte-expert": {
      "serverUrl": "http://localhost:7180/mcp"
    }
  }
}

Archivo de instrucciones: .windsurf/rules/isabyte-mcp.md. Descargar isabyte-mcp.md

Comprueba que funciona: la sección MCPs debería mostrar isabyte-expert con sus herramientas y recursos. Después usa el prompt de prueba en Cascade.

Problemas habituales: Windsurf ahora se llama Devin Desktop. Sigue leyendo .windsurf/rules/, pero su agente predeterminado, Devin Local, lee los servidores MCP de .devin/mcp_config.json en lugar de la configuración de Cascade; añade ahí el servidor con devin mcp add -s project isabyte-expert http://localhost:7180/mcp. Un archivo de reglas puede contener como máximo 12.000 caracteres.

Gemini CLI

Configuración MCP: este comando escribe .gemini/settings.json en el proyecto:

gemini mcp add --transport http isabyte-expert http://localhost:7180/mcp

La entrada que escribe usa httpUrl:

{
  "mcpServers": {
    "isabyte-expert": {
      "httpUrl": "http://localhost:7180/mcp"
    }
  }
}

Archivo de instrucciones: GEMINI.md en la raíz del proyecto. Descargar GEMINI.md

Comprueba que funciona: ejecuta /mcp; isabyte-expert debería estar conectado, con sus herramientas y recursos listados. Después usa el prompt de prueba.

Problemas habituales: en settings.json, httpUrl significa Streamable HTTP, el transporte que usa este servidor; url significa el transporte SSE más antiguo y no conecta. Gemini CLI solo lee AGENTS.md si context.fileName lo incluye en su configuración, así que usa GEMINI.md. De forma predeterminada, Gemini CLI recorta los resultados de herramientas de más de 40.000 caracteres (tools.truncateToolOutputThreshold); la skill de Isabyte más grande es más larga, así que el agente debería leerla sección a sección (read_isabyte_skill admite un section).

Cline

Configuración MCP: en el panel MCP Servers, elige Configure → "Configure MCP Servers" y añade:

{
  "mcpServers": {
    "isabyte-expert": {
      "type": "streamableHttp",
      "url": "http://localhost:7180/mcp"
    }
  }
}

Archivo de instrucciones: .clinerules/isabyte-mcp.md. Descargar isabyte-mcp.md

Comprueba que funciona: el panel MCP Servers debería mostrar isabyte-expert como conectado, con las herramientas list_isabyte_skills y read_isabyte_skill. Después usa el prompt de prueba.

Problemas habituales: sin "type": "streamableHttp", Cline recurre al transporte SSE más antiguo y no puede conectarse. La documentación de Cline solo menciona de pasada los recursos MCP, así que el agente lee la documentación de Isabyte con las herramientas.

Continue

Configuración MCP: un archivo .continue/mcpServers/isabyte-expert.yaml:

name: Isabyte MCP server
version: 0.0.1
schema: v1
mcpServers:
  - name: isabyte-expert
    type: streamable-http
    url: http://localhost:7180/mcp

Archivo de instrucciones: .continue/rules/isabyte-mcp.md. Descargar isabyte-mcp.md

Comprueba que funciona: en modo agente, escribe @; los recursos de isabyte-expert deberían aparecer entre los proveedores de contexto. Después usa el prompt de prueba.

Problemas habituales: Continue solo usa servidores MCP en modo agente. El archivo YAML necesita sus líneas name, version y schema; de lo contrario, no se carga. La cabecera Authorization va en requestOptions: → headers: dentro de la entrada del servidor.

opencode

Configuración MCP: opencode.json en la raíz del proyecto:

{
  "mcp": {
    "isabyte-expert": {
      "type": "remote",
      "url": "http://localhost:7180/mcp",
      "enabled": true
    }
  }
}

Archivo de instrucciones: AGENTS.md en la raíz del proyecto, el mismo archivo que lee OpenAI Codex. Descargar AGENTS.md

Comprueba que funciona: opencode mcp list muestra si isabyte-expert está conectado. Después usa el prompt de prueba.

Problemas habituales: opencode solo lee CLAUDE.md cuando el proyecto no tiene AGENTS.md. Su documentación solo describe herramientas MCP, así que el agente lee la documentación de Isabyte con las herramientas list_isabyte_skills y read_isabyte_skill.

Claude Desktop

Claude Desktop no tiene archivo de instrucciones de proyecto. En un proyecto de Claude, pega en su lugar el contenido de cualquiera de las descargas anteriores en las instrucciones del proyecto. Sus conectores personalizados (Customize → Connectors → Add custom connector) se conectan desde la nube de Anthropic, no desde tu ordenador, así que no pueden acceder a un servidor en localhost: el servidor debe ser accesible por HTTPS desde internet.

Si sigue sin funcionar

  • curl http://localhost:7180/health falla: el servidor no está en ejecución.
  • La dirección debe terminar en /mcp.
  • El cliente devuelve 401: el servidor se inició con MCP_AUTH_TOKEN y el cliente no envía ninguna cabecera Authorization: Bearer, o envía un token incorrecto.
  • El agente escribe código de Isabyte sin leer la documentación de Isabyte (un recurso o read_isabyte_skill): el archivo de instrucciones no está en la ruta indicada para tu cliente, o no has iniciado una sesión nueva desde que lo añadiste.
  • Después de cambiar la configuración MCP de un cliente, reinicia el cliente o inicia una sesión nueva.
Se ha producido un error no controlado. Recargar 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please reload the page.