Cursor에서 환경 매개변수로 MCP 서버 구성하기

Cursor에서 환경 매개변수로 모델 컨텍스트 프로토콜(MCP) 서버를 구성하면 민감한 정보를 안전하게 전달하고 서버 동작을 사용자 지정할 수 있습니다. 이 가이드는 MCP 서버에 대한 환경 변수 설정 및 관리에 대한 자세한 지침을 제공합니다.

MCP 서버 환경 구성 소개

모델 컨텍스트 프로토콜(MCP) 서버는 추가 도구와 리소스를 제공하여 Cursor의 AI 기능을 확장합니다. 환경 매개변수를 통해 다음을 수행할 수 있습니다:

• API 키와 인증 토큰을 안전하게 전달
• 코드를 수정하지 않고 서버 동작 구성
• 다양한 환경(개발, 스테이징, 프로덕션) 설정
• 배포 컨텍스트에 따라 서버 기능 사용자 지정

환경 매개변수를 사용하는 이유?

환경 매개변수는 여러 가지 장점을 제공합니다:

1. 보안: 민감한 정보를 코드베이스에서 분리
2. 유연성: 코드를 수정하지 않고 구성 변경 가능
3. 이식성: 다양한 환경에서 동일한 서버 실행
4. 관심사 분리: 구성과 구현을 별도로 유지

MCP 서버 구성 이해하기

환경 매개변수를 추가하기 전에 Cursor에서 MCP 서버 구성의 기본 구조를 이해하는 것이 중요합니다.

MCP 구성 파일 구조

MCP 서버는 다음 구조를 가진 JSON 파일에서 구성됩니다:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "KEY1": "value1",
        "KEY2": "value2"
      },
      "disabled": false,
      "autoApprove": ["tool1", "tool2"]
    }
  }
}

주요 구성 요소:

• server-name: MCP 서버의 고유 식별자
• command: 서버를 실행하는 명령어(예: node, python)
• args: 명령어에 전달되는 인수
• env: 서버 프로세스에 전달되는 환경 변수
• disabled: 서버 비활성화 여부
• autoApprove: 명시적 승인이 필요하지 않은 도구 목록

단계별 구성 가이드

1. MCP 구성 파일 찾기

MCP 구성 파일의 위치는 운영 체제에 따라 다릅니다:

Windows:

%APPDATA%\Code\User\globalStorage\tencent-cloud.coding-copilot\settings\Craft_mcp_settings.json

macOS:

~/Library/Application Support/Code/User/globalStorage/tencent-cloud.coding-copilot/settings/Craft_mcp_settings.json

Linux:

~/.config/Code/User/globalStorage/tencent-cloud.coding-copilot/settings/Craft_mcp_settings.json

2. 구성 파일 편집하기

1. 선호하는 텍스트 편집기에서 구성 파일 열기
2. 파일이 존재하지 않거나 비어 있는 경우, 다음 구조로 생성:

{
  "mcpServers": {}
}

3. 서버 구성 추가 또는 수정:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"],
      "env": {
        "API_KEY": "your-api-key-here",
        "DEBUG": "true",
        "PORT": "3000"
      },
      "disabled": false
    }
  }
}

3. 환경 매개변수 추가하기

MCP 서버에 환경 매개변수를 추가하려면:

1. 서버에 필요한 환경 변수 식별
2. 서버 구성의 env 객체에 추가
3. 구성 파일 저장

여러 환경 변수가 있는 예시:

"env": {
  "OPENAI_API_KEY": "sk-abcdef123456",
  "SERVER_PORT": "3000",
  "LOG_LEVEL": "info",
  "CACHE_ENABLED": "true",
  "MAX_TOKENS": "4096",
  "MODEL_NAME": "gpt-4",
  "TIMEOUT_MS": "30000"
}

4. MCP 서버에서 환경 변수 사용하기

MCP 서버 코드에서 이러한 환경 변수에 액세스할 수 있습니다:

JavaScript/Node.js:

const apiKey = process.env.API_KEY;
const debug = process.env.DEBUG === 'true';
const port = parseInt(process.env.PORT || '3000', 10);

console.log(`Starting server with API key ${apiKey} on port ${port}`);
if (debug) {
  console.log('Debug mode enabled');
}

Python:

import os

api_key = os.environ.get('API_KEY')
debug = os.environ.get('DEBUG') == 'true'
port = int(os.environ.get('PORT', '3000'))

print(f"Starting server with API key {api_key} on port {port}")
if debug:
    print("Debug mode enabled")

고급 구성 기법

환경 파일 사용하기

더 복잡한 구성의 경우 환경 파일을 사용할 수 있습니다:

1. .env 파일 생성:

API_KEY=your-api-key-here
DEBUG=true
PORT=3000

2. MCP 서버 구성 업데이트:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"],
      "env": {
        "ENV_FILE": "/path/to/.env"
      }
    }
  }
}

3. 서버 코드에서 환경 파일 로드:

JavaScript/Node.js (dotenv 사용):

require('dotenv').config({ path: process.env.ENV_FILE });

// 이제 변수에 액세스할 수 있습니다
const apiKey = process.env.API_KEY;

Python (python-dotenv 사용):

import os
from dotenv import load_dotenv

load_dotenv(os.environ.get('ENV_FILE'))

# 이제 변수에 액세스할 수 있습니다
api_key = os.environ.get('API_KEY')

환경 변수 확장

구성 내에서 다른 환경 변수를 참조할 수 있습니다:

"env": {
  "BASE_URL": "https://api.example.com",
  "API_ENDPOINT": "${BASE_URL}/v1/data",
  "HOME_DIR": "${HOME}/projects"
}

시스템 환경 변수 사용하기

구성에서 시스템 환경 변수를 참조할 수 있습니다:

"env": {
  "USER_HOME": "${HOME}",
  "SYSTEM_TEMP": "${TEMP}",
  "CURRENT_USER": "${USER}"
}

보안 모범 사례

API 키와 같은 민감한 정보를 포함한 환경 매개변수로 작업할 때는 다음 보안 모범 사례를 따르세요:

1. 민감한 정보를 절대 커밋하지 않기

• .gitignore를 사용하여 환경 파일 제외
• 실제 API 키가 포함된 구성 파일을 커밋하지 않기
• 커밋된 예시에는 자리 표시자 값 사용

2. 민감한 값에 암호화 사용하기

• 민감한 환경 변수 암호화 고려
• 가능한 경우 보안 키 관리 시스템 사용

3. 구성 파일에 대한 액세스 제한

• 적절한 파일 권한 설정
• 구성 파일을 볼 수 있고 편집할 수 있는 사람 제한

4. 정기적으로 비밀 교체하기

• API 키와 토큰을 주기적으로 변경
• 비밀이 변경될 때 구성 파일 업데이트

5. 환경 변수 검증하기

서버 코드에서 환경 변수를 사용하기 전에 검증:

function validateEnv() {
  const requiredVars = ['API_KEY', 'SERVER_PORT'];
  const missing = requiredVars.filter(varName => !process.env[varName]);
  
  if (missing.length > 0) {
    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
  }
}

validateEnv();

일반적인 문제 해결

환경 변수를 사용할 수 없음

문제: MCP 설정에서 구성된 환경 변수를 서버에서 사용할 수 없습니다.

해결책:

• 구성 파일 구문 확인
• 서버가 올바르게 시작되고 있는지 확인
• 구성 변경 후 Cursor 재시작
• 환경 관련 오류에 대한 서버 로그 확인

구성 파일을 찾을 수 없음

문제: Cursor가 MCP 구성 파일을 찾을 수 없습니다.

해결책:

• 파일 경로가 운영 체제에 맞게 올바른지 확인
• 디렉토리 구조가 없는 경우 생성
• 파일 권한 확인
• 파일 생성 후 Cursor 재시작

잘못된 JSON 형식

문제: 구성 파일에 JSON 구문 오류가 있습니다.

해결책:

• JSON 검증기를 사용하여 JSON 검증
• 누락된 쉼표, 괄호 또는 따옴표 확인
• 모든 속성 이름이 큰따옴표로 묶여 있는지 확인
• 후행 쉼표 제거

시작 시 서버 충돌

문제: MCP 서버가 시작 직후 충돌합니다.

해결책:

• 오류 메시지에 대한 서버 로그 확인
• 필요한 모든 환경 변수가 제공되었는지 확인
• 환경 변수 값이 올바른 형식인지 확인
• 파일 참조의 경로 문제 확인

일반적인 사용 사례 예시

1. OpenAI API 통합

{
  "mcpServers": {
    "openai-tools": {
      "command": "node",
      "args": ["/path/to/openai-server.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here",
        "MODEL": "gpt-4",
        "MAX_TOKENS": "8192",
        "TEMPERATURE": "0.7"
      }
    }
  }
}

2. 데이터베이스 연결

{
  "mcpServers": {
    "db-tools": {
      "command": "python",
      "args": ["/path/to/db-server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "user",
        "DB_PASSWORD": "password",
        "CONNECTION_POOL_SIZE": "10"
      }
    }
  }
}

3. 개발 vs. 프로덕션 설정

{
  "mcpServers": {
    "api-tools": {
      "command": "node",
      "args": ["/path/to/api-server.js"],
      "env": {
        "NODE_ENV": "development",
        "API_URL": "http://localhost:8080/api",
        "CACHE_ENABLED": "false",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

결론

Cursor에서 환경 매개변수로 MCP 서버를 구성하면 서버 동작을 사용자 지정하고 민감한 정보를 관리하는 유연하고 안전한 방법을 제공합니다. 이 가이드에 설명된 단계와 모범 사례를 따르면 MCP 서버에 대한 환경 변수를 효과적으로 설정하고 관리할 수 있습니다.

외부 API와 통합하든, 데이터베이스에 연결하든, 단순히 서버 동작을 사용자 지정하든, 환경 매개변수는 구성과 코드 사이에 깔끔한 분리를 제공하여 보안과 유지 관리성을 향상시킵니다.

추가 리소스

• 공식 Cursor 문서
• 모델 컨텍스트 프로토콜(MCP) 사양
• 환경 변수 모범 사례
• JSON 구성 가이드
• Cursor 커뮤니티 포럼