MCP

Model Context Protocol(MCP)는 AI 도구를 외부 서비스와 데이터에 연결하는 개방형 표준입니다. MCP 서버를 연결하면 AI가 그 서버의 도구를 사용할 수 있습니다.

지원 범위

헬피코드의 MCP 설정 화면은 원격 MCP 서버(URL) 등록을 지원합니다. 서버 이름과 URL만 입력하면 됩니다. 로컬 프로세스(stdio) 방식 서버는 설정 화면에서 추가할 수 없습니다. 엔진 설정 파일에 직접 적는 방법은 아래 설정 파일로 관리를 참고하세요.

MCP 서버 추가하기

설정 > AI 환경설정 > MCP 환경설정을 엽니다. 이 메뉴는 모든 구성원이 사용할 수 있습니다.

1. MCP 추가(목록이 비어 있으면 MCP 추가하기)를 누릅니다.

2. 다음을 입력합니다.

   항목	규칙
   MCP 이름	영문, 숫자, 하이픈(-), 밑줄(_)만 사용할 수 있습니다. 이미 있는 이름은 쓸 수 없습니다. 예: my-mcp-server
   MCP 서버 URL	https://mcp.example.com 형식의 올바른 주소

3. 저장을 누릅니다.

상태와 인증

각 서버에는 상태가 표시됩니다.

상태	의미
확인 중	연결 상태를 확인하고 있습니다.
연결됨	정상 연결되어 AI가 도구를 쓸 수 있습니다.
연결 안 됨	사용이 꺼져 있습니다.
연결 실패	연결하지 못했습니다. 다시 시도로 재확인하세요.
인증필요	OAuth 인증이 필요합니다.

인증필요인 서버는 인증하기를 누르면 브라우저에서 인증 페이지가 열리고, 인증이 끝나면 앱으로 돌아와 "MCP 인증이 완료되었습니다."가 표시됩니다. 인증 진행 중에는 남은 시간이 카운트다운으로 표시되며 5분 안에 완료해야 합니다. 인증 전에는 서버를 켤 수 없습니다("MCP를 연결하려면 인증이 필요합니다.").

켜기와 끄기

• 설정 화면의 MCP 사용 토글, 또는 채팅창의 /mcp 패널에서 서버별로 켜고 끕니다.
• /mcp 패널은 입력창 위에 열리고, 서버별 스위치와 상태, 인증하기를 제공합니다. 등록된 서버가 없으면 "등록된 MCP 서버가 없습니다."가 표시됩니다.
• 서버를 편집하거나 삭제할 수 있습니다. 삭제는 되돌릴 수 없습니다.

채팅으로 MCP 추가하기

AI에게 "이 MCP 서버를 추가해줘"라고 요청하면, AI는 엔진 설정 파일(opencode.json)의 mcp 필드를 수정하고 /mcp로 반영하라고 안내합니다. 이때 설정 파일 수정은 보호 파일이라 확인 패널이 나타납니다. /mcp 패널을 열면 변경 내용이 반영되고, 인증이 필요한 서버는 바로 인증할 수 있습니다.

설정 파일로 관리

MCP 서버는 엔진 설정 파일의 mcp 필드에 저장됩니다. 헬피코드는 이 필드만 읽고 씁니다.

// <설정 폴더>/opencode.json
{
  "mcp": {
    "my-mcp-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "enabled": true
    }
  }
}

설정 폴더 위치는 설정 참조를 보세요.

MCP 도구와 권한

MCP 도구는 기본적으로 묻는 대상입니다(수동 수락에서 사용할 때마다 확인). 자세한 내용은 권한을 참고하세요.

警告

신뢰하는 MCP 서버만 연결하세요. MCP 서버의 도구 결과는 AI의 입력이 되며, 서버가 AI에게 지시를 끼워 넣을 수 있습니다. 헬피코드는 엔진 이름이 MCP 서버나 인증 동의 화면에 그대로 노출되지 않도록 클라이언트 이름을 숨깁니다.

문제 해결

• 연결 실패: URL이 맞는지, 서버가 외부에서 접근 가능한지 확인하고 다시 시도하세요. 사내 프록시 환경에서는 시스템 인증서(CA)를 신뢰하도록 설정되어 있습니다.
• 인증이 끝나도 상태가 바뀌지 않음: 5분 제한이 지났을 수 있습니다. 다시 인증하기를 누르세요.
• 채팅에서 추가한 서버가 안 보임: /mcp 패널을 열어 설정을 다시 불러오세요.

다음 단계

• 권한
• 설정 참조