modal-workspace-mcp

원격 MCP 브리지로, GitHub Copilot, Copilot CLI, 기타 MCP 클라이언트가 사용자의 Modal 계정을 Linux 실행, 의존성 설치, Git 작업, GPU 작업, 배포된 Modal Functions 호출에 사용할 수 있게 합니다.

이 프로젝트는 의도적으로 브리지이며, IDE나 호스팅 개발자 워크스페이스가 아닙니다.

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

V1 도구

• sandbox_create — 분리된 Sandbox를 생성하며 CPU/RAM/GPU, apt/pip 패키지, 네트워크 정책, 허용 목록에 등록된 Secrets 및 Volumes를 구성할 수 있습니다.

• sandbox_exec — bash -lc 명령을 실행하고 종료 코드/stdout/stderr를 반환합니다.

• sandbox_status — Sandbox가 실행 중인지 확인합니다.

• sandbox_list — 이 MCP가 관리하는 Sandbox 목록을 표시합니다.

• sandbox_snapshot — Sandbox 파일시스템을 Modal Image로 스냅샷합니다.

• sandbox_terminate — Sandbox를 종료합니다.

• function_call — 앱/함수 이름으로 이미 배포된 Modal Function을 호출합니다.

• app_get — 이름이 지정된 Modal App과 대시보드 URL을 확인합니다.

• app_list — 공식 modal app list --json CLI 인터페이스를 통해 Modal Apps를 나열합니다.

Related MCP server: MCP4Modal Sandbox

이것이 GitHub 컨테이너 DNS 문제를 해결하는 이유

GitHub 에이전트는 로컬에서 apt, curl, git clone 또는 pip를 실행하지 않습니다. Modal 엔드포인트로 MCP HTTP 요청을 보낼 뿐입니다. 실제 네트워크 및 셸 작업은 Modal Sandbox 내부에서 이루어집니다.

1. 게이트웨이 토큰 구성

로컬에서 임의의 토큰을 생성합니다:

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

해당 값을 포함하는 modal-workspace-mcp-auth라는 이름의 Modal Secret을 생성합니다:

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

동일한 게이트웨이 Secret은 허용 목록(allowlist)과 같은 비밀 정보가 아닌 구성도 담을 수 있으므로, 배포된 Function이 이를 환경 변수로 받습니다.

토큰을 커밋하지 마세요.

2. 선택사항: Sandbox Secrets 및 Volumes 허용

MCP는 기본적으로 임의의 Secret/Volume 마운트를 거부합니다. 필요한 경우 게이트웨이 Function에 허용 목록(allowlist)을 구성하세요.

서버가 인식하는 환경 변수:

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

예를 들어 자격 증명을 별도의 Modal Secrets로 생성합니다:

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

그런 다음 해당 Secret 이름이 명시적으로 허용 목록에 포함되도록 게이트웨이 Secret을 업데이트합니다 (해당 값은 여전히 별도의 Secrets에 보관됩니다):

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

3. 배포

로컬에서 Modal 인증을 완료한 상태에서:

uv sync
uv run modal deploy modal_app.py

Modal은 공개 Web Function URL을 출력합니다. MCP 엔드포인트는 해당 URL에 /mcp/를 붙인 것입니다.

상태 확인:

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

MCP Inspector의 경우:

npx @modelcontextprotocol/inspector

Streamable HTTP 사용, URL:

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

그리고 헤더:

Authorization: Bearer <generated-token>

4. GitHub Copilot 클라우드 에이전트

대상 GitHub 저장소에서 다음 Agents 값을 구성합니다:

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

그런 다음 .mcp.json의 저장소 MCP 구성을 사용합니다:

{
  "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"
      ]
    }
  }
}

GitHub Copilot 클라우드 에이전트는 원격 HTTP MCP 서버와 COPILOT_MCP_ 접두사가 붙은 Agents 비밀/변수 치환을 지원합니다. 여기서는 OAuth 기반 원격 MCP를 의도적으로 사용하지 않습니다. 게이트웨이는 Bearer 토큰을 사용합니다.

4A. GitHub Copilot 플러그인으로 설치

이 저장소는 또한 작은 Copilot 플러그인 마켓플레이스입니다. GitHub에 게시한 후, 대상 저장소는 examples/github-copilot-settings.json의 템플릿을 사용하여 .github/copilot/settings.json으로 플러그인을 활성화할 수 있습니다:

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

마켓플레이스 항목은 plugins/modal-workspace/를 가리키며, 해당 디렉터리의 .mcp.json은 Copilot을 배포된 Modal HTTP MCP 엔드포인트에 연결합니다. 첫 디버깅을 위해 플러그인 설치를 테스트하기 전에 동일한 원격 MCP를 저장소의 Copilot MCP 설정에 직접 구성할 수도 있습니다.

5. 첫 엔드투엔드 테스트

Copilot에게 다음에 해당하는 작업을 요청하세요:

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.

더 강력한 테스트:

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.

보안 모델

• HTTP MCP 엔드포인트는 Bearer 토큰을 요구합니다.

• Sandbox Secret 및 Volume 마운트는 기본적으로 거부되며 허용 목록(allowlist) 기반입니다.

• Secret 값은 MCP 도구 인수로 절대 허용되지 않습니다.

• 출력은 MCP 응답의 폭주를 방지하기 위해 잘립니다.

• Sandbox는 전용 Modal App 아래에서 태그가 지정되고 격리됩니다.

• 파괴적인 작업은 Sandbox 내부에서만 수행하세요.

• 광범위한 개인 토큰보다 최소한의 저장소 권한을 가진 전용 GitHub 토큰을 사용하세요.

로컬 검증

이 저장소에는 의존성이 없는 헬퍼 테스트가 포함되어 있습니다:

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

전체 MCP/Modal 통합 테스트에는 인터넷 액세스와 인증된 Modal 계정이 필요합니다.