MCP 엔드포인트¶

Backend.AI GO는 MCP(Model Context Protocol) 서버로 동작할 수 있습니다. Claude Code, Claude Desktop, Codex CLI, IDE 연동 같은 외부 MCP 클라이언트가 하나의 HTTP 엔드포인트에 연결해 Backend.AI GO의 내장 도구(파일 검색, 셸·Python 실행, 웹 페치, Data Hub 접근 등)를 호출합니다.

이는 Backend.AI GO가 원격 MCP 서버에 클라이언트로 접속하는 설정 > 도구 및 확장 > MCP 서버와는 반대 방향입니다. MCP 엔드포인트는 Backend.AI GO 자체를 서버로 만듭니다. MCP Streamable HTTP 트랜스포트(프로토콜 리비전 2025-03-26)를 사용하며 주소는 다음과 같습니다.

POST http://127.0.0.1:8001/api/v1/mcp

포트는 관리 API 서버 포트(기본 8001)입니다. MCP 엔드포인트 카드에는 서버가 지금 실제로 수신 중인 주소가 표시되므로, URL은 직접 입력하지 말고 카드에서 복사하세요.

엔드포인트 활성화¶

엔드포인트는 기본적으로 꺼져 있습니다. 비활성 상태에서는 /api/v1/mcp가 404 Not Found로 응답하므로 기본 설치 상태에서는 아무것도 노출되지 않습니다.

API > 관리 API에서 MCP 엔드포인트 활성화를 켭니다. 관리 API 서버가 꺼져 있었다면 엔드포인트를 제공하는 관리 API 서버도 함께 켜집니다.
카드에 표시된 연결 URL을 복사합니다. URL은 서버가 실제로 수신 중일 때만 표시됩니다. 서버가 꺼져 있거나 시작에 실패한 경우(예: 포트가 이미 사용 중)에는 그 상태를 대신 보여주며, 바로 위의 관리 API 서버 카드에서 해결할 수 있습니다.
포트 변경, API 키 요구, 다른 기기에서의 접근 허용은 같은 탭의 관리 API 서버 카드에서 설정합니다.

관리 API 서버와 MCP 엔드포인트는 별개의 스위치입니다. MCP 엔드포인트를 켜면 서버 없이는 엔드포인트가 동작할 수 없으므로 서버도 함께 켜집니다. MCP 엔드포인트를 끄더라도 서버는 다른 클라이언트를 위해 계속 실행되며, API > 관리 API에서 서버를 끄면 MCP 토글은 켜진 채로 남지만 서버가 다시 켜질 때까지 엔드포인트는 접근 불가로 표시됩니다.

Claude Code 연결¶

API 키 필요(API > 관리 API)가 켜져 있으면 요청에 API > 액세스 키에서 발급한 액세스 키를 X-API-Key 헤더로 담아야 합니다.

claude mcp add --transport http backend-ai-go http://127.0.0.1:8001/api/v1/mcp \
  --header "X-API-Key: <액세스-키>"

API 키 필요가 꺼져 있으면(localhost 바인딩의 기본값) --header 플래그를 생략합니다. 카드의 Claude Code 명령은 현재 설정을 이미 반영하고 있습니다.

이후 Claude Code 세션 안에서 확인합니다.

/mcp

backend-ai-go 서버가 연결된 상태로 표시되고 도구 목록을 사용할 수 있어야 합니다. Streamable HTTP 트랜스포트를 지원하는 다른 MCP 클라이언트도 동일하게 URL과 X-API-Key 헤더만 지정하면 됩니다.

노출되는 도구¶

엔드포인트는 앱 자체 에이전트가 사용하는 내장 도구 카탈로그를 그대로 광고하되, 이 트랜스포트에서 실제로 실행 가능한 도구만 노출합니다.

데스크톱 앱 셸이 필요한 도구(클립보드, 알림, 음성 전사, 이미지 생성, 메모리 뱅크, load_model이나 list_downloads 같은 AppControl 도구)는 광고하지 않습니다. 이 도구들은 HTTP 트랜스포트가 갖고 있지 않은 데스크톱 UI 프로세스 상태를 필요로 하기 때문입니다.
엔터프라이즈 도구 허용/차단 정책으로 거부된 도구는 광고되지 않으며, 호출해도 거부됩니다. 정책 집행과 감사 로그는 REST POST /api/v1/tools/execute 경로와 같은 공유 실행 서비스를 거치므로, MCP로 시작된 호출도 동일하게 게이트와 감사가 적용됩니다.

실패한 도구 호출(정책 거부 포함)은 MCP 명세대로 isError: true인 MCP 도구 결과로 보고됩니다. JSON-RPC 오류는 알 수 없는 메서드 같은 프로토콜 오류에만 사용합니다.

프로토콜 세부 사항¶

지원 메서드: initialize, notifications/initialized, tools/list, tools/call, ping.
initialize는 Mcp-Session-Id 헤더를 발급하며 클라이언트는 이후 모든 요청에 이 헤더를 보내야 합니다. 세션은 유휴 타임아웃(기본 1시간)이 지나면 만료되고 동시 세션 수도 제한됩니다(기본 10개). 상한에 도달하면 새 initialize가 실패하는 대신 가장 오래 쓰이지 않은 세션을 밀어내므로, DELETE를 보내지 않고 재시작하는 클라이언트가 스스로를 잠그는 일은 없습니다. 만료되었거나 밀려났거나 알 수 없는 세션 id는 404로 응답하여 클라이언트가 다시 초기화하도록 합니다.
세션 id 헤더와 함께 DELETE /api/v1/mcp를 보내면 세션을 명시적으로 종료합니다.
GET /api/v1/mcp는 405 Method Not Allowed로 응답합니다. 이 서버는 요청마다 일반 JSON으로 응답하며, 선택 사항인 서버→클라이언트 SSE 스트림은 제공하지 않습니다.
JSON-RPC 배치 요청(최상위 배열)은 하나의 JSON-RPC 오류로 거부됩니다.
resources, prompts, sampling 기능은 제공하지 않으며 도구만 광고합니다.

보안 유의 사항¶

엔드포인트에 접근할 수 있는 사람은 누구나 도구를 실행할 수 있습니다. 셸·Python 실행도 포함됩니다. 액세스 키를 비밀로 유지하고 셸 자격 증명처럼 다루세요.
기본 바인딩은 localhost입니다. 관리 API는 기본적으로 127.0.0.1에 바인딩되므로 같은 머신의 프로세스만 엔드포인트에 접근할 수 있습니다. 기본값인 API 키 필요 꺼짐 상태에서는 로컬의 모든 프로세스가 호출할 수 있으므로, 허용할 수 없다면 API > 관리 API에서 키 요구를 켜세요.
인증 없는 네트워크 노출은 없습니다. 데스크톱 앱은 API 키 필요가 켜져 있지 않으면 localhost가 아닌 주소(예: 0.0.0.0)에서 관리 API를 시작하지 않습니다. 다른 기기에서 접근 허용 스위치는 키 요구를 켜기 전까지 비활성 상태이며, settings.json을 직접 편집해 두 설정을 조합한 경우에도 서버를 띄우는 대신 시작 실패로 보고합니다.
localhost가 아닌 출처의 브라우저 Origin 헤더가 붙은 요청은 거부되어, localhost 바인딩을 노리는 DNS 리바인딩 공격을 차단합니다.
루프백 호스트 검사. 관리 API가 루프백 주소에 바인딩되어 있는 동안에는 Host 헤더가 루프백 호스트가 아닌 요청, 그리고 CORS 허용 출처 목록에 없는 루프백 외 Origin을 담은 요청을 모두 거부합니다. 웹 페이지가 자기 도메인을 127.0.0.1로 리바인딩해 로컬 서버에 접근하는 것을 막는 장치입니다. 이 검사는 MCP 엔드포인트뿐 아니라 모든 경로에 적용되며, 루프백이 아닌 주소에 바인딩한 경우에는 대신 인증이 요구되므로 꺼집니다.
POST 요청에는 Streamable HTTP 명세가 정한 Content-Type: application/json이 필요하며, 다른 타입은 415 Unsupported Media Type으로 거부됩니다. 같은 머신의 다른 포트에서 제공되는 웹 페이지가 도구 호출을 일으키지 못하게 막는 장치입니다. 브라우저가 프리플라이트 없이 교차 출처로 보낼 수 있는 콘텐츠 타입이 바로 이 엔드포인트가 거부하는 타입이기 때문입니다.
토글을 끄면 재시작 없이 즉시 엔드포인트가 다시 숨겨집니다(404).