MCP 연동하기¶

Model Context Protocol (MCP)은 AI 애플리케이션이 모든 서비스에 대해 개별적인 통합 코드를 작성하지 않고도 외부 도구나 데이터 소스에 연결할 수 있게 해주는 개방형 표준입니다.

MCP란 무엇인가요?¶

MCP는 도구와 데이터를 노출하는 표준 인터페이스입니다. 서버가 이 인터페이스를 구현하면 Backend.AI GO를 고치지 않고 연결할 수 있습니다. USB 포트에 비유할 수 있습니다.

왜 MCP를 사용하나요?¶

확장성: 회사의 내부 데이터베이스, 로컬 슬랙(Slack), 특정 API, 또는 직접 작성한 스크립트에 AI를 연결할 수 있습니다.
커뮤니티 생태계: 전 세계 개발자들이 만들어 공유하는 다양한 오픈 소스 MCP 서버들을 바로 활용할 수 있습니다.
표준화: 한 번만 MCP 서버를 구축해 두면, Backend.AI GO뿐만 아니라 다른 MCP 지원 AI 클라이언트에서도 그대로 사용할 수 있습니다.

MCP 서버 연결하기¶

Backend.AI GO는 두 가지 방식으로 MCP 서버와 연결합니다. 서버를 로컬 프로세스로 직접 실행하거나(stdio), 네트워크 너머의 원격 서버에 접속하는 방식입니다.

로컬 프로세스¶

설정 > 도구 및 확장으로 이동합니다.
서버 추가를 클릭합니다. 목록 대신 서버 입력 화면이 열립니다.
서버의 이름을 입력합니다.
연결 방식은 로컬 프로세스로 둡니다.
실행할 명령어(예: node, python, npx)를 입력합니다. 다른 프로그램은 먼저 허용해야 하는데, 허용이 필요한 명령어를 참고하세요.
필요한 인자(arguments)나 환경 변수(예: API 키)를 추가합니다.
화면 위쪽의 추가를 클릭합니다. 목록으로 돌아가면 새 서버가 보입니다.
해당 서버의 연결을 클릭합니다.

허용이 필요한 명령어¶

로컬 서버의 명령어가 기본 목록에 있는 패키지 실행기나 인터프리터, 즉 npx, node, npm, yarn, pnpm, bunx, bun, python, python3, uvx, uv, pipx, poetry, deno, cargo 중 하나라면 별도 절차 없이 바로 실행됩니다. 비교할 때는 파일 이름만 보기 때문에 /opt/homebrew/bin/uvx처럼 전체 경로로 적어도 uvx로 취급합니다.

직접 설치한 CLI(예: open-computer-use mcp)처럼 목록에 없는 프로그램은 데스크톱 앱에서 허용해야 실행할 수 있습니다. 연결을 클릭하면 앱이 명령어와 실제로 실행될 프로그램 파일, 인수, 서버가 설정하는 환경 변수의 이름까지 전체 명령줄을 보여 주는데요, 환경 변수의 값은 표시하지 않습니다. 허용하고 연결을 클릭하면 해당 프로그램을 허용하고 바로 연결하며, 취소를 클릭하면 서버는 연결되지 않은 상태로 남습니다.

허용은 해당 파일에만 적용됩니다. 앱은 명령어가 가리키는 절대 경로와 파일의 SHA-256 해시를 기록해 두고, 서버를 시작할 때마다 둘을 다시 확인한 뒤 이름을 다시 찾지 않고 확인한 파일을 그대로 실행하죠. 프로그램이 업데이트되거나 교체된 경우, 또는 같은 이름이 다른 경로에서 발견되는 경우(예: 서버 환경 변수의 PATH를 바꾼 경우)에는 다시 허용을 요청합니다. 허용한 프로그램이라도 다른 검사는 그대로 적용되므로 셸 메타 문자가 들어간 인수나 LD_PRELOAD 같은 환경 변수는 여전히 거부됩니다. Node나 Python 진입 스크립트 같은 스크립트라면 해시는 해당 스크립트 파일만 확인하고, 스크립트가 불러오는 다른 파일은 확인하지 않습니다.

허용한 프로그램은 같은 설정 화면의 허용한 명령어에 나타납니다. 허용 취소를 클릭하고 확인하면 허용이 사라지고, 해당 프로그램으로 실행 중인 서버는 연결이 해제되며, 다음에 연결할 때 다시 허용을 요청합니다. 허용 목록은 MCP 서버 설정과 함께 mcp_servers.json 옆의 mcp_command_approvals.json에 저장되므로 앱을 다시 시작해도 유지됩니다.

프로그램을 허용할 수 있는 사람은 데스크톱 앱 사용자뿐입니다. 관리 API나 aigo CLI로 등록한 서버도 실행하기 전에 같은 허용이 필요하고, 허용을 대신해 주는 API 엔드포인트는 없습니다. 플러그인 번들은 기본 목록에 없는 명령어를 사용하는 서버를 등록하지 않습니다. 헤드리스 서버(aigo-server)는 허용 기능을 사용하지 않고 기본 목록의 명령어만 실행합니다. 조직은 tools.allowUserApprovedMcpCommands 정책 설정으로 허용 기능을 끌 수 있으며(엔터프라이즈 정책 참고), 이때는 데스크톱 앱에서도 기본 목록의 명령어만 실행됩니다.

원격 서버¶

설정 > 도구 및 확장으로 이동합니다.
서버 추가를 클릭합니다. 목록 대신 서버 입력 화면이 열립니다.
서버의 이름을 입력합니다.
연결 방식을 Streamable HTTP로 설정합니다. HTTP+SSE는 이전 방식이고 단계적으로 사라지고 있으니, Streamable HTTP를 지원하지 않는 서버에만 선택하세요.
서버 URL을 입력합니다(예: https://mcp.example.com/mcp).
서버에 인증이 필요하면 토큰을 입력합니다. 토큰은 Bearer 토큰으로 전송되고 시스템 키체인에 저장되며, 입력한 뒤에는 다시 표시되지 않습니다.
서버가 별도의 요청 헤더를 요구하면 한 줄에 이름: 값 하나씩 추가합니다.
화면 위쪽의 추가를 클릭합니다. 목록으로 돌아가면 새 서버가 보입니다.
해당 서버의 연결을 클릭합니다.

http://127.0.0.1:3000/mcp처럼 자기 컴퓨터에서 실행 중인 서버는 별도 설정 없이 그대로 연결됩니다. 그 외의 주소는 앱의 다른 네트워크 요청과 동일한 규칙을 따르기 때문에, 관리 정책이 적용된 설치 환경에서는 해당 호스트가 조직의 허용 목록에 들어 있어야 합니다.

CLI도 관리 API를 통해 같은 원격 설정을 등록합니다. 현재 방식의 서버에는 streamable_http를, 예전 HTTP+SSE 서버에는 sse를 지정하세요.

export AIGO_MCP_TOKEN='<token>'
aigo mcp add hosted-tools \
  --transport streamable_http \
  --url https://mcp.example.com/mcp \
  --header 'X-Tenant: acme'
aigo mcp connect hosted-tools
aigo mcp tools hosted-tools

AIGO_MCP_TOKEN 대신 --token으로 자격 증명을 전달해도 됩니다. 관리 API가 URL과 헤더를 검증하고 토큰은 시스템 키체인으로 옮기며, mcp_servers.json에는 비밀이 아닌 서버 설정만 기록합니다.

요청 제한 시간¶

서버로 보내는 요청은 도구 호출을 포함해 기본적으로 30초 안에 응답을 받아야 합니다. 에이전트 루프를 실행하거나 오래 검색하는 도구에는 더 긴 시간이 필요할 수 있습니다. 서버 설정 양식의 요청 제한 시간(초)에 1에서 3600 사이의 값을 입력하세요. 비워 두면 기본값을 사용합니다. 이 값은 해당 서버에만 적용됩니다.

명령줄에서는 aigo mcp add에 --timeout <SECS>를 지정합니다. REST API에서는 POST /api/v1/mcp/servers 또는 PUT /api/v1/mcp/servers/{id} 본문에 requestTimeoutSecs를 보냅니다. 1에서 3600을 벗어난 값은 400으로 거부됩니다.

MCP 도구 관리하기¶

연결이 성공하면 MCP 서버가 제공하는 도구들이 코워크 설정에 자동으로 나타납니다.

개별 MCP 서버를 켜거나 끌 수 있습니다.
에이전트는 MCP 도구를 기본 제공 도구와 똑같이 취급하며, 동일한 권한 승인 절차를 거칩니다.
연결된 MCP 서버의 "상세 정보"를 클릭하면 발견된 도구 목록을 확인할 수 있습니다.

인기 있는 MCP 서버 목록은 MCP 서버 디렉토리에서 확인해 보세요.