MCP 도구 사용하기

MCP (Model Context Protocol) 서버를 추가하고 연결하면, 서버가 제공하는 도구가 Agent의 사용 가능한 도구 세트에 자동으로 등록됩니다. 이 페이지에서는 도구가 어떻게 검색되고, 명명되며, 사용되는지, 그리고 도구를 세부적으로 관리하는 방법을 설명합니다.

자동 도구 검색

MCP 서버가 성공적으로 연결되면 Elftia는 자동으로 다음을 수행합니다:

1. 도구 목록 가져오기 — 서버의 listTools 엔드포인트를 호출하여 사용 가능한 모든 도구를 조회
2. 형식 등록 — 내부 도구 시스템에 도구를 등록
3. 캐시 저장 — 빈번한 요청을 피하기 위해 도구 목록을 5분간 캐시

캐시 동작

동작	설명
캐시 지속 시간	5분 (300초)
캐시 범위	서버 ID별로 개별 캐시
자동 새로 고침	캐시 만료 후 다음 요청 시 최신 목록을 자동으로 가져옴
수동 새로 고침	MCP 서버 목록의 검색 버튼을 클릭하여 강제 새로 고침
재연결	서버를 끊고 다시 연결하면 해당 캐시가 초기화됨

수동 검색

MCP 서버 페이지에서 각 서버에 대해 검색을 실행하여 전체 기능 요약을 볼 수 있습니다:

• 도구 — Agent가 호출할 수 있는 함수
• 리소스 — 서버가 제공하는 데이터 리소스 (파일, 데이터베이스 테이블 등)
• 프롬프트 — 서버에서 사전 정의한 프롬프트 템플릿

도구 명명 형식

Agent 내 각 MCP 도구의 식별자는 다음 형식을 따릅니다:

mcp__<server-name>__<tool-name>

명명 규칙:

• 서버 이름과 도구 이름의 영숫자가 아닌 문자는 밑줄 _로 대체됩니다
• 이중 밑줄 __을 구분자로 사용합니다

예시:

서버 이름	원래 도구 이름	Agent 내 식별자
filesystem	read_file	mcp__filesystem__read_file
brave-search	brave_web_search	mcp__brave_search__brave_web_search
github	create_issue	mcp__github__create_issue

MCP 사용 모드

Elftia는 대화 중 도구 사용 가능 여부를 제어하는 세 가지 MCP 사용 모드를 제공합니다:

모드	설명	사용 사례
자동 (기본)	활성화된 모든 서버의 도구를 자동으로 사용 가능	일상 사용; Agent가 자체적으로 도구 선택
수동	각 대화 전에 사용할 서버를 직접 선택	도구 범위를 정밀하게 제어해야 하는 시나리오
비활성화	MCP 도구 완전히 꺼짐	외부 도구가 필요 없는 간단한 대화

자동 모드

기본 모드입니다. 활성화된 (isActive) 모든 MCP 서버의 도구가 Agent의 도구 목록에 자동으로 추가됩니다. Agent는 대화 내용을 기반으로 도구를 호출할지 여부를 스스로 결정합니다.

수동 모드

수동 모드에서는 현재 대화에 사용할 MCP 서버를 정밀하게 선택할 수 있습니다:

1. 대화 설정에서 MCP 모드를 수동으로 전환
2. 사용 가능한 서버 목록에서 필요한 서버를 체크
3. 선택된 서버의 도구만 대화 중에 사용 가능

비활성화 모드

MCP 기능을 완전히 비활성화합니다. Agent는 어떤 MCP 도구도 로드하지 않습니다.

도구 형식 적응

Elftia는 여러 LLM 제공자를 지원하며, 각 제공자는 도구 호출 형식이 다릅니다. MCP 도구는 현재 제공자가 요구하는 형식으로 자동 변환됩니다:

제공자	도구 형식	설명
OpenAI / DeepSeek / 중국계 LLM	function 형식	{ type: "function", function: { name, description, parameters } }
Anthropic (Claude)	tool 형식	{ name, description, input_schema }
Google (Gemini)	functionDeclarations 형식	{ functionDeclarations: [{ name, description, parameters }] }

이 변환은 완전히 자동으로 이루어지며 수동 개입이 필요하지 않습니다.

대화에서 도구가 표시되는 방식

Agent가 MCP 도구를 호출하면 대화 UI에 전용 도구 호출 카드가 표시됩니다:

• 호출 중 — 도구 이름과 전달된 인수 표시
• 결과 — 도구가 반환한 내용 표시 (텍스트, 이미지 등)
• 오류 — 호출 실패 시 오류 세부 정보 표시

도구 반환 콘텐츠 유형

MCP 도구는 다음 유형의 콘텐츠를 반환할 수 있습니다:

콘텐츠 유형	설명
text	텍스트 결과, 직접 표시
image	이미지 데이터 (Base64 인코딩), 이미지로 렌더링
audio	오디오 데이터 (Base64 인코딩), 플레이어로 렌더링

호출 타임아웃

단일 도구 호출의 타임아웃은 2분 (120초)입니다. 도구가 이 시간 내에 결과를 반환하지 않으면 호출이 종료되고 타임아웃 오류가 반환됩니다.

Agent에 MCP 서버 연결하기

특정 MCP 서버를 특정 Agent에 연결하여 더 세밀한 도구 할당을 할 수 있습니다:

연결 단계

1. MCP 서버 목록에서 대상 서버의 관리 버튼 클릭
2. 나타나는 대화 상자에서 이미 연결된 Agent 목록 확인
3. Agent에 추가를 클릭하여 사용 가능한 Agent 목록 펼치기
4. 연결할 Agent 선택

연결 관리

관리 대화 상자에서 다음을 할 수 있습니다:

작업	설명
연결된 Agent 보기	현재 연결된 Agent 표시
활성화/비활성화	토글을 사용하여 특정 Agent에 대한 도구 사용 가능 여부 제어
연결 제거	삭제 버튼을 클릭하여 Agent 연결 제거
Agent 검색	추가 시 Agent 목록 검색 및 필터링

특정 도구 비활성화

MCP 서버가 너무 많은 도구를 제공하거나 Agent가 사용하지 않길 원하는 특정 도구가 있는 경우 선택적으로 비활성화할 수 있습니다:

• 서버 수준의 disabledTools 목록에 비활성화된 도구의 이름이 기록됩니다
• 비활성화된 도구는 Agent의 도구 목록에 나타나지 않습니다
• 비활성화는 서버 업데이트 인터페이스를 통해 수행됩니다

신뢰 관리

MCP 서버에는 두 가지 신뢰 수준이 있습니다:

수준	설명	동작 차이
신뢰되지 않음 (기본)	새로 추가된 서버는 기본적으로 신뢰되지 않음	일반 사용 가능하지만 추가 제한이 있을 수 있음
신뢰됨	사용자가 신뢰할 수 있다고 명시적으로 표시한 서버	도구 호출에 대한 완전한 신뢰

신뢰됨으로 표시하기

서버 관리에서 서버의 isTrusted 속성을 업데이트하여 신뢰됨으로 표시하세요. 신뢰된 서버는 도구 호출이 자동 승인될 때 상승된 권한을 가집니다.

서버 활성화 및 비활성화

각 MCP 서버에는 isActive 토글이 있습니다:

• 활성화 — 서버가 도구 로딩에 참여합니다 (자동 모드에서 자동으로 연결)
• 비활성화 — 서버가 건너뛰어지고 도구 로딩에 참여하지 않으며 연결 리소스를 소비하지 않음

서버를 비활성화해도 설정이 삭제되지 않으며 언제든지 다시 활성화할 수 있습니다.

문제 해결

도구 호출 시 오류 반환

증상: Agent가 도구를 호출한 후 오류 메시지가 표시됩니다.

해결 방법:

• 도구에 필요한 API 키가 올바르게 설정되어 있는지 확인
• 도구 인수가 예상 형식과 일치하는지 확인
• 서버가 아직 실행 중인지 확인 (Stdio 서버의 경우)
• 서버 재연결 시도

도구 목록이 비어 있음

증상: 서버가 연결되었지만 도구가 검색되지 않습니다.

해결 방법:

• 검색 기능을 사용하여 도구 목록을 수동으로 가져오기
• 서버 버전이 tools/list 엔드포인트를 지원하는지 확인
• 서버의 로그 출력에서 오류 확인

Agent가 사용 가능한 도구를 사용하지 않음

증상: 도구가 등록되어 있지만 대화 중 Agent가 도구를 호출하지 않습니다.

해결 방법:

• 프롬프트에 도구 이름이나 관련 기능을 명시적으로 언급하기
• 모드가 비활성화로 설정되어 있는지 확인
• 도구의 설명이 정확한지 확인하여 Agent가 언제 사용해야 할지 판단할 수 있도록 하기
• 선택지 과부하를 피하기 위해 사용 가능한 도구 수 줄이기

다음 단계

• MCP 서버 추가하기 — 추가 MCP 서버 설정
• JSON 일괄 가져오기 — JSON을 통해 설정을 빠르게 가져오기
• MCP 개요 — MCP 핵심 개념 복습