MCP 서버 추가
이 페이지에서는 Elftia에서 MCP 서버를 추가하고 구성하는 방법을 설명합니다. Elftia는 세 가지 전송 유형을 지원하며, 각 유형마다 구성 단계가 약간 다릅니다.
MCP 관리 페이지 열기
- 왼쪽 탐색 막대에서 MCP Servers 페이지를 클릭합니다
- 오른쪽 위의 Add 버튼을 클릭합니다
- 표시되는 양식에서 Form Input 모드를 선택합니다
팁
JSON Import 모드를 사용해 서버를 일괄 추가할 수도 있습니다. JSON 일괄 가져오기를 참조하세요.
Stdio 서버 추가
Stdio는 가장 일반적인 전송 유형으로, 로컬 명령줄을 통해 실행되는 MCP 서버(예: npm 또는 pip 패키지)에 사용됩니다.
구성 단계
- Server name — 알아보기 쉬운 이름을 입력합니다(예:
filesystem) - Transport type —
Stdio를 선택합니다 - Command — 서버를 시작할 명령을 입력합니다(예:
npx) - Arguments — 한 줄에 하나씩 인수를 입력합니다.
-y@modelcontextprotocol/server-filesystem/path/to/allowed/directory
- Environment variables(선택 사항) —
KEY=VALUE형식으로 한 줄에 하나씩 입력합니다.API_KEY=your-api-keyDEBUG=true - Save를 클릭합니다
구성 필드 설명
| Field | Required | Description |
|---|---|---|
| Server name | Yes | 고유 식별자이며, 기존 서버 이름과 중복될 수 없습니다 |
| Command | Yes | 실행 명령입니다. 예: npx, uvx, node, python |
| Arguments | No | 명령에 전달되는 인수 목록이며, 한 줄에 하나씩 입력합니다 |
| Environment variables | No | 자식 프로세스에 사용할 추가 환경 변수입니다. 현재 시스템 환경을 상속합니다 |
일반적인 Stdio 서버 예시
Filesystem 서버:
| Field | Value |
|---|---|
| Command | npx |
| Arguments | -y , @modelcontextprotocol/server-filesystem , /Users/yourname/Documents |
Brave Search 서버:
| Field | Value |
|---|---|
| Command | npx |
| Arguments | -y , @modelcontextprotocol/server-brave-search@latest |
| Environment variables | BRAVE_API_KEY=your-brave-api-key |
Tavily Search 서버:
| Field | Value |
|---|---|
| Command | npx |
| Arguments | -y , tavily-mcp@latest |
| Environment variables | TAVILY_API_KEY=your-tavily-api-key |
SSE 서버 추가
SSE(Server-Sent Events)는 HTTP 장기 연결을 통해 통신하는 원격 호스팅 MCP 서버에 사용됩니다.
구성 단계
- Server name — 이름을 입력합니다(예:
web-search) - Transport type —
SSE를 선택합니다 - URL — 서버의 SSE 엔드포인트 주소를 입력합니다
- Request headers(선택 사항) —
Key=Value형식으로 한 줄에 하나씩 입력합니다.Authorization=Bearer your-tokenX-API-Key=your-api-key - Environment variables(선택 사항) — Stdio와 동일합니다
- Save를 클릭합니다
구성 필드 설명
| Field | Required | Description |
|---|---|---|
| Server name | Yes | 고유 식별자 |
| URL | Yes | MCP 서버의 SSE 엔드포인트 URL |
| Request headers | No | 인증 등에 사용되는 HTTP 요청 헤더 |
| Environment variables | No | 추가 환경 변수 |
SSE 서버 예시
Zhipu Web Search:
| Field | Value |
|---|---|
| URL | https://api.z.ai/api/mcp/web_search_prime/mcp |
| Request headers | Authorization=Bearer your-zhipu-api-key |
HTTP 서버 추가
HTTP 전송(Streamable HTTP)은 MCP 2025-03-26 사양을 기반으로 하며 더 새로운 전송 옵션입니다.
구성 단계
- Server name — 이름을 입력합니다
- Transport type —
HTTP를 선택합니다 - URL — 서버의 HTTP 엔드포인트 주소를 입력합니다
- Request headers(선택 사항) — SSE와 동일합니다
- Save를 클릭합니다
구성 필드 설명
사용되는 전송 프로토콜만 다르며 SSE와 동일합니다.
| Field | Required | Description |
|---|---|---|
| Server name | Yes | 고유 식별자 |
| URL | Yes | MCP 서버의 HTTP 엔드포인트 URL |
| Request headers | No | HTTP 요청 헤더 |
| Environment variables | No | 추가 환경 변수 |
HTTP 서버 예시
Zhipu Web Reader:
| Field | Value |
|---|---|
| URL | https://api.z.ai/api/mcp/web_reader/mcp |
| Request headers | Authorization=Bearer your-zhipu-api-key |
의존성 확인
Stdio 서버를 추가할 때 Elftia는 필요한 CLI 도구가 설치되어 있는지 자동으로 확인합니다.
| Command | What is checked | Auto-install method |
|---|---|---|
npx / npm / node | Node.js 런타임 | Windows: winget; macOS: Homebrew; 기타: 수동 설치 안내 |
uv / uvx | uv Python 패키지 관리자 | 공식 설치 스크립트를 통해 자동 설치 |
누락된 의존성이 감지되면 Elftia는 자동 설치 또는 수동 다운로드 페이지 링크를 제공하는 안내를 표시합니다.
의존성 확인 동작
- 먼저 시스템 PATH에서 명령을 찾습니다
- 찾지 못하면 일반적인 설치 디렉터리(
~/.local/bin,~/.cargo/bin, npm 전역 디렉터리 등)를 자동으로 스캔합니다 - 설치 후 사용 가능 여부를 자동으로 확인합니다
- 자동으로 설치할 수 없는 의존성에는 다운로드 페이지 링크를 제공합니다
연결 테스트
서버를 추가한 뒤에는 즉시 연결을 테스트하는 것이 좋습니다.
- MCP 서버 목록에서 대상 서버를 찾습니다
- Test 버튼을 클릭합니다
- 연결 및 도구 검색이 완료될 때까지 기다립니다
- 성공하면 도구 이름 목록과 함께
Connected successfully. Found N tools.메시지가 표시됩니다
공식 프리셋 사용
Elftia에는 원클릭 설치를 지원하는 일부 일반적인 MCP 서버의 프리셋 구성이 포함되어 있습니다.
- MCP Servers 페이지에서 Official 탭으로 전환합니다
- 사용 가능한 프리셋을 둘러봅니다(카테고리별 필터: 검색, 비전, 웹 읽기, 코드 저장소 등)
- Install 버튼을 클릭합니다
- API 키가 필요한 경우 시스템은 이미 구성된 LLM 제공자에서 자동으로 연결하려고 시도합니다. 찾지 못하면 수동으로 입력해야 합니다
현재 지원되는 공식 프리셋:
| Preset | Category | Transport | Requires API Key |
|---|---|---|---|
| MiniMax Coding Plan MCP | 일반 | Stdio | Yes |
| Zhipu Vision MCP | 비전 | Stdio | Yes |
| Zhipu Web Search | 검색 | HTTP | Yes |
| Zhipu Web Reader | 웹 읽기 | HTTP | Yes |
| Zhipu Zread | 코드 저장소 | HTTP | Yes |
| Tavily Search | 검색 | Stdio | Yes |
| Brave Search | 검색 | Stdio | Yes |
문제 해결
명령을 찾을 수 없음
증상: 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분마다 만료됩니다. 캐시가 새로고침될 때까지 기다리거나 다시 연결하세요
다음 단계
- JSON 일괄 가져오기 — JSON으로 여러 서버를 빠르게 가져오기
- MCP 도구 사용 — 대화 중 도구가 사용되는 방식을 알아보기