설치 매뉴얼

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 http nexol-gw https://mcp.nexol.co.kr/mcp --header "Authorization: Bearer YOUR_API_KEY"

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

등록 확인

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

claude mcp list

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

nexol-gw: https://mcp.nexol.co.kr/mcp - ✓ Connected

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

Claude Code 설정 파일

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

{
  "mcpServers": {
    "nexol-gw": {
      "type": "http",
      "url": "https://mcp.nexol.co.kr/mcp",
      "headers": { "Authorization": "Bearer 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-gw": {
      "type": "http",
      "url": "https://mcp.nexol.co.kr/mcp",
      "headers": { "Authorization": "Bearer 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-gw": {
      "type": "http",
      "url": "https://mcp.nexol.co.kr/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

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

문제 해결

연결 실패 시

# MCP 삭제 후 재등록
claude mcp remove nexol-mcp
claude mcp add --scope user --transport http nexol-gw https://mcp.nexol.co.kr/mcp --header "Authorization: Bearer YOUR_API_KEY"

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

"Unexpected token" JSON 파싱 에러

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

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

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

네트워크 오류 시

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

# 서비스 상태 확인 (키 없이 보냅니다)
curl -o /dev/null -w "%{http_code}\n" -X POST https://mcp.nexol.co.kr/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

401이 나오면 서버는 정상이고 인증만 빠진 상태입니다. 연결 자체가 안 되면 000이 나옵니다.

연결 상태 진단

발급받은 키로 실제로 붙는지 확인하려면:

# 초기화 요청 (응답 헤더까지 보려면 -i)
curl -i -X POST https://mcp.nexol.co.kr/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

응답 헤더에 mcp-session-id가 있으면 정상입니다.

401 — 키가 없거나 잘못됐습니다. 관리자에게 재발급을 요청하십시오.
410 — 폐기된 옛 경로(/sse, /message)를 쓰고 있습니다. 위 명령처럼 /mcp로 보내십시오.
000 — 네트워크나 DNS 문제입니다. 사내망 연결을 확인하십시오.

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