설치 매뉴얼

Nexol MCP 서비스를 Claude Desktop 또는 Claude Code에 설치하는 방법입니다.

사전 요구사항

항목	요구사항
API Key	관리자에게 발급 요청 필요 (아래 참고)
Claude Code	최신 버전 (claude --version으로 확인)
네트워크	사내 네트워크 또는 VPN 연결
OS	Windows 10+, macOS 10.15+, Linux

⚠️ API Key 필요: MCP 서비스를 사용하려면 관리자에게 API Key를 발급받아야 합니다.

신청 방법: roy.cho@nexol.co.kr로 아래 정보와 함께 요청하세요.
• 이름 / 부서
• 사용 목적
• 필요 리소스 (MySQL, MSSQL, Redmine, Draw 중 선택)

Claude Code 설치

Claude Code 설치 확인

터미널에서 Claude Code가 설치되어 있는지 확인합니다.

claude --version

버전이 출력되면 설치되어 있는 것입니다. 설치되어 있지 않다면 아래 명령으로 설치하세요.

Claude Code 설치 (미설치 시)

macOS / Linux

curl -fsSL https://claude.ai/install.sh | sh

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

Nexol MCP 등록

방법 A: CLI 명령어 (권장)

MCP 서버 등록

발급받은 API Key를 사용하여 Nexol MCP를 등록합니다.

claude mcp add --scope user --transport sse nexol-mcp "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"

참고: YOUR_API_KEY를 발급받은 실제 API Key로 교체하세요.
--scope user는 현재 사용자에게만 적용됩니다.

등록 확인

MCP가 정상적으로 등록되었는지 확인합니다.

claude mcp list

아래와 같이 표시되면 성공입니다:

nexol-mcp: https://mcp.nexol.co.kr/sse?key=... - ✓ Connected

방법 B: 설정 파일 직접 수정

Claude Code 설정 파일

~/.claude/settings.json 파일을 생성하거나 편집합니다.

{
  "mcpServers": {
    "nexol-mcp": {
      "type": "sse",
      "url": "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"
    }
  }
}

참고: YOUR_API_KEY를 발급받은 실제 API Key로 교체하세요.

Cursor IDE 설정

MCP 설정 열기

Cursor IDE에서 MCP 설정 메뉴를 엽니다.

Cursor → Settings → MCP

MCP 서버 추가

+ Add new global MCP server 버튼을 클릭하고 아래 JSON을 붙여넣습니다.

{
  "mcpServers": {
    "nexol-mcp": {
      "type": "sse",
      "url": "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"
    }
  }
}

참고: YOUR_API_KEY를 발급받은 실제 API Key로 교체하세요.

Claude Desktop 설정 (선택)

설정 파일 편집

Claude Desktop을 사용하는 경우, 설정 파일을 직접 편집할 수 있습니다.

설정 파일 위치

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

설정 내용

{
  "mcpServers": {
    "nexol-mcp": {
      "type": "sse",
      "url": "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"
    }
  }
}

참고: YOUR_API_KEY를 발급받은 실제 API Key로 교체하세요.

문제 해결

연결 실패 시

# MCP 삭제 후 재등록
claude mcp remove nexol-mcp
claude mcp add --scope user --transport sse nexol-mcp "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"

API Key가 만료되었거나 잘못된 경우 관리자에게 재발급을 요청하세요.

"Unexpected token" JSON 파싱 에러

Claude Code에서 "Unexpected token '<', "<!DOCTYPE "... is not valid JSON" 에러가 발생하는 경우:

Claude Code를 완전히 종료 후 재시작
/mcp 명령으로 MCP 상태 확인
Reconnect 선택하여 재연결

문제가 지속되면 관리자에게 문의하세요.

네트워크 오류 시

VPN 연결을 확인하거나, 사내 네트워크에 있는지 확인하세요.

# 서비스 상태 확인
curl https://mcp.nexol.co.kr/gateway/health

{"status":"ok"}가 출력되면 서버는 정상입니다.

연결 상태 진단

SSE 연결을 직접 테스트하려면:

# SSE 엔드포인트 테스트 (Ctrl+C로 중단)
curl -N "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"

event: endpoint로 시작하는 응답이 오면 정상입니다.

지원: 문제가 지속되면 roy.cho@nexol.co.kr로 문의하세요.