gpu-broker-mcp

AI 에이전트를 위한 GPU 컴퓨팅 액세스를 중개하는 상태 비저장(stateless) MCP 서버입니다. 에이전트는 SSH 키, 노드 IP, 공급자 API를 직접 관리하지 않고도 네 가지 MCP 도구를 통해 노드를 발견하고, 용량을 예약하고, 추론을 디스패치하고, 결과를 폴링합니다.

SDK: mcp==2.0.0 (Python SDK v2, mcp.server.MCPServer) 대상 사양: MCP 사양 개정판 2026-07-28 전송: 스트리밍 가능한 HTTP, 상태 비저장 모드(stateless_http=True, json_response=True). 세션 없음, Mcp-Session-Id 없음, 고정 라우팅 없음.

아키텍처

┌─────────────────────────────────────────────────────────────┐
│  Agent (MCP client)                                         │
│  Calls: list_nodes → reserve_node → dispatch_inference      │
│         → get_result (poll)                                 │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC over Streamable HTTP
                         │ (stateless, any replica)
┌────────────────────────▼────────────────────────────────────┐
│  gpu-broker-mcp server                                      │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │ HMAC-SHA256       │  │ NodePool ABC     │                 │
│  │ Handle signing    │  │  ├ FakeNodePool   │                │
│  │ & validation      │  │  └ VastNodePool   │                │
│  └──────────────────┘  └──────────────────┘                 │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │ Error taxonomy    │  │ JobStore ABC     │                 │
│  │ (single enum,     │  │  └ InMemoryStore  │                │
│  │  structured JSON) │  │    (per-replica)  │                │
│  └──────────────────┘  └──────────────────┘                 │
└────────────────────────┬────────────────────────────────────┘
                         │ SSH (VastNodePool only)
┌────────────────────────▼────────────────────────────────────┐
│  GPU node (e.g. Vast.ai RTX 3090)                           │
│  Runs inference workload, returns stdout                    │
└─────────────────────────────────────────────────────────────┘

브로커는 로컬에서 실행됩니다. 브로커는 GPU 노드의 클라이언트이지 노드에 상주하지 않습니다. CPU 바운드 HMAC 서명과 JSON 직렬화를 수행하며 GPU의 이점을 얻을 수 있는 작업은 없습니다.

Related MCP server: clausius

서명된 핸들 대신 세션이 아닌 이유

예약 상태는 핸들 자체에 포함됩니다. base64로 인코딩된 JSON 페이로드(노드 ID, 만료 시간, 범위)와 HMAC-SHA256 서명이 연결된 형태입니다. 비밀은 GPU_BROKER_SECRET에서 가져오며 설정되지 않으면 서버가 부팅을 거부합니다.

즉, 비밀을 공유하는 모든 복제본은 자체적으로 발급하지 않은 핸들도 검증할 수 있습니다. 세션 테이블, Mcp-Session-Id 헤더, 고정 라우팅 요구 사항이 없습니다. 로드 밸런서는 모든 요청을 모든 복제본으로 라우팅할 수 있습니다. 핸들에는 범위(reserve 대 task)가 있으므로 예약 핸들을 작업 ID로 재생할 수 없으며 그 반대의 경우도 마찬가지입니다. 잘못 사용하면 HANDLE_SCOPE_INVALID가 반환됩니다.

메모리 내 JobStore가 복제본 간에 손실하는 것은 작업 상태 조회입니다. 복제본 B는 복제본 A에 디스패치된 작업의 상태를 알려줄 수 없습니다. 이는 상태 비저장 설계의 결함이 아니라 공유 백엔드(Redis, Postgres) 요구 사항입니다. 보안에 중요한 서명 검증은 완전히 이식 가능합니다.

도구

도구 서명은 백엔드에서 안정적입니다. FakeNodePool을 VastNodePool로 교체해도 클라이언트에 표시되는 인터페이스는 변경되지 않습니다.

캐싱 참고 사항

list_nodes는 도구 결과에 meta.ttlMs 및 meta.cacheScope를 반환합니다. 이는 로컬 규칙입니다. SEP-2549는 개별 tools/call 결과가 아닌 tools/list 및 resources/list 응답을 규율합니다. 이를 인식하는 클라이언트는 캐시할 수 있고, 그렇지 않은 클라이언트는 단순히 다시 호출합니다.

라우팅 헤더

서버는 게이트웨이 라우팅을 위해 Mcp-Method 및 Mcp-Name 헤더를 내보내지만 서버 측에서 강제하지는 않습니다. 적용 지점은 브로커 자체가 아니라 에지(API 게이트웨이, 리버스 프록시)입니다.

오류 분류

모든 도구 오류는 code, message, retryable 및 선택적 retry_after_seconds가 포함된 구조화된 JSON을 반환합니다. 에이전트는 message가 아닌 code를 기준으로 분기해야 합니다. 메시지는 사람이 읽을 수 있는 진단 정보이며 변경될 수 있습니다.

호스트 수준 오류(NVML_VERSION_MISMATCH ~ DOCKER_SOCKET_PERMISSION_DENIED)는 vast.py:_raise_from_stderr의 SSH stderr 문자열에서 매핑됩니다. 패턴은 Vast.ai GPU 호스트의 알려진 오류 모드를 기반으로 하지만 아직 캡처된 프로덕션 문자열에 대해 검증되지는 않았습니다. 작업 3에서는 축어적 오류 출력을 캡처하고 일치 패턴을 구체화합니다.

빠른 시작

페이크 모드 (GPU, API 키 불필요)

export GPU_BROKER_SECRET="any-secret-string"
python src/gpu_broker/server.py
# Server at http://127.0.0.1:8000/mcp

Vast.ai 모드 (실제 GPU)

export GPU_BROKER_SECRET="any-secret-string"
export VASTAI_API_KEY="your-vast-api-key"

# Find and rent a node
python vast_manage.py search --gpu "RTX 3090" --max-price 0.30
python vast_manage.py rent <offer_id>
python vast_manage.py wait <instance_id>

# Start the broker (auto-detects VASTAI_API_KEY)
python src/gpu_broker/server.py

# When done
python vast_manage.py destroy <instance_id>

테스트 실행

uv run pytest tests/ -v

테스트에는 다음이 포함됩니다.

• 핸들 왕복 (예약 → 디스패치 → get_result)

• 변조된 서명 거부

• 만료된 핸들 거부

• 범위 불일치 거부

• 교차 복제본 조회에 대한 JOB_NOT_FOUND

• 하위 프로세스 상태 비저장 테스트: 세 개의 실제 HTTP 서버(A와 B는 비밀을 공유하고 C는 다른 비밀을 가짐)를 부팅하고, A에서 작업을 발행하고, A가 pending을 반환하고 B가 JOB_NOT_FOUND를 반환하고 C가 HANDLE_SIGNATURE_INVALID를 반환하는지 확인

• 비밀 미설정 부팅 거부

• 모든 오류 변형에 대한 직렬화 왕복

현재 범위 및 제한 사항

이것은 프로덕션 시스템이 아닌 작동하는 프로토타입입니다.

• FakeNodePool은 세 노드의 정적 목록을 반환하며 실제 추론을 디스패치하지 않습니다. 도구 상호 작용 및 핸들 메커니즘을 테스트하는 데 유용합니다.

• VastNodePool은 Vast.ai API를 쿼리하여 실행 중인 인스턴스를 찾고 SSH를 통해 추론을 디스패치합니다. 실제 작업을 수행하지만 연결 풀링, 재시도 논리 또는 시스템 기본값 이상의 SSH 키 관리는 없습니다.

• InMemoryJobStore는 다시 시작하면 모든 상태를 잃고 복제본 간에 작업 상태를 공유할 수 없습니다. 프로덕션 배포에는 공유 백엔드(Redis, Postgres)가 필요합니다.

• 호스트 수준 오류에 대한 오류 분류 패턴은 알려진 오류 모드를 기반으로 한 추측입니다. GPU 호스트에서 캡처된 실제 stderr에 대한 검증이 필요합니다.

• MCP 엔드포인트 자체에는 인증이 없습니다. HTTP 포트에 도달할 수 있는 모든 클라이언트가 도구를 호출할 수 있습니다. 프로덕션에서는 앞에 인증 계층이 필요합니다.

• 속도 제한, 요청 크기 제한, 감사 로깅이 없습니다.