JSON 일괄 가져오기

폼을 통해 서버를 하나씩 추가하는 방법 외에도, Elftia는 JSON 설정을 사용해 여러 MCP 서버를 한 번에 가져오는 기능을 지원합니다. 다음과 같은 상황에서 특히 유용합니다:

• 다른 도구(예: Claude Desktop, Cursor)에서 MCP 설정 마이그레이션
• 팀 내에서 통일된 서버 설정 공유
• 새 기기에서 MCP 환경을 빠르게 복원
• 관련된 여러 서버를 한 번에 설정

JSON 가져오기 열기

1. MCP 서버 페이지 열기
2. 추가 버튼 클릭
3. 나타나는 폼에서 JSON 가져오기 모드로 전환

JSON 형식

권장 형식: mcpServers 일괄 설정

이것은 권장되는 JSON 형식으로, Claude Desktop 등의 도구에서 사용하는 설정 형식과 호환됩니다. 여러 서버를 한 번에 추가하는 것을 지원합니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search@latest"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    },
    "web-reader": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

단일 서버 형식

서버를 하나만 추가하려는 경우 간소화된 형식을 사용할 수 있습니다:

{
  "name": "my-server",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@example/mcp-server"]
}

JSON 필드 설명

mcpServers 형식

mcpServers 객체에서 각 키는 서버 이름이고 값은 설정 객체입니다:

필드	타입	필수 여부	설명
command	string	Stdio 필수	시작 명령어
args	string[]	아니오	명령어 인수
env	object	아니오	환경 변수 키-값 쌍
url	string	SSE/HTTP 필수	서버 엔드포인트 URL
headers	object	아니오	HTTP 요청 헤더
type	string	아니오	전송 유형: stdio, sse, http

:::info 타입 자동 추론 type 필드를 지정하지 않으면 시스템이 자동으로 추론합니다:

• command가 있는 경우 → stdio
• url이 있는 경우 → sse :::

단일 서버 형식

필드	타입	필수 여부	설명
name	string	예	서버 이름
type	string	아니오	전송 유형; 자동 추론
command	string	Stdio 필수	시작 명령어
args	string[]	아니오	명령어 인수
env	object	아니오	환경 변수
url	string	SSE/HTTP 필수	서버 엔드포인트 URL
headers	object	아니오	HTTP 요청 헤더

완전한 예시

예시 1: 파일 시스템 + 검색

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "tavily-search": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxxxxxxx"
      }
    }
  }
}

예시 2: GitHub + 데이터베이스

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxx"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
    }
  }
}

예시 3: 로컬 서버와 원격 서버 혼합

{
  "mcpServers": {
    "local-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "web-search": {
      "url": "https://api.z.ai/api/mcp/web_search_prime/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    },
    "web-reader": {
      "url": "https://api.z.ai/api/mcp/web_reader/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

예시 4: Python 도구 (uvx 사용)

{
  "mcpServers": {
    "minimax-tools": {
      "command": "uvx",
      "args": ["minimax-coding-plan-mcp", "-y"],
      "env": {
        "MINIMAX_API_KEY": "your-minimax-key",
        "MINIMAX_API_HOST": "https://api.minimaxi.com"
      }
    }
  }
}

가져오기 흐름

1. JSON 내용을 입력 필드에 붙여넣기
2. 시스템이 JSON 형식을 실시간으로 검증하며, 오류가 있으면 입력창 아래에 표시됨
3. 검증이 통과되면 저장 클릭
4. Stdio 서버의 경우 시스템이 필요한 종속성(npx 또는 uvx 등)을 자동으로 확인
5. 종속성이 없으면 설치 안내 메시지가 표시됨
6. 모든 서버가 추가된 후 서버 목록이 자동으로 새로고침됨

유효성 검사 규칙

• JSON은 유효한 JSON 형식이어야 함
• mcpServers 형식: 각 서버 설정에 command, url, type 중 하나 이상 포함 필요
• 단일 서버 형식: stdio 타입은 command 필요; http/sse 타입은 url 필요
• 서버 이름은 기존 서버 이름과 중복되지 않아야 함

기기 간 설정 공유

설정 내보내기

현재 Elftia의 MCP 설정은 로컬의 mcp-config 파일에 저장됩니다. 다음 방법으로 공유할 수 있습니다:

1. MCP 서버 목록 페이지에서 서버를 편집해 전체 설정 보기
2. 설정을 수동으로 JSON 형식으로 정리해 파일로 저장 후 공유

Claude Desktop에서 마이그레이션

이전에 Claude Desktop에서 MCP 서버를 설정한 경우, 설정 파일의 mcpServers 섹션을 직접 복사할 수 있습니다:

1. Claude Desktop 설정 파일 열기 (일반적으로 ~/.claude/config.json에 위치)
2. mcpServers 섹션 찾기
3. 위에서 설명한 JSON 형식으로 정리
4. Elftia에서 JSON 가져오기를 사용해 가져오기

:::caution 중요 사항

• 가져오기 전에 환경 변수의 API 키 등 민감한 값이 올바른지 확인하세요
• 설정을 내보낼 때 API 키 등 민감한 정보가 노출되지 않도록 주의하세요
• 파일 경로는 대상 기기의 실제 경로에 맞게 조정해야 합니다 :::

문제 해결

JSON 형식 오류

증상: JSON을 입력한 후 아래에 빨간색 오류 메시지가 표시됨.

해결 방법:

• JSON 문법 확인 (괄호, 따옴표, 쉼표가 올바른지)
• JSON 포맷 도구를 사용해 형식 검증
• 이스케이프 문자 주의 (예: Windows 경로의 백슬래시는 \\로 작성해야 함)

일부 서버 추가 실패

증상: 일괄 가져오기 후 일부 서버가 목록에 표시되지 않음.

해결 방법:

• 중복된 서버 이름 확인 (이름은 고유해야 함)
• 콘솔에서 오류 메시지 확인
• 실패한 서버를 폼을 통해 개별적으로 추가 시도

다음 단계

• MCP 도구 사용 — 추가 후 대화에서 도구가 작동하는 방식 알아보기
• MCP 개요 — MCP 핵심 개념 복습