Forguncy 애플리케이션을 MCP클라이언트로 사용하기
MCP 서버 설정 및 사용하기 (클라이언트로서)
이 문서는 Forguncy에서 MCP 서버를 설정하고 사용하여 AI 기능을 확장하는 방법을 설명합니다. Forguncy를 MCP 클라이언트로 활용하면 외부 AI 도구 및 서비스에 연결할 수 있습니다.
1. 핵심 개념
설정 전에 자주 사용되는 MCP 서버 연결 방식 몇 가지를 알아두면 도움이 됩니다.
StreamableHTTP / SSE 방식: 네트워크 URL을 통해 접근하는 MCP 서버(OpenAI, Anthropic 등에서 제공하는 호스팅 도구나 서비스)를 연결할 때 사용합니다. SSE는 HTTP의 특수한 형태로, 서버가 데이터를 스트리밍 방식으로 반환하는 것을 지원합니다.
Stdio 방식: 로컬 컴퓨터에서 실행되는 명령줄 프로그램을 호출할 때 사용합니다. 예를 들어 로컬 파일 처리 스크립트를 MCP 도구로 캡슐화하여 AI가 호출할 수 있도록 만들 수 있습니다.
2. 기본 설정 흐름
빌더에서 MCP 서버를 추가하는 기본 단계는 다음과 같습니다.
1. 애플리케이션 설정 열기
빌더 상단 메뉴에서 "파일" 을 클릭하고 "옵션>응용 프로그램 설정" 을 선택합니다.
2. MCP 서버 설정 추가
애플리케이션 설정 대화상자에서 "MCP 설정" 항목을 찾아 "추가" 버튼을 클릭합니다.
3. 설정 정보 입력 및 테스트
팝업된 대화상자에서 연결할 MCP 서버 유형에 맞게 정보를 입력합니다.
입력 완료 후 "테스트" 버튼을 클릭합니다. 연결에 성공하면 시스템이 해당 서버가 제공하는 사용 가능한 도구 목록을 표시합니다.
StreamableHTTP/SSE 방식의 경우: 주로 서버의
URL을 입력합니다.Stdio 방식의 경우: 주로 프로그램의
명령(command)경로와파라미터(args)를 입력합니다.
4. 설정 저장
테스트 통과 후 "확인" 을 클릭하여 해당 MCP 서버 설정을 저장합니다.
3. 애플리케이션에서 MCP 도구 사용하기
설정 완료 후, 다음 위치에서 이 MCP 도구들을 사용할 수 있습니다.
1. AI 대화 셀에서 사용
페이지에 "AI 대화 셀" 을 배치합니다.
오른쪽 속성 설정에서 "MCP 도구" 열을 찾아, 드롭다운에서 방금 설정한 MCP 서버를 선택합니다.
실행 시, 자연어로 직접 AI에게 지시를 내리면 AI가 자동으로 적절한 도구를 판단하여 호출합니다. 예: "몇 시야?"
결과 옆의 전환 버튼을 클릭하면 도구 호출의 상세 정보(파라미터, 반환값 등)를 확인할 수 있습니다.
2. AI 어시스턴트 명령에서 사용
클라이언트 명령 또는 서버단 명령에서 "AI 어시스턴트" 명령 노드를 추가할 수 있습니다.
해당 노드의 속성 설정에서 마찬가지로 사용할 MCP 도구를 체크하고 설정할 수 있습니다.
명령 실행 후, MCP 도구의 반환값을 가져와 후속 업무 로직에 활용할 수 있습니다.
4. 고급 설정 옵션
인증 방식과 사용 시나리오에 따라 일부 고급 설정이 필요할 수 있습니다.
1. 커스텀 요청 헤더 (Custom Headers)
연결할 MCP 서버가 API 키(API Key) 등의 인증 정보를 요구하는 경우, "Headers" 를 통해 설정할 수 있습니다.
설정 방법: MCP 서버 설정에서 키-값 쌍을 추가합니다. 예:
키(Key):
Authorization값(Value):
Bearer your-api-key
2. OAuth 2.0 인증
OAuth 2.0 인증을 지원하는 MCP 서버의 경우, 플랫폼은 간소화된 설정 방식을 제공합니다.
설정 방법: MCP 서버 설정에서
clientId,clientSecret,tokenUrl,scope등의 필드를 입력합니다.작동 원리: 설정 후 Forguncy는 서버와 통신하기 전에 자동으로 이 정보를 사용하여 액세스 토큰(Access Token)을 획득하고 요청 헤더에 추가합니다. 토큰이 만료되면 자동으로 새로 발급받습니다.
주의: OAuth와 수동
Authorization요청 헤더를 동시에 설정하는 것은 권장하지 않습니다.
3. 환경 변수 사용 (Environment Variables)
설정에 경로나 키를 직접 하드코딩하는 것을 피하기 위해 환경 변수를 사용할 수 있습니다.
사용 방법: 지원되는 필드에서
%변수명%형식으로 환경 변수를 참조합니다. 예:%MY_API_KEY%지원 필드:
command,url,args,env의 값,headers의 값, 그리고oauth내의 모든 필드주의: 새 환경 변수를 추가하거나 수정한 후에는 Forguncy 빌더 또는 서버를 재시작해야 적용됩니다.
5. 보안 및 인터랙션 기능
1. 실행 전 확인 (Confirm Before Execute)
AI가 고위험 작업(데이터 삭제, 이메일 발송 등)을 자동으로 실행하는 것을 방지하기 위해 이 기능을 활성화하는 것을 권장합니다.
활성화 방법: MCP 도구를 사용하는 컴포넌트(예: AI 대화 셀)에서 "실행 전 확인" 옵션을 체크합니다.
효과: AI가 해당 도구를 호출하기로 결정하면, 먼저 확인 대화상자가 팝업되어 사용자가 직접 확인한 후에야 실행됩니다.
2. 실행 전/후 명령
AI 대화 셀에는 "MCP 실행 전 명령" 과 "MCP 실행 후 명령" 두 가지 이벤트가 제공됩니다. 이 이벤트들에서 명령을 작성하여 로그 기록이나 결과에 따른 판단 등 커스텀 로직을 구현할 수 있습니다.
6. 관리 및 유지보수
1. 관리 콘솔에서 관리
애플리케이션 배포 후, 관리자는 관리 콘솔의 "MCP 서버" 페이지에서 기존 MCP 설정을 편집하거나 특정 MCP 서비스를 활성화/비활성화할 수 있습니다.
2. 설정 가져오기 및 내보내기
빌더의 애플리케이션 설정에서 설정된 MCP 서버 목록을 JSON 파일로 내보낼 수 있어, 프로젝트 간 마이그레이션이나 백업에 편리합니다. 이 JSON 파일은 MCP 프로토콜을 지원하는 다른 클라이언트(예: VS Code / Cursor)에서도 사용할 수 있습니다.
7. 주의사항 및 제한사항
기능 지원: 현재 버전은 MCP 프로토콜 중 "도구(Tool)" 부분을 주로 지원하며, 프롬프트(Prompts), 리소스(Resources) 등 기타 부분은 아직 지원하지 않습니다.
반환 유형: 현재 버전은 반환 유형이 텍스트(Text)인 MCP 도구를 주로 처리합니다.
오류 처리: MCP 도구 호출이 실패하면 시스템은 흐름을 중단하지 않고, 오류 정보를 컨텍스트로 AI에 반환합니다. AI는 오류를 이해하고 수정을 시도하거나, 사용자에게 문제를 설명할 수 있습니다.