modal-workspace-mcp

Un puente MCP remoto que permite a GitHub Copilot, Copilot CLI y otros clientes MCP utilizar tu cuenta de Modal para ejecución en Linux, instalación de dependencias, operaciones de Git, trabajos de GPU y llamadas a Modal Functions desplegadas.

Este proyecto es deliberadamente un puente, no un IDE ni un espacio de trabajo de desarrollo alojado.

GitHub Copilot / MCP client
          |
          | Streamable HTTP MCP + Bearer token
          v
https://...modal.run/mcp/
          |
          v
modal-workspace-mcp gateway
          |
          +--> Modal Sandbox --> apt / git / curl / uv / pip / GPU / Internet
          |
          +--> deployed Modal Function

Herramientas V1

• sandbox_create — crear un Sandbox desacoplado con CPU/RAM/GPU configurables, paquetes apt/pip, política de red, Secrets y Volumes en lista de permitidos.

• sandbox_exec — ejecutar comandos bash -lc y devolver el código de salida/stdout/stderr.

• sandbox_status — comprobar si un Sandbox está en ejecución.

• sandbox_list — listar los Sandboxes gestionados por este MCP.

• sandbox_snapshot — crear una instantánea del sistema de archivos del Sandbox en una Modal Image.

• sandbox_terminate — terminar un Sandbox.

• function_call — invocar una Modal Function ya desplegada por nombre de app/función.

• app_get — resolver una Modal App por nombre y la URL del dashboard.

• app_list — listar Modal Apps a través de la interfaz CLI oficial modal app list --json.

Por qué esto resuelve el problema de DNS del contenedor de GitHub

El agente de GitHub no ejecuta apt, curl, git clone ni pip localmente. Solo realiza una solicitud HTTP MCP a tu endpoint de Modal. Las operaciones de red y shell reales ocurren dentro de un Modal Sandbox.

1. Configura el token del gateway

Genera un token aleatorio localmente:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Crea un Modal Secret llamado modal-workspace-mcp-auth que contenga ese valor:

modal secret create modal-workspace-mcp-auth MODAL_WORKSPACE_MCP_TOKEN='<generated-token>'

El mismo gateway Secret también puede contener configuración no secreta, como listas de permitidos, para que la Function desplegada la reciba como variables de entorno.

No hagas commit del token.

2. Opcional: permitir Secrets y Volumes de Sandbox

El MCP rechaza el montaje arbitrario de Secret/Volume de forma predeterminada. Configura listas de permitidos en la gateway Function si las necesitas.

Variables de entorno entendidas por el servidor:

MODAL_WORKSPACE_ALLOWED_SECRETS=github-agent,huggingface-agent
MODAL_WORKSPACE_ALLOWED_VOLUMES=model-cache,workspace-cache
MODAL_WORKSPACE_SANDBOX_APP=modal-workspace-sandboxes
MODAL_WORKSPACE_MAX_OUTPUT_CHARS=120000

Por ejemplo, crea credenciales como Modal Secrets separados:

modal secret create github-agent GH_TOKEN="$GH_TOKEN"
modal secret create huggingface-agent HF_TOKEN="$HF_TOKEN"

Luego actualiza el gateway Secret para que esos nombres de Secret estén explícitamente en la lista de permitidos (sus valores se mantienen en los Secrets separados):

modal secret create modal-workspace-mcp-auth \
  MODAL_WORKSPACE_MCP_TOKEN='<generated-token>' \
  MODAL_WORKSPACE_ALLOWED_SECRETS='github-agent,huggingface-agent'

3. Despliegue

Con Modal autenticado localmente:

uv sync
uv run modal deploy modal_app.py

Modal imprimirá la URL pública de Web Function. El endpoint de MCP es esa URL más /mcp/.

Comprobación de estado:

curl https://YOUR-ENDPOINT.modal.run/healthz

Para MCP Inspector:

npx @modelcontextprotocol/inspector

Usa Streamable HTTP, URL:

https://YOUR-ENDPOINT.modal.run/mcp/

y cabecera:

Authorization: Bearer <generated-token>

4. Agente en la nube de GitHub Copilot

Configura estos valores de Agents en el repositorio de GitHub de destino:

COPILOT_MCP_MODAL_URL=https://YOUR-ENDPOINT.modal.run
COPILOT_MCP_MODAL_GATEWAY_TOKEN=<generated-token>

Luego usa la configuración MCP del repositorio desde .mcp.json:

{
  "mcpServers": {
    "modal-workspace": {
      "type": "http",
      "url": "${COPILOT_MCP_MODAL_URL}/mcp/",
      "headers": {
        "Authorization": "Bearer ${COPILOT_MCP_MODAL_GATEWAY_TOKEN}"
      },
      "tools": [
        "sandbox_create",
        "sandbox_exec",
        "sandbox_status",
        "sandbox_list",
        "sandbox_snapshot",
        "sandbox_terminate",
        "function_call",
        "app_get",
        "app_list"
      ]
    }
  }
}

El agente en la nube de GitHub Copilot admite servidores MCP HTTP remotos y la sustitución de secrets/variables de Agents con prefijo COPILOT_MCP_. El MCP remoto basado en OAuth no se usa deliberadamente aquí; el gateway usa un token Bearer.

4A. Instalar como plugin de GitHub Copilot

Este repositorio es también un pequeño marketplace de plugins de Copilot. Después de publicarlo en GitHub, un repositorio de destino puede habilitar el plugin con .github/copilot/settings.json usando la plantilla en examples/github-copilot-settings.json:

{
  "enabledPlugins": {
    "modal-workspace@modal-workspace-mcp": true
  },
  "extraKnownMarketplaces": {
    "modal-workspace-mcp": {
      "source": {
        "source": "github",
        "repo": "xiaoqianran/modal-workspace-mcp"
      }
    }
  }
}

La entrada del marketplace apunta a plugins/modal-workspace/, cuyo .mcp.json conecta Copilot con el endpoint MCP HTTP de Modal desplegado. Para la primera depuración, también puedes configurar el mismo MCP remoto directamente en la configuración MCP de Copilot del repositorio antes de probar la instalación del plugin.

5. Primera prueba de extremo a extremo

Pide a Copilot que haga el equivalente de:

1. Call sandbox_create with timeout_seconds=1800.
2. Call sandbox_exec on the returned sandbox_id with:
   apt-get update && apt-get install -y ffmpeg && git --version && curl -I https://github.com
3. Return the exit code and the last part of stdout/stderr.
4. Call sandbox_terminate.

Una prueba más sólida:

Create a Modal Sandbox, clone a public GitHub repository into /root/repo,
install its dependencies, run its tests, report results, then terminate the Sandbox.
Do not use the local GitHub agent shell for network operations.

Modelo de seguridad

• El endpoint MCP HTTP requiere un token Bearer.

• El montaje de Secrets y Volumes de Sandbox está denegado por defecto y se basa en listas de permitidos.

• Los valores de Secret nunca se aceptan como argumentos de herramientas MCP.

• La salida se trunca para evitar respuestas MCP descontroladas.

• Los Sandboxes se etiquetan y aíslan bajo una Modal App dedicada.

• Mantén las operaciones destructivas dentro del Sandbox.

• Prefiere un token de GitHub dedicado con permisos mínimos de repositorio en lugar de un token personal con permisos amplios.

Validación local

El repositorio contiene pruebas auxiliares sin dependencias:

python -m unittest discover -s tests -v
python -m compileall modal_workspace_mcp modal_app.py

Las pruebas de integración completas de MCP/Modal requieren acceso a Internet y una cuenta de Modal autenticada.