MCP Proxy Server

Agrega múltiples servidores de recursos MCP en una única interfaz con soporte stdio/sse.

GitHub
193
Prueba este MCPPatrocinado

Documentación

MCP Proxy Server

Chino simplificado

✨ Características clave destacadas

  • 🌐 Gestión mediante interfaz web: Administre fácilmente todos los servidores MCP conectados a través de una interfaz web intuitiva (opcional, requiere habilitación).
  • 🔧 Control granular de herramientas: Habilite o deshabilite herramientas individuales y sobrescriba nombres/descripciones mediante la interfaz web.
  • 🛡️ Autenticación flexible de endpoints: Proteja sus endpoints basados en HTTP (/sse, /mcp) con opciones de autenticación flexibles (Authorization: Bearer <token> o X-API-Key: <key>).
  • 🔄 Manejo robusto de sesiones y concurrencia:
    • Manejo mejorado de sesiones SSE para reconexiones de clientes (dependiendo de los eventos endpoint enviados por el servidor) y soporte para conexiones concurrentes.
    • El endpoint HTTP transmisible (/mcp) también admite interacciones concurrentes de clientes.
  • 🚀 Operaciones MCP versátiles (Servidor y Proxy):
    • Actúa como proxy: Se conecta y agrega múltiples servidores MCP backend de varios tipos (Stdio, SSE, HTTP transmisible).
    • Actúa como servidor: Expone estas capacidades agregadas a través de sus propios endpoints HTTP transmisible (/mcp) y SSE (/sse). También puede ejecutarse en modo Stdio puro.
  • ✨ Salida de instalación en tiempo real: Supervise el progreso de instalación de servidores Stdio (stdout/stderr) directamente en la interfaz web.
  • ✨ Terminal web: Acceda a una terminal de línea de comandos dentro de la interfaz de administración para interacción directa con el servidor (opcional, usar con precaución debido a riesgos de seguridad).

Este servidor actúa como un centro central para los servidores de recursos del Protocolo de Contexto de Modelo (MCP). Puede:

  • Conectarse y gestionar múltiples servidores MCP backend (tipos Stdio, SSE y HTTP transmisible).
  • Exponer sus capacidades combinadas (herramientas, recursos) a través de una interfaz SSE unificada, una interfaz HTTP transmisible o actuar como un único servidor MCP basado en Stdio.
  • Manejar el enrutamiento de solicitudes a los servidores backend apropiados.
  • Agregar respuestas si es necesario (aunque principalmente actúa como proxy).
  • Soportar múltiples conexiones SSE simultáneas de clientes con autenticación opcional mediante clave API.

Características

Gestión de recursos y herramientas mediante proxy

  • Descubre y se conecta a múltiples servidores de recursos MCP definidos en config/mcp_server.json.
  • Agrega herramientas y recursos de todos los servidores activos conectados.
  • Enruta las llamadas a herramientas y las solicitudes de acceso a recursos al servidor backend correcto.
  • Mantiene esquemas de URI consistentes.

✨ Interfaz web de administración opcional (ENABLE_ADMIN_UI=true)

Proporciona una interfaz basada en navegador para gestionar la configuración del servidor proxy y las herramientas conectadas. Las características incluyen:

  • Configuración del servidor: Ver, agregar, editar y eliminar entradas de servidor (mcp_server.json). Admite tipos de servidor Stdio, SSE y HTTP con opciones relevantes (tipo, comando, argumentos, entorno, URL, clave API, token portador, configuración de instalación).
  • Configuración de herramientas: Ver todas las herramientas descubiertas de los servidores backend activos. Habilitar o deshabilitar herramientas específicas. Sobrescribir el nombre mostrado y la descripción de cada herramienta (tool_config.json).
  • Recarga en vivo: Aplicar cambios de configuración de servidores y herramientas activando una recarga de configuración sin necesidad de reiniciar todo el proceso del servidor proxy.
  • Instalación de servidores Stdio: Para servidores Stdio, puede definir comandos de instalación en la configuración. La interfaz de administración le permite:
    • Activar la ejecución de estos comandos de instalación.
    • Supervisar el progreso de instalación en tiempo real con salida en vivo de stdout y stderr transmitida directamente a la interfaz.
  • Terminal web: Acceder a una terminal integrada basada en web que proporciona acceso shell al entorno donde se ejecuta el servidor proxy.
    • Advertencia de seguridad: Esta característica otorga un acceso significativo y debe usarse con extrema precaución, especialmente si la interfaz de administración está expuesta.

Configuración

La configuración se realiza principalmente mediante variables de entorno y archivos JSON ubicados en el directorio ./config.

1. Conexiones de servidor (config/mcp_server.json)

Este archivo define los servidores MCP backend a los que el proxy debe conectarse.

Ejemplo de config/mcp_server.json:

{
  "mcpServers": {
    "unique-server-key1": {
      "type": "stdio",
      "name": "My Stdio Server",
      "active": true,
      "command": "/path/to/server/executable",
      "args": ["--port", "1234"],
      "env": {
        "API_KEY": "server_specific_key"
      },
      "installDirectory": "/custom_install_path/unique-server-key1",
      "installCommands": [
        "git clone https://github.com/some/repo unique-server-key1",
        "cd unique-server-key1 && npm install && npm run build"
      ]
    },
    "another-sse-server": {
      "type": "sse",
      "name": "My SSE Server",
      "active": true,
      "url": "http://localhost:8080/sse",
      "apiKey": "sse_server_api_key"
    },
    "http-mcp-server": {
      "type": "http",
      "name": "My Streamable HTTP Server",
      "active": true,
      "url": "http://localhost:8081/mcp",
      "bearerToken": "some_secure_token_for_http_server"
    },
    "stdio-default-install": {
        "type": "stdio",
        "name": "Stdio Server with Default Install Path",
        "active": true,
        "command": "my_other_server",
        "installCommands": ["echo 'Installing to default location...'"]
    }
  }
}

Campos:

  • mcpServers: (Requerido) Un objeto donde cada clave es un identificador único para un servidor backend.
  • name: (Opcional) Un nombre mostrado amigable para el servidor (usado en la interfaz de administración).
  • active: (Opcional, predeterminado: true) Establecer a false para evitar que el proxy se conecte a este servidor.
  • type: (Requerido) Especifica el tipo de transporte. Debe ser uno de "stdio", "sse" o "http".
  • command: (Requerido si type es "stdio") El comando para ejecutar el proceso del servidor.
  • args: (Opcional si type es "stdio") Una matriz de argumentos de cadena para pasar al comando.
  • env: (Opcional si type es "stdio") Un objeto de variables de entorno (KEY: "value") para establecer para el proceso del servidor. Se fusionan con el entorno del servidor proxy.
  • url: (Requerido si type es "sse" o "http") La URL completa del endpoint del servidor backend (por ejemplo, endpoint SSE para "sse", endpoint MCP para "http").
  • apiKey: (Opcional si type es "sse" o "http") Una clave API para enviar en el encabezado X-Api-Key cuando el proxy se conecta a este backend específico.
  • bearerToken: (Opcional si type es "sse" o "http") Un token para enviar en el encabezado Authorization: Bearer <token> al conectarse a este backend específico. (Si se proporcionan tanto apiKey como bearerToken, bearerToken generalmente tiene prioridad para esa conexión backend específica).
  • installDirectory: (Opcional si type es "stdio") La ruta absoluta donde el servidor en sí debe instalarse (por ejemplo, /opt/my-server-files). Usado por la función de instalación de la interfaz de administración.
    • Si se proporciona en mcp_server.json, se usa esta ruta exacta.
    • Si se omite, el directorio efectivo depende de la variable de entorno TOOLS_FOLDER (consulte la sección Variables de entorno).
      • Si TOOLS_FOLDER está establecido y no está vacío, el servidor se instalará en un subdirectorio con el nombre de la clave del servidor dentro de esta carpeta (por ejemplo, ${TOOLS_FOLDER}/<server_key>).
      • Si TOOLS_FOLDER también está vacío o no está establecido, se predetermina a un subdirectorio tools dentro del directorio de trabajo del servidor proxy (por ejemplo, ./tools/<server_key>).
    • Asegúrese de que el directorio padre de la ruta de instalación objetivo (por ejemplo, TOOLS_FOLDER o ./tools) sea escribible por el usuario que ejecuta el servidor proxy.
  • installCommands: (Opcional para tipo Stdio) Una matriz de comandos shell ejecutados secuencialmente por la función de instalación de la interfaz de administración si el directorio del servidor objetivo (derivado de installDirectory o valores predeterminados) no existe. Los comandos se ejecutan desde el directorio padre del directorio de instalación del servidor objetivo (por ejemplo, si installDirectory se resuelve a /opt/tools/my-server, los comandos se ejecutan en /opt/tools/). Usar con extrema precaución debido a riesgos de seguridad.

2. Configuración de herramientas (config/tool_config.json)

Este archivo permite sobrescribir propiedades de herramientas descubiertas de servidores backend. Se gestiona principalmente mediante la interfaz de administración, pero puede editarse manualmente.

Ejemplo de config/tool_config.json:

{
  "tools": {
    "unique-server-key1__tool-name-from-server": {
      "enabled": true,
      "displayName": "My Custom Tool Name",
      "description": "A more user-friendly description."
    },
    "another-sse-server__another-tool": {
      "enabled": false
    }
  }
}
  • Las claves tienen el formato <server_key><separator><original_tool_name>, donde <separator> es el valor de la variable de entorno SERVER_TOOLNAME_SEPERATOR (predeterminado: __).
  • enabled: (Opcional, predeterminado: true) Establecer a false para ocultar esta herramienta de los clientes que se conectan al proxy.
  • displayName: (Opcional) Sobrescribir el nombre de la herramienta en las interfaces de cliente.
  • description: (Opcional) Sobrescribir la descripción de la herramienta.

3. Variables de entorno

  • PORT: Puerto para los endpoints basados en HTTP del servidor proxy (/sse, /mcp y la interfaz de administración si está habilitada). Predeterminado: 3663. Nota: Esto solo se usa cuando se ejecuta en un modo que inicia un servidor HTTP (por ejemplo, mediante npm run dev:sse o el contenedor Docker). El script npm run dev se ejecuta en modo Stdio.

    export PORT=8080

  • ALLOWED_KEYS: (Opcional) Lista separada por comas de claves API para proteger los endpoints basados en HTTP del proxy (/sse, /mcp). Si ni ALLOWED_KEYS ni ALLOWED_TOKENS están establecidos, la autenticación está deshabilitada para estos endpoints. Los clientes deben proporcionar una clave mediante el encabezado X-Api-Key o el parámetro de consulta ?key=.

    export ALLOWED_KEYS="client_key1,client_key2"

  • ALLOWED_TOKENS: (Opcional) Lista separada por comas de tokens portadores para proteger los endpoints basados en HTTP del proxy (/sse, /mcp). Si ni ALLOWED_KEYS ni ALLOWED_TOKENS están establecidos, la autenticación está deshabilitada. Los clientes deben proporcionar un token mediante el encabezado Authorization: Bearer <token>. Si tanto ALLOWED_KEYS como ALLOWED_TOKENS están configurados, se intentará primero la autenticación con token portador.

    export MCP_PROXY_SSE_ALLOWED_TOKENS="your_bearer_token_1,your_bearer_token_2"

  • ENABLE_ADMIN_UI: (Opcional) Establecer a true para habilitar la interfaz web de administración (solo aplicable en modo SSE). Predeterminado: false.

    export ENABLE_ADMIN_UI=true

  • ADMIN_USERNAME: (Requerido si la interfaz de administración está habilitada) Nombre de usuario para el inicio de sesión de la interfaz de administración. Predeterminado: admin.

  • ADMIN_PASSWORD: (Requerido si la interfaz de administración está habilitada) Contraseña para el inicio de sesión de la interfaz de administración. Predeterminado: password (¡Cámbiela!).

    export ADMIN_USERNAME=myadmin
export ADMIN_PASSWORD=aVerySecurePassword123!

  • SESSION_SECRET: (Opcional, recomendado si la interfaz de administración está habilitada) Secreto utilizado para firmar las cookies de sesión. Si no se establece, se usa un secreto predeterminado menos seguro y se emite una advertencia. Se genera automáticamente un secreto seguro y se guarda en config/.session_secret en el primer inicio si no se proporciona mediante variable de entorno.

    # Recommended: Generate a strong secret (e.g., openssl rand -hex 32)
export SESSION_SECRET='your_very_strong_random_secret_here'

  • TOOLS_FOLDER: (Opcional) Especifica el directorio base para las instalaciones de servidores Stdio iniciadas mediante la interfaz de administración, usado cuando installDirectory no está establecido explícitamente en mcp_server.json para un servidor específico.

    • Si se establece (por ejemplo, /custom/tools_path), las instalaciones para servidores sin un installDirectory específico se dirigirán a un subdirectorio con el nombre de la clave del servidor dentro de esta carpeta (por ejemplo, ${TOOLS_FOLDER}/<server_key>).
    • Si TOOLS_FOLDER no está establecido o está vacío, dichas instalaciones se predeterminarán a un subdirectorio tools dentro del directorio de trabajo del servidor proxy (por ejemplo, ./tools/<server_key>).
    • El Dockerfile establece esto a /tools de forma predeterminada.
    export TOOLS_FOLDER=/srv/mcp_tools

  • SERVER_TOOLNAME_SEPERATOR: (Opcional) Define el separador utilizado para combinar el nombre del servidor y el nombre de la herramienta al generar la clave única para las herramientas (por ejemplo, server-key__tool-name). Esta clave se usa internamente y en el archivo tool_config.json.

    • Predeterminado: __.
    • Debe tener al menos 2 caracteres y contener solo letras (a-z, A-Z), números (0-9), guiones (-) y guiones bajos (_).
    • Si el valor proporcionado no es válido, se usará el predeterminado (__) y se registrará una advertencia.
    export SERVER_TOOLNAME_SEPERATOR="___" # Example: using triple underscore

  • LOGGING: (Opcional) Controla el nivel mínimo de registro de salida del servidor.

    • Valores posibles (sin distinción de mayúsculas/minúsculas): error, warn, info, debug.
    • Se mostrarán los registros en el nivel especificado y todos los niveles superiores.
    • Predeterminado: info.
    export LOGGING="debug"

  • RETRY_SSE_TOOL_CALL: (Opcional) Controla si se habilitan los reintentos para llamadas de herramientas SSE. Establézcalo en "true" para habilitar, "false" para deshabilitar. Predeterminado: true. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export RETRY_SSE_TOOL_CALL="true"

  • SSE_TOOL_CALL_MAX_RETRIES: (Opcional) Número máximo de intentos de reintento para llamadas de herramientas SSE (después del fallo inicial). Predeterminado: 2. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export SSE_TOOL_CALL_MAX_RETRIES="2"

  • SSE_TOOL_CALL_RETRY_DELAY_BASE_MS: (Opcional) Retraso base en milisegundos para los reintentos de llamadas de herramientas SSE, utilizado en la retrocesión exponencial. Predeterminado: 300. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="300"

  • RETRY_HTTP_TOOL_CALL: (Opcional) Controla si se reintenta en caso de errores de conexión de llamadas de herramientas HTTP. Establézcalo en "true" para habilitar, "false" para deshabilitar. Predeterminado: true. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export RETRY_HTTP_TOOL_CALL="true"

  • HTTP_TOOL_CALL_MAX_RETRIES: (Opcional) Número máximo de intentos de reintento para llamadas de herramientas HTTP (después del fallo inicial). Predeterminado: 2. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export HTTP_TOOL_CALL_MAX_RETRIES="3"

  • HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS: (Opcional) Retraso base en milisegundos para los reintentos de llamadas de herramientas HTTP, utilizado en la retrocesión exponencial. Predeterminado: 300. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

  • RETRY_STDIO_TOOL_CALL: (Opcional) Controla si se reintenta en caso de errores de conexión de llamadas de herramientas Stdio (intenta reiniciar el proceso). Establézcalo en "true" para habilitar, "false" para deshabilitar. Predeterminado: true. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export RETRY_STDIO_TOOL_CALL="true"

  • STDIO_TOOL_CALL_MAX_RETRIES: (Opcional) Número máximo de intentos de reintento para llamadas de herramientas Stdio (después del fallo inicial). Predeterminado: 2. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export STDIO_TOOL_CALL_MAX_RETRIES="5"

  • STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS: (Opcional) Retraso base en milisegundos para los reintentos de llamadas de herramientas Stdio, utilizado en la retrocesión exponencial. Predeterminado: 300. Consulte la sección "Funciones de confiabilidad mejorada" para más detalles.

    export STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS="1000"

Funciones de confiabilidad mejorada

MCP Proxy Server incluye funciones para mejorar su resiliencia y la confiabilidad de las interacciones con los servicios MCP de backend, garantizando operaciones más fluidas y una ejecución de herramientas más consistente.

1. Propagación de errores

El servidor proxy garantiza que los errores originados en los servicios MCP de backend se propaguen de manera consistente al cliente solicitante. Estos errores se formatean como respuestas de error JSON-RPC estándar, lo que facilita que los clientes los manejen de manera uniforme.

2. Reintento de llamadas de herramientas SSE

Cuando se realiza una operación tools/call a un servidor backend basado en SSE, y la conexión subyacente se pierde o experimenta un error (incluidos los tiempos de espera), el servidor proxy implementa un mecanismo de reintento.

Mecanismo de reintento: Si una llamada de herramienta SSE inicial falla debido a un error de conexión o un tiempo de espera, el proxy intentará restablecer la conexión con el backend SSE. Si el restablecimiento es exitoso, reintentará la solicitud tools/call original utilizando una estrategia de retrocesión exponencial, similar a los reintentos de HTTP y Stdio. Esto significa que el retraso antes de cada intento de reintento posterior aumenta exponencialmente, con una pequeña cantidad de jitter (aleatoriedad) añadida.

Configuración: Estos ajustes se controlan principalmente mediante variables de entorno. Los valores en config/mcp_server.json dentro del objeto proxy para estas claves específicas serán anulados por las variables de entorno si están configuradas.

  • RETRY_SSE_TOOL_CALL (variable de entorno):

    • Establézcalo en "true" para habilitar los reintentos para llamadas de herramientas SSE.
    • Establézcalo en "false" para deshabilitar esta función.
    • Comportamiento predeterminado: true (si la variable de entorno no está configurada, está vacía o tiene un valor no válido).

  • SSE_TOOL_CALL_MAX_RETRIES (variable de entorno):

    • Especifica el número máximo de intentos de reintento después del intento fallido inicial. Por ejemplo, si se establece en "2", habrá un intento inicial y hasta dos intentos de reintento, totalizando un máximo de tres intentos.
    • Comportamiento predeterminado: 2 (si la variable de entorno no está configurada, está vacía o no es un entero válido).

  • SSE_TOOL_CALL_RETRY_DELAY_BASE_MS (variable de entorno):

    • El retraso base en milisegundos utilizado en el cálculo de retrocesión exponencial. El retraso antes del n-ésimo reintento (indexado desde 0) es aproximadamente SSE_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Comportamiento predeterminado: 300 (milisegundos) (si la variable de entorno no está configurada, está vacía o no es un entero válido).

Ejemplo (Variables de entorno):

export RETRY_SSE_TOOL_CALL="true"
export SSE_TOOL_CALL_MAX_RETRIES="3"
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

3. Reintento de solicitudes HTTP para llamadas de herramientas

Para operaciones tools/call dirigidas a servidores backend basados en HTTP, el proxy implementa un mecanismo de reintento para errores de conexión (por ejemplo, "fallo al obtener", tiempos de espera de red).

Mecanismo de reintento: Si una solicitud HTTP inicial falla debido a un error de conexión, el proxy reintentará la solicitud utilizando una estrategia de retrocesión exponencial. Esto significa que el retraso antes de cada intento de reintento posterior aumenta exponencialmente, con una pequeña cantidad de jitter (aleatoriedad) añadida para prevenir escenarios de avalancha (thundering herd).

Configuración: Estos ajustes se controlan principalmente mediante variables de entorno.

  • RETRY_HTTP_TOOL_CALL (variable de entorno):

    • Establézcalo en "true" para habilitar los reintentos para llamadas de herramientas HTTP.
    • Establézcalo en "false" para deshabilitar esta función.
    • Comportamiento predeterminado: true (si la variable de entorno no está configurada, está vacía o tiene un valor no válido).

  • HTTP_TOOL_CALL_MAX_RETRIES (variable de entorno):

    • Especifica el número máximo de intentos de reintento después del intento fallido inicial. Por ejemplo, si se establece en "2", habrá un intento inicial y hasta dos intentos de reintento, totalizando un máximo de tres intentos.
    • Comportamiento predeterminado: 2 (si la variable de entorno no está configurada, está vacía o no es un entero válido).

  • HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS (variable de entorno):

    • El retraso base en milisegundos utilizado en el cálculo de retrocesión exponencial. El retraso antes del n-ésimo reintento (indexado desde 0) es aproximadamente HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Comportamiento predeterminado: 300 (milisegundos) (si la variable de entorno no está configurada, está vacía o no es un entero válido).

4. Reintento de conexión Stdio para llamadas de herramientas

Para operaciones tools/call dirigidas a servidores backend basados en Stdio, el proxy implementa un mecanismo de reintento para errores de conexión (por ejemplo, cierre del proceso o falta de respuesta).

Mecanismo de reintento: Si una conexión Stdio inicial o una llamada de herramienta falla, el proxy intentará reiniciar el proceso Stdio y reintentar la solicitud. Este mecanismo sigue una estrategia de retrocesión exponencial similar a los reintentos de HTTP.

Configuración: Estos ajustes se controlan principalmente mediante variables de entorno.

  • RETRY_STDIO_TOOL_CALL (variable de entorno):

    • Establézcalo en "true" para habilitar los reintentos de llamadas de herramientas Stdio.
    • Establézcalo en "false" para deshabilitar esta función.
    • Comportamiento predeterminado: true (si la variable de entorno no está configurada, está vacía o tiene un valor no válido).

  • STDIO_TOOL_CALL_MAX_RETRIES (variable de entorno):

    • Especifica el número máximo de intentos de reintento después del intento fallido inicial. Por ejemplo, si se establece en "2", habrá un intento inicial y hasta dos intentos de reintento, totalizando un máximo de tres intentos.
    • Comportamiento predeterminado: 2 (si la variable de entorno no está configurada, está vacía o no es un entero válido).

  • STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS (variable de entorno):

    • El retraso base en milisegundos utilizado en el cálculo de retrocesión exponencial. El retraso antes del n-ésimo reintento (indexado desde 0) es aproximadamente STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Comportamiento predeterminado: 300 (milisegundos) (si la variable de entorno no está configurada, está vacía o no es un entero válido).

Notas generales sobre el análisis de variables de entorno:

  • Las variables de entorno booleanas (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) se consideran true si su valor en minúsculas es exactamente "true". Cualquier otro valor (incluido vacío o no configurado) da como resultado la aplicación del valor predeterminado o false si el valor predeterminado es false (aunque para estas variables específicas, el valor predeterminado es true).
  • Las variables de entorno numéricas (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) se analizan como enteros en base 10. Si el análisis falla (por ejemplo, el valor no es un número, o la variable está vacía o no está configurada), se utiliza el valor predeterminado.

Desarrollo

MCP Proxy Server incluye funciones para mejorar su resiliencia y la confiabilidad de las interacciones con los servicios MCP de backend, garantizando operaciones más fluidas y una ejecución de herramientas más consistente.

1. Propagación de errores

El servidor proxy garantiza que los errores originados en los servicios MCP de backend se propaguen de manera consistente al cliente solicitante. Estos errores se formatean como respuestas de error JSON-RPC estándar, lo que facilita que los clientes los manejen de manera uniforme.

2. Reintento de conexión SSE para llamadas de herramientas

Cuando se realiza una operación tools/call a un servidor backend basado en SSE, y la conexión subyacente se pierde o experimenta un error, el servidor proxy intentará automáticamente:

  1. Restablecer la conexión con el backend SSE.
  2. Si el restablecimiento es exitoso, reintentará la solicitud tools/call original una vez.

Este comportamiento ayuda a mitigar problemas de red transitorios que podrían interrumpir temporalmente las conexiones SSE.

Configuración: Esta función se controla principalmente mediante la variable de entorno RETRY_SSE_TOOL_CALL_ON_DISCONNECT.

  • RETRY_SSE_TOOL_CALL_ON_DISCONNECT (variable de entorno):
    • Establézcalo en "true" para habilitar la reconexión y el reintento automáticos.
    • Establézcalo en "false" para deshabilitar esta función.
    • Comportamiento predeterminado: true (si la variable de entorno no está configurada, está vacía o tiene un valor no válido).
    • Nota: Si este ajuste también está presente en config/mcp_server.json dentro de proxy, la variable de entorno tiene prioridad.

Ejemplo (Variable de entorno):

export RETRY_SSE_TOOL_CALL_ON_DISCONNECT="true"

(El ejemplo JSON para mcp_server.json en "Configuración de comportamiento del proxy" ilustra dónde podrían ir otros ajustes del proxy, pero este ajuste específico se gestiona mejor mediante su variable de entorno.)

3. Reintento de solicitudes HTTP para llamadas de herramientas

Para operaciones tools/call dirigidas a servidores backend basados en HTTP, el proxy implementa un mecanismo de reintento para errores de conexión (por ejemplo, "fallo al obtener", tiempos de espera de red).

Mecanismo de reintento: Si una solicitud HTTP inicial falla debido a un error de conexión, el proxy reintentará la solicitud utilizando una estrategia de retrocesión exponencial. Esto significa que el retraso antes de cada intento de reintento posterior aumenta exponencialmente, con una pequeña cantidad de jitter (aleatoriedad) añadida para prevenir escenarios de avalancha (thundering herd).

Configuración: Estos ajustes se controlan principalmente mediante variables de entorno. Los valores en config/mcp_server.json dentro del objeto proxy para estas claves específicas serán anulados por las variables de entorno si están configuradas.

  • RETRY_HTTP_TOOL_CALL (variable de entorno):

    • Establézcalo en "true" para habilitar los reintentos para llamadas de herramientas HTTP.
    • Establézcalo en "false" para deshabilitar esta función.
    • Comportamiento predeterminado: true (si la variable de entorno no está configurada, está vacía o tiene un valor no válido).

  • HTTP_TOOL_CALL_MAX_RETRIES (variable de entorno):

    • Especifica el número máximo de intentos de reintento después del intento inicial fallido. Por ejemplo, si se establece en "2", habrá un intento inicial y hasta dos reintentos, totalizando un máximo de tres intentos.
    • Comportamiento predeterminado: 2 (si la variable de entorno no está establecida, está vacía o no es un entero válido).

  • HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS (variable de entorno):

    • El retraso base en milisegundos utilizado en el cálculo de retroceso exponencial. El retraso antes del n-ésimo reintento (indexado desde 0) es aproximadamente HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Comportamiento predeterminado: 300 (milisegundos) (si la variable de entorno no está establecida, está vacía o no es un entero válido).

Notas generales sobre el análisis de variables de entorno:

  • Las variables de entorno booleanas (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) se consideran true si su valor en minúsculas es exactamente "true". Cualquier otro valor (incluyendo vacío o no establecido) da como resultado que se aplique el valor predeterminado o false si el valor predeterminado es false (aunque para estas variables específicas, el valor predeterminado es true).
  • Las variables de entorno numéricas (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) se analizan como enteros en base 10. Si el análisis falla (por ejemplo, el valor no es un número, o la variable está vacía o no establecida), se utiliza el valor predeterminado.

Ejemplo (variables de entorno):

export RETRY_HTTP_TOOL_CALL="true"
export HTTP_TOOL_CALL_MAX_RETRIES="3"
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

4. Reintento de conexión Stdio para llamadas a herramientas

Para operaciones tools/call dirigidas a servidores backend basados en Stdio, el proxy implementa un mecanismo de reintento para errores de conexión (por ejemplo, caída del proceso o falta de respuesta).

Mecanismo de reintento: Si una conexión Stdio inicial o una llamada a herramienta falla, el proxy intentará reiniciar el proceso Stdio y reintentar la solicitud. Este mecanismo sigue una estrategia de retroceso exponencial similar a los reintentos HTTP.

Configuración: Estos ajustes se controlan principalmente mediante variables de entorno.

  • RETRY_STDIO_TOOL_CALL (variable de entorno):

    • Establecer en "true" para habilitar los reintentos de llamadas a herramientas Stdio.
    • Establecer en "false" para deshabilitar esta función.
    • Comportamiento predeterminado: true (si la variable de entorno no está establecida, está vacía o tiene un valor no válido).

  • STDIO_TOOL_CALL_MAX_RETRIES (variable de entorno):

    • Especifica el número máximo de intentos de reintento después del intento inicial fallido. Por ejemplo, si se establece en "2", habrá un intento inicial y hasta dos reintentos, totalizando un máximo de tres intentos.
    • Comportamiento predeterminado: 2 (si la variable de entorno no está establecida, está vacía o no es un entero válido).

  • STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS (variable de entorno):

    • El retraso base en milisegundos utilizado en el cálculo de retroceso exponencial. El retraso antes del n-ésimo reintento (indexado desde 0) es aproximadamente STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
    • Comportamiento predeterminado: 300 (milisegundos) (si la variable de entorno no está establecida, está vacía o no es un entero válido).

Notas generales sobre el análisis de variables de entorno:

  • Las variables de entorno booleanas (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) se consideran true si su valor en minúsculas es exactamente "true". Cualquier otro valor (incluyendo vacío o no establecido) da como resultado que se aplique el valor predeterminado o false si el valor predeterminado es false (aunque para estas variables específicas, el valor predeterminado es true).
  • Las variables de entorno numéricas (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) se analizan como enteros en base 10. Si el análisis falla (por ejemplo, el valor no es un número, o la variable está vacía o no establecida), se utiliza el valor predeterminado.

Desarrollo

Instalar dependencias:

npm install
# or yarn install

Compilar el servidor (compila TypeScript a JavaScript en build/):

npm run build

Ejecutar en modo de desarrollo (usa tsx para ejecución directa de TS con reinicio automático en cambios):

# Run as a Stdio MCP server (default mode)
npm run dev

# Run as an SSE MCP server (enables SSE endpoint and Admin UI if configured)
# Ensure environment variables (PORT, ENABLE_ADMIN_UI etc.) are set as needed
ENABLE_ADMIN_UI=true npm run dev:sse

Observar cambios y recompilar automáticamente (útil si no se usa tsx):

npm run watch

Ejecución con Docker

Se proporciona un Dockerfile. El contenedor ejecuta el servidor en modo SSE por defecto (usando build/sse.js) e incluye todas las dependencias necesarias. La variable de entorno TOOLS_FOLDER tiene como valor predeterminado /tools dentro del contenedor.

Recomendado: Usar la imagen precompilada (desde GHCR)

Se recomienda usar la imagen precompilada del Registro de Contenedores de GitHub para una configuración más sencilla. Proporcionamos dos tipos de imágenes:

  1. Imagen estándar (ligera): Esta es la imagen predeterminada y recomendada para la mayoría de los usuarios. Contiene la funcionalidad principal del MCP Proxy Server.

    • Etiquetas: latest, <version> (por ejemplo, 0.1.2)
    # Pull the latest standard image
docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

# Or pull a specific version
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:0.1.2

  2. Imagen empaquetada (completa): Esta imagen incluye un conjunto de servidores MCP preinstalados y dependencias del navegador Playwright. Es significativamente más grande, pero proporciona acceso inmediato a herramientas comunes.

    • Etiqueta: <version>-bundled-mcpservers-playwright (por ejemplo, 0.1.2-bundled-mcpservers-playwright) o latest-bundled-mcpservers-playwright
    # Pull a bundled version
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest-bundled-mcpservers-playwright

    La imagen empaquetada incluye los siguientes componentes preinstalados (a través de argumentos de compilación de Docker):

    • Paquetes PIP (PRE_INSTALLED_PIP_PACKAGES_ARG):
      • mcp-server-time
      • markitdown-mcp
      • mcp-proxy
    • Paquetes NPM (PRE_INSTALLED_NPM_PACKAGES_ARG):
      • g-search-mcp
      • fetcher-mcp
      • playwright
      • time-mcp
      • mcp-trends-hub
      • @adenot/mcp-google-search
      • edgeone-pages-mcp
      • @modelcontextprotocol/server-filesystem
      • mcp-server-weibo
      • @variflight-ai/variflight-mcp
      • @baidumap/mcp-server-baidu-map
      • @modelcontextprotocol/inspector
    • Comando de inicialización (PRE_INSTALLED_INIT_COMMAND_ARG):
      • playwright install --with-deps chromium

Elija el tipo de imagen que mejor se adapte a sus necesidades. Para la mayoría de los usuarios, la imagen estándar es suficiente, y los servidores MCP backend se pueden configurar a través de mcp_server.json.

Luego, ejecute la imagen de contenedor elegida:

docker run -d \
  -p 3663:3663 \
  -e PORT=3663 \
  -e ENABLE_ADMIN_UI=true \
  -e ADMIN_USERNAME=myadmin \
  -e ADMIN_PASSWORD=yoursupersecretpassword \
  -e ALLOWED_KEYS="clientkey1" \
  -e TOOLS_FOLDER=/my/custom_tools_volume # Optional: Override default /tools for server installations
  -v ./my_config:/mcp-proxy-server/config \
  -v /path/on/host/to/tools:/my/custom_tools_volume `# Mount a volume for TOOLS_FOLDER if overridden` \
  --name mcp-proxy-server \
  ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest
  • Reemplace ./my_config con la ruta de su host que contiene mcp_server.json y opcionalmente tool_config.json. El contenedor espera archivos de configuración en /app/config.
  • Si sobrescribe TOOLS_FOLDER para instalaciones de servidores a través de la interfaz de administración, asegúrese de montar un volumen correspondiente (por ejemplo, -v /path/on/host/for_tools:/my/custom_tools_volume). Si usa el valor predeterminado /tools (establecido por TOOLS_FOLDER en el Dockerfile), puede montar en /tools (por ejemplo, -v /path/on/host/to/tools_default:/tools).
  • Ajuste la etiqueta (:latest) si ha extraído una versión específica.
  • Establezca otras variables de entorno usando la bandera -e según sea necesario.

Compilar la imagen localmente (opcional):

docker build -t mcp-proxy-server .

(Si compila localmente, use mcp-proxy-server en lugar del nombre de imagen ghcr.io/... en el comando docker run anterior).

Instalación y uso con clientes

Este servidor proxy se puede usar de dos maneras principales:

1. Como servidor MCP Stdio: Configure su cliente MCP (como Claude Desktop) para ejecutar el servidor proxy directamente usando su comando (build/index.js). El proxy se conectará entonces a los servidores backend definidos en su config/mcp_server.json.

Ejemplo para Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-proxy": {
      "name": "MCP Proxy (Aggregator)",
      "command": "/path/to/mcp-proxy-server/build/index.js",
      "env": {
         "NODE_ENV": "production", // Optional: Set environment for the proxy itself
         "TOOLS_FOLDER": "/custom/path/for/proxy/tools" // Optional: If proxy needs to install its own backends
      }
    }
  }
}
  • Reemplace /path/to/mcp-proxy-server/build/index.js con la ruta real al punto de entrada compilado de este proyecto de servidor proxy. Asegúrese de que el directorio config esté ubicado correctamente en relación con el lugar desde donde se ejecuta el comando, o use rutas absolutas en la configuración del propio proxy si es necesario.

2. Como servidor MCP SSE o HTTP transmisible (Streamable HTTP): Ejecute el servidor proxy en un modo que inicie su servidor HTTP (por ejemplo, npm run dev:sse o el contenedor Docker). Luego, configure su cliente MCP para conectarse al endpoint apropiado del proxy: - Para SSE: http://localhost:3663/sse - Para HTTP transmisible: http://localhost:3663/mcp

Si la autenticación está habilitada en el proxy (a través de ALLOWED_KEYS o ALLOWED_TOKENS), el cliente debe proporcionar las credenciales correspondientes.

Métodos de autenticación (para /sse y /mcp):

  • Clave API: Proporcione la clave en la configuración del cliente. Para el endpoint /sse, se admite el parámetro de consulta de URL ?key=.... Para ambos /sse y /mcp, se admite el encabezado X-Api-Key.
  • Token Bearer: Establezca el encabezado Authorization: Bearer <token> en la configuración del cliente.

Ejemplo para Claude Desktop (claude_desktop_config.json) conectándose a SSE:

{
  "mcpServers": {
    "my-proxy-sse": {
      "type": "sse", // Important for clients that distinguish
      "name": "MCP Proxy (SSE)",
      // If using API Key authentication, append ?key=<your_key>
      "url": "http://localhost:3663/sse?key=clientkey1"
      // If using Bearer Token authentication, the client configuration method may vary.
      // For example, some clients might support setting custom headers:
      // "headers": {
      //   "Authorization": "Bearer your_bearer_token_1"
      // }
    }
  }
}

Ejemplo para una configuración genérica de cliente HTTP transmisible:

{
  "mcpServers": {
    "my-proxy-http": {
      "type": "http", // Or the client's specific designation
      "name": "MCP Proxy (Streamable HTTP)",
      "url": "http://localhost:3663/mcp",
      // Authentication headers would be configured according to the client's capabilities
      // e.g., "requestInit": { "headers": { "X-Api-Key": "clientkey1" } }
    }
  }
}

Depuración

Use el Inspector MCP para depurar la comunicación (principalmente para el modo Stdio):

npm run inspector

Este script envuelve la ejecución del servidor compilado (build/index.js) con el inspector. Acceda a la interfaz del inspector a través de la URL proporcionada en la salida de la consola. Para el modo SSE, se pueden usar las herramientas de desarrollo estándar del navegador para inspeccionar las solicitudes de red.

Referencia

Este proyecto fue originalmente inspirado y refactorizado a partir de adamwattis/mcp-proxy-server.