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)를 사용하며 주소는 다음과 같습니다.
포트는 관리 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 세션 안에서 확인합니다.
backend-ai-go 서버가 연결된 상태로 표시되고 도구 목록을 사용할 수 있어야 합니다. Streamable HTTP 트랜스포트를 지원하는 다른 MCP 클라이언트도 동일하게 URL과 X-API-Key 헤더만 지정하면 됩니다.
노출되는 도구¶
엔드포인트는 앱 자체 에이전트가 사용하는 내장 도구 카탈로그를 그대로 광고하되, 이 트랜스포트에서 실제로 실행 가능한 도구만 노출합니다.
- 데스크톱 앱 셸이 필요한 도구(클립보드, 알림, 음성 전사, 이미지 생성, 메모리 뱅크,
load_model이나list_downloads같은 모델 계열 AppControl 도구)는 광고하지 않습니다. 이 도구들은 HTTP 트랜스포트가 갖고 있지 않은 데스크톱 UI 프로세스 상태를 필요로 하기 때문입니다. - 엔터프라이즈 도구 허용/차단 정책으로 거부된 도구는 광고되지 않으며, 호출해도 거부됩니다. 정책 집행과 감사 로그는 REST
POST /api/v1/tools/execute경로와 같은 공유 실행 서비스를 거치므로, MCP로 시작된 호출도 동일하게 게이트와 감사가 적용됩니다. - autonomous-agent 쓰기 도구는 엔드포인트 자체에 접근할 수 있으면 계속 광고되지만, 호출 시점에 scope 검사를 추가로 수행합니다.
send_autonomous_message는autonomous_message_send또는Admin이 필요하고,decide_hermes_approval은container_write또는Admin이 필요합니다. scope가 없으면 감사가 기록된 policy-denied 도구 결과로 반환됩니다.
실패한 도구 호출(정책 거부 포함)은 MCP 명세대로 isError: true인 MCP 도구 결과로 보고됩니다. JSON-RPC 오류는 알 수 없는 메서드 같은 프로토콜 오류에만 사용합니다.
Autonomous-agent 도구¶
autonomous-agent 도구 7개는 이 엔드포인트로 광고되며 POST /api/v1/tools/execute로도 호출할 수 있습니다. REST API와 같은 프로바이더 레지스트리, 게이트웨이 상태, 채널 서비스, Hermes 승인 서비스를 사용합니다.
| 도구 | 승인 | 추가 헤드리스 scope | 용도 |
|---|---|---|---|
list_autonomous_providers | 불필요 | 없음 | 프로바이더 가용성, 사용할 수 없는 이유, 기능, 설치 상태, 게이트웨이 상태를 나열합니다. |
get_autonomous_gateway | 불필요 | 없음 | 프로바이더 하나의 최신 캐시된 게이트웨이 상태를 반환합니다. |
list_autonomous_channels | 불필요 | 없음 | 프로바이더 하나의 메시징 채널을 최대 50개 나열합니다. |
list_autonomous_channel_messages | 불필요 | 없음 | 프로바이더 채널 하나의 최근 메시지를 최대 50개 나열합니다. |
send_autonomous_message | 필요 | autonomous_message_send 또는 Admin | 프로바이더 채널 하나로 메시지를 보냅니다. |
list_hermes_pending_approvals | 불필요 | 없음 | 운영자 결정을 기다리는 Hermes 거버넌스 요청을 나열합니다. |
decide_hermes_approval | 필요 | container_write 또는 Admin | 대기 중인 Hermes 거버넌스 요청 하나를 승인하거나 거부합니다. |
list_autonomous_providers는 등록된 프로바이더가 없는 헤드리스 서버에서도 의도적으로 유용합니다. 알려진 프로바이더 종류와 사용할 수 없는 이유를 보고합니다. 이 트랜스포트에서는 호스트가 대화형 승인 프롬프트를 표시하지 않으므로, 변경 도구를 호출하기 전에 사용자에게 확인하는 책임은 MCP 클라이언트에 있습니다.
스쿼드 도구¶
스쿼드 도구 13개는 이 엔드포인트로 광고됩니다. 따라서 aigo-server에 연결한 MCP 클라이언트가 스쿼드를 조회하고 조작할 수 있습니다. 같은 도구를 POST /api/v1/tools/execute로도 호출할 수 있습니다.
| 도구 | 승인 | 용도 |
|---|---|---|
list_squads | 불필요 | 스쿼드 목록과 이름, 설명, 에이전트 수, 상태. |
get_squad | 불필요 | 스쿼드 하나의 설정과 에이전트 명단(id, 이름, 역할, 모델). |
list_squad_templates | 불필요 | 설치된 스쿼드 템플릿 목록(내장 및 사용자 생성). |
list_squad_tasks | 불필요 | 스쿼드의 관리 태스크 목록. 상태로 필터링 가능. |
get_squad_execution | 불필요 | 실행 하나의 단계, 웨이브 진행도, 계획 태스크, 최종 결과, 토큰 사용량. |
list_squad_executions | 불필요 | 기록된 실행 이력(최신순). |
create_squad | 필요 | 스쿼드 생성. 템플릿으로 초기 구성 가능. |
submit_squad_request | 필요 | 요청을 제출해 실행을 생성. |
approve_squad_plan | 필요 | 승인 대기 중인 계획을 승인하고 실행을 시작합니다. 데스크톱과 헤드리스 서버에서 동일합니다. |
reject_squad_plan | 필요 | 계획을 반려합니다. 피드백이 플래너에 전달되어 같은 실행을 다시 계획하며, 수정된 계획은 승인 대기 상태로 남고 결과에 새 작업 수와 웨이브 수가 담깁니다. |
cancel_squad_execution | 필요 | 아직 끝나지 않은 실행을 취소. |
steer_squad_execution | 필요 | 실행 중이거나 일시 정지 또는 미승인 상태인 실행에 상시 지시를 전달. |
send_squad_agent_message | 필요 | 에이전트 한 명에게 메시지를 보내고 턴을 실행. |
이슈 #4954 이후로는 두 도구 모두 헤드리스 서버에서도 데스크톱과 같은 일을 합니다. submit_squad_request는 플래너를 실행하고 autoApprove가 켜져 있으면 실행기까지 시작하며, approve_squad_plan은 승인을 기다리던 계획의 실행기를 시작합니다. 각 결과는 무엇이 일어났는지를 여전히 plannerStarted와 executorStarted로 보고하므로 짐작할 필요가 없습니다. plannerStarted는 런타임이 제출 경로를 호출했는지가 아니라 플래너가 실제로 요청을 분해했는지를 답합니다. 라우터가 꺼져 있거나 플래너 에이전트에 쓸 수 있는 모델이 없거나 플래너 응답이 태스크를 하나도 만들지 않으면 run_planner_decomposition은 에이전트마다 태스크 하나씩인 폴백으로 내려앉고, 그 폴백에 안착한 제출은 plannerStarted: false와 함께 원인을 담은 plannerDegradedReason을 보고합니다(이슈 #4966). 이 사유는 실행에 남아 있으므로 이후의 모든 get_squad_execution 폴링에서도 함께 읽힙니다. 스쿼드 태스크가 호출하는 도구는 POST /tools/execute와 같은 기능 게이트와 정책 게이트를 거치므로, 데스크톱 앱이 필요한 도구는 카탈로그가 알리는 사유와 함께 거부됩니다.
표에서 상태를 변경하는 도구는 모두 requires_approval: true입니다. 이 트랜스포트에서는 호스트가 승인을 묻지 않으므로, 호출 전에 사용자에게 확인하는 책임은 MCP 클라이언트에 있습니다.
프로토콜 세부 사항¶
- 지원 메서드:
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).