본문으로 건너뛰기

MCP 서버 추가

이 페이지에서는 Elftia에서 MCP 서버를 추가하고 구성하는 방법을 설명합니다. Elftia는 세 가지 전송 유형을 지원하며, 각 유형마다 구성 단계가 약간 다릅니다.

MCP 관리 페이지 열기​

  1. 왼쪽 탐색 막대에서 MCP Servers 페이지를 클릭합니다
  2. 오른쪽 위의 Add 버튼을 클릭합니다
  3. 표시되는 양식에서 Form Input 모드를 선택합니다
팁

JSON Import 모드를 사용해 서버를 일괄 추가할 수도 있습니다. JSON 일괄 가져오기를 참조하세요.

Stdio 서버 추가​

Stdio는 가장 일반적인 전송 유형으로, 로컬 명령줄을 통해 실행되는 MCP 서버(예: npm 또는 pip 패키지)에 사용됩니다.

구성 단계​

  1. Server name — 알아보기 쉬운 이름을 입력합니다(예: filesystem)
  2. Transport type — Stdio를 선택합니다
  3. Command — 서버를 시작할 명령을 입력합니다(예: npx)
  4. Arguments — 한 줄에 하나씩 인수를 입력합니다.
    -y
    @modelcontextprotocol/server-filesystem
    /path/to/allowed/directory
  5. Environment variables(선택 사항) — KEY=VALUE 형식으로 한 줄에 하나씩 입력합니다.
    API_KEY=your-api-key
    DEBUG=true
  6. Save를 클릭합니다

구성 필드 설명​

FieldRequiredDescription
Server nameYes고유 식별자이며, 기존 서버 이름과 중복될 수 없습니다
CommandYes실행 명령입니다. 예: npx, uvx, node, python
ArgumentsNo명령에 전달되는 인수 목록이며, 한 줄에 하나씩 입력합니다
Environment variablesNo자식 프로세스에 사용할 추가 환경 변수입니다. 현재 시스템 환경을 상속합니다

일반적인 Stdio 서버 예시​

Filesystem 서버:

FieldValue
Commandnpx
Arguments-y , @modelcontextprotocol/server-filesystem , /Users/yourname/Documents

Brave Search 서버:

FieldValue
Commandnpx
Arguments-y , @modelcontextprotocol/server-brave-search@latest
Environment variablesBRAVE_API_KEY=your-brave-api-key

Tavily Search 서버:

FieldValue
Commandnpx
Arguments-y , tavily-mcp@latest
Environment variablesTAVILY_API_KEY=your-tavily-api-key

SSE 서버 추가​

SSE(Server-Sent Events)는 HTTP 장기 연결을 통해 통신하는 원격 호스팅 MCP 서버에 사용됩니다.

구성 단계​

  1. Server name — 이름을 입력합니다(예: web-search)
  2. Transport type — SSE를 선택합니다
  3. URL — 서버의 SSE 엔드포인트 주소를 입력합니다
  4. Request headers(선택 사항) — Key=Value 형식으로 한 줄에 하나씩 입력합니다.
    Authorization=Bearer your-token
    X-API-Key=your-api-key
  5. Environment variables(선택 사항) — Stdio와 동일합니다
  6. Save를 클릭합니다

구성 필드 설명​

FieldRequiredDescription
Server nameYes고유 식별자
URLYesMCP 서버의 SSE 엔드포인트 URL
Request headersNo인증 등에 사용되는 HTTP 요청 헤더
Environment variablesNo추가 환경 변수

SSE 서버 예시​

Zhipu Web Search:

FieldValue
URLhttps://api.z.ai/api/mcp/web_search_prime/mcp
Request headersAuthorization=Bearer your-zhipu-api-key

HTTP 서버 추가​

HTTP 전송(Streamable HTTP)은 MCP 2025-03-26 사양을 기반으로 하며 더 새로운 전송 옵션입니다.

구성 단계​

  1. Server name — 이름을 입력합니다
  2. Transport type — HTTP를 선택합니다
  3. URL — 서버의 HTTP 엔드포인트 주소를 입력합니다
  4. Request headers(선택 사항) — SSE와 동일합니다
  5. Save를 클릭합니다

구성 필드 설명​

사용되는 전송 프로토콜만 다르며 SSE와 동일합니다.

FieldRequiredDescription
Server nameYes고유 식별자
URLYesMCP 서버의 HTTP 엔드포인트 URL
Request headersNoHTTP 요청 헤더
Environment variablesNo추가 환경 변수

HTTP 서버 예시​

Zhipu Web Reader:

FieldValue
URLhttps://api.z.ai/api/mcp/web_reader/mcp
Request headersAuthorization=Bearer your-zhipu-api-key

의존성 확인​

Stdio 서버를 추가할 때 Elftia는 필요한 CLI 도구가 설치되어 있는지 자동으로 확인합니다.

CommandWhat is checkedAuto-install method
npx / npm / nodeNode.js 런타임Windows: winget; macOS: Homebrew; 기타: 수동 설치 안내
uv / uvxuv Python 패키지 관리자공식 설치 스크립트를 통해 자동 설치

누락된 의존성이 감지되면 Elftia는 자동 설치 또는 수동 다운로드 페이지 링크를 제공하는 안내를 표시합니다.

의존성 확인 동작​

  • 먼저 시스템 PATH에서 명령을 찾습니다
  • 찾지 못하면 일반적인 설치 디렉터리(~/.local/bin, ~/.cargo/bin, npm 전역 디렉터리 등)를 자동으로 스캔합니다
  • 설치 후 사용 가능 여부를 자동으로 확인합니다
  • 자동으로 설치할 수 없는 의존성에는 다운로드 페이지 링크를 제공합니다

연결 테스트​

서버를 추가한 뒤에는 즉시 연결을 테스트하는 것이 좋습니다.

  1. MCP 서버 목록에서 대상 서버를 찾습니다
  2. Test 버튼을 클릭합니다
  3. 연결 및 도구 검색이 완료될 때까지 기다립니다
  4. 성공하면 도구 이름 목록과 함께 Connected successfully. Found N tools. 메시지가 표시됩니다

공식 프리셋 사용​

Elftia에는 원클릭 설치를 지원하는 일부 일반적인 MCP 서버의 프리셋 구성이 포함되어 있습니다.

  1. MCP Servers 페이지에서 Official 탭으로 전환합니다
  2. 사용 가능한 프리셋을 둘러봅니다(카테고리별 필터: 검색, 비전, 웹 읽기, 코드 저장소 등)
  3. Install 버튼을 클릭합니다
  4. API 키가 필요한 경우 시스템은 이미 구성된 LLM 제공자에서 자동으로 연결하려고 시도합니다. 찾지 못하면 수동으로 입력해야 합니다

현재 지원되는 공식 프리셋:

PresetCategoryTransportRequires API Key
MiniMax Coding Plan MCP일반StdioYes
Zhipu Vision MCP비전StdioYes
Zhipu Web Search검색HTTPYes
Zhipu Web Reader웹 읽기HTTPYes
Zhipu Zread코드 저장소HTTPYes
Tavily Search검색StdioYes
Brave Search검색StdioYes

문제 해결​

명령을 찾을 수 없음​

증상: Stdio 서버를 추가할 때 명령이 존재하지 않는다는 메시지가 표시됩니다.

해결 방법:

  • 관련 런타임이 설치되어 있는지 확인합니다(Node.js, Python 등)
  • 터미널에서 명령을 직접 실행해 확인해 봅니다
  • PATH 환경 변수를 새로고침하려면 Elftia를 다시 시작합니다
  • 명령 이름 대신 전체 경로를 사용합니다(예: /usr/local/bin/npx)

연결 시간 초과​

증상: 연결 테스트 시 오랫동안 응답이 없습니다.

해결 방법:

  • 네트워크 연결을 확인합니다(SSE/HTTP 서버의 경우)
  • URL이 올바른지, 특히 포트와 경로를 확인합니다
  • 방화벽이나 프록시가 연결을 차단하고 있는지 확인합니다
  • Stdio 서버의 경우 명령이 정상적으로 시작될 수 있는지 확인합니다

인증 오류​

증상: 연결은 성공하지만 도구 호출이 인증 관련 오류로 실패합니다.

해결 방법:

  • API 키가 환경 변수에 올바르게 설정되어 있는지 확인합니다
  • SSE/HTTP 서버의 경우 요청 헤더의 인증 정보 형식이 올바른지 확인합니다
  • Bearer 토큰 형식에 유의하세요: Authorization=Bearer your-token

도구가 표시되지 않음​

증상: 서버가 성공적으로 연결되었지만 대화에 도구가 표시되지 않습니다.

해결 방법:

  • 서버가 활성화 상태인지 확인합니다(isActive가 true)
  • MCP 모드가 disabled로 설정되어 있는지 확인합니다
  • 수동 모드에서는 서버가 선택되었는지 확인합니다
  • Discover 버튼을 사용해 도구 목록을 수동으로 새로고침해 봅니다
  • 도구 캐시는 5분마다 만료됩니다. 캐시가 새로고침될 때까지 기다리거나 다시 연결하세요

다음 단계​