본문으로 건너뛰기

MCP Server 설정 가이드

개요​

이 문서는 다양한 환경에서 MCP(Model Context Protocol) Server를 설정하고 등록하는 방법을 설명합니다. MCP Server를 통해 AI 도구들이 시스템과 상호작용할 수 있습니다.

개발 도구별 MCP Server 설정​

Cursor AI에서 MCP Server 설정​

1. 설정 파일 위치​

Cursor AI의 MCP 설정은 다음 위치에 있습니다:

  • macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings\cline_mcp_settings.json

2. 빠른 시작 가이드​

  1. Cursor 설정 열기: Cmd+, (Mac) 또는 Ctrl+, (Windows/Linux)
  2. 검색창에 "MCP" 입력
  3. MCP Server 설정에 아래 예시 복사하여 붙여넣기
  4. 설정 저장 (Mac: 바로 사용 가능, Windows/Linux: Cursor 재시작)

3. 기본 설정 구조​

{
  "mcpServers": {
    "server-name": {
      "url": "서버 URL",
      "transport": "전송 방식",
      "name": "표시 이름",
      "description": "서버 설명",
      "capabilities": {
        "tools": ["사용 가능한 도구 목록"],
        "resources": []
      }
    }
  }
}

4. DTA Wide MCP Server 설정​

4.1 개발 환경 설정​
{
  "mcpServers": {
    "dta-wide-agent-qa": {
      "url": "https://dta-wide-agent-qa-dev.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server",
      "description": "시간 관리, 로깅, 모니터링 도구를 제공하는 MCP 서버",
      "capabilities": {
        "tools": [
          "get-current-time",
          "query-recent-errors",
          "analyze-error-patterns",
          "query-logs"
        ],
        "resources": []
      }
    }
  }
}
4.2 로컬 QA Agent 설정​
{
  "mcpServers": {
    "dta-wide-agent-qa": {
      "url": "http://localhost:3003/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server",
      "description": "QA 테스트 자동화 및 데이터 조회 도구",
      "capabilities": {
        "tools": [
          "questionnaire_data_query",
          "sleep_log_data_query",
          "get-current-time",
          "query-recent-errors",
          "analyze-error-patterns",
          "query-logs",
          "query-mobile-logs"
        ],
        "resources": []
      }
    }
  }
}

5. 전송 방식 선택​

5.1 Streamable HTTP 방식 (권장)​

가장 권장되는 방식으로, 실시간 스트리밍을 지원합니다.

{
  "transport": "streamable-http",
  "url": "https://your-server.com/v1/messages"
}
5.2 HTTP POST 방식 (대체 방법)​

Streamable HTTP가 작동하지 않을 경우 사용할 수 있는 대체 방법입니다.

{
  "mcpServers": {
    "dta-wide-mcp-http": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "http://localhost:3004/v1/mcp/request",
        "-H", "Content-Type: application/json",
        "-d"
      ],
      "transport": "stdio"
    }
  }
}

6. 다중 서버 설정​

여러 MCP 서버를 동시에 사용할 수 있습니다:

{
  "mcpServers": {
    "dta-wide-agent-qa": {
      "url": "https://dta-wide-agent-qa-dev.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server (Dev)",
      "description": "개발 환경 MCP 서버",
      "capabilities": {
        "tools": ["get-current-time", "query-logs"]
      }
    },
    "dta-wide-agent-qa-stage": {
      "url": "https://dta-wide-agent-qa-stage.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server (Stage)",
      "description": "스테이징 환경 MCP 서버",
      "capabilities": {
        "tools": ["get-current-time", "query-logs"]
      }
    },
    "dta-wide-agent-qa-local": {
      "url": "http://localhost:3003/v1/messages",
      "transport": "streamable-http",
      "name": "Local QA Agent",
      "description": "로컬 개발용 QA Agent",
      "capabilities": {
        "tools": ["questionnaire_data_query", "sleep_log_data_query"]
      }
    }
  }
}

VS Code에서 MCP Server 설정 (Claude Extension)​

1. Claude Extension 설치​

  1. VS Code Extensions에서 "Claude for VS Code" 검색 및 설치
  2. Extension 설정에서 MCP Server 추가

2. 설정 방법​

{
  "claude.mcpServers": {
    "dta-wide-mcp": {
      "url": "https://dta-wide-agent-qa-dev.weltcorp.com/v1/messages",
      "transport": "streamable-http"
    }
  }
}

터미널에서 직접 MCP 사용​

1. cURL을 통한 직접 호출​

# MCP Tool 호출 예시
curl -X POST https://dta-wide-agent-qa-dev.weltcorp.com/v1/mcp/request \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get-current-time",
      "arguments": {
        "timezone": "Asia/Seoul"
      }
    },
    "id": 1
  }'

2. Python SDK 사용​

import requests

def call_mcp_tool(tool_name, arguments):
    response = requests.post(
        "https://dta-wide-agent-qa-dev.weltcorp.com/v1/mcp/request",
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments
            },
            "id": 1
        }
    )
    return response.json()

# 사용 예시
result = call_mcp_tool("query-mobile-logs", {
    "startTime": "2024-01-15T00:00:00.000Z",
    "endTime": "2024-01-15T23:59:59.999Z",
    "platform": "iOS"
})

설정 적용 방법​

1. 설정 적용​

macOS: 설정 변경 후 바로 사용 가능 (재시작 불필요) Windows/Linux: Cursor를 완전히 종료하고 다시 시작

macOS 사용자

macOS에서는 대부분의 경우 설정 변경 후 바로 MCP 도구를 사용할 수 있습니다. 만약 도구가 인식되지 않는다면 Cursor를 재시작해보세요.

2. 연결 확인​

  1. Cursor에서 새 대화 시작
  2. MCP 도구 사용 시도: 
    현재 시간을 알려주세요 (get-current-time 도구 사용)
  3. 정상적으로 도구가 실행되면 설정 완료

3. 문제 해결​

연결 실패 시​

  1. 네트워크 확인

    # 서버 연결 테스트
    curl https://dta-wide-mcp-dev.weltcorp.com/v1/health

  2. 로컬 서버 확인 (로컬 환경)

    # QA Agent 실행 상태 확인
    curl http://localhost:3003/v1/health

  3. 방화벽/프록시 설정 확인

    • 기업 네트워크의 경우 프록시 설정 필요
    • 로컬 방화벽이 포트를 차단하지 않는지 확인

환경별 설정 가이드​

개발 환경​

{
  "mcpServers": {
    "dta-wide-dev": {
      "url": "https://dta-wide-agent-qa-dev.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server",
      "description": "시간 관리, 로깅, 모니터링 도구를 제공하는 MCP 서버",
      "capabilities": {
        "tools": [
          "get-current-time",
          "query-recent-errors",
          "analyze-error-patterns",
          "query-logs",
          "query-mobile-logs",
          "questionnaire_data_query",
          "sleep_log_data_query"
        ]
      }
    }
  }
}

프로덕션 환경​

{
  "mcpServers": {
    "dta-wide-prod": {
      "url": "https://dta-wide-agent-qa-prod.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Production",
      "description": "프로덕션 환경 - 읽기 전용",
      "capabilities": {
        "tools": [
          "query-logs",
          "query-mobile-logs"
        ]
      }
    }
  }
}

보안 고려사항​

1. 인증 토큰​

프로덕션 환경에서는 인증이 필요할 수 있습니다:

{
  "mcpServers": {
    "dta-wide-secure": {
      "url": "https://dta-wide-agent-qa-prod.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

2. 접근 제한​

  • 로컬 개발: localhost URL 사용
  • 내부 네트워크: VPN 연결 필요
  • 프로덕션: IP 화이트리스트 적용

고급 설정​

1. 환경 변수 사용​

{
  "mcpServers": {
    "dta-wide-dynamic": {
      "url": "${MCP_SERVER_URL}/v1/messages",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

2. 커스텀 도구 설정​

특정 도구만 활성화하려면:

{
  "capabilities": {
    "tools": [
      "questionnaire_data_query",
      "sleep_log_data_query"
    ],
    "disabledTools": [
      "query-recent-errors",
      "analyze-error-patterns"
    ]
  }
}

문제 해결 체크리스트​

  1. ✅ Cursor가 최신 버전인가?
  2. ✅ MCP 서버가 실행 중인가?
  3. ✅ 네트워크 연결이 정상인가?
  4. ✅ 설정 파일 JSON이 유효한가?
  5. ✅ 도구 이름이 정확한가?
  6. ✅ 전송 방식(transport)이 올바른가?
  7. ✅ Windows/Linux: Cursor를 재시작했는가?
  8. ✅ macOS: 설정 저장 후 새 대화를 시작했는가?

전체 설정 예시​

Cursor를 위한 완전한 설정 (복사해서 사용)​

{
  "mcpServers": {
    "dta-wide-agent-qa": {
      "url": "https://dta-wide-agent-qa-dev.weltcorp.com/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server",
      "description": "시간 관리, 로깅, 모니터링 도구를 제공하는 MCP 서버",
      "capabilities": {
        "tools": [
          "get-current-time",
          "query-recent-errors",
          "analyze-error-patterns",
          "query-logs"
        ],
        "resources": []
      }
    },
    "dta-wide-agent-qa-local": {
      "url": "http://localhost:3003/v1/messages",
      "transport": "streamable-http",
      "name": "DTA Wide Agent QA Server (Local)",
      "description": "QA 테스트 자동화 및 데이터 조회 도구",
      "capabilities": {
        "tools": [
          "questionnaire_data_query",
          "sleep_log_data_query",
          "get-current-time",
          "query-recent-errors",
          "analyze-error-patterns",
          "query-logs",
          "query-mobile-logs"
        ],
        "resources": []
      }
    }
  }
}

사용 예시​

설정 완료 후 Cursor에서 다음과 같이 사용할 수 있습니다:

// 시간 조회
"현재 한국 시간을 알려주세요"

// 모바일 로그 조회
"iOS 플랫폼에서 오늘 발생한 에러 로그를 조회해주세요"

// 설문 데이터 조회
"user-12345의 설문 응답 데이터를 조회해주세요"

// 에러 패턴 분석
"최근 24시간 동안의 에러 패턴을 분석해주세요"

관련 문서​