MCP 서버 설정

세 가지 설정 스코프

MCP 서버는 목적에 따라 세 가지 위치에 설정할 수 있습니다.

| 스코프 | 파일 경로 | 공유 여부 | 용도 | |--------|-----------|-----------|------| | project | .mcp.json | 팀 공유 (Git 포함) | 프로젝트 공통 서버 | | user | ~/.claude.json | 개인 전역 | 모든 프로젝트에서 사용 | | local | ~/.claude.json | 개인 로컬 | 현재 프로젝트에서만 사용, 기본 스코프 |

// .mcp.json (프로젝트 공유 - Git에 커밋)
{
  "mcpServers": {
    "project-db": {
      "command": "node",
      "args": ["./scripts/mcp-server.js"]
    }
  }
}

// ~/.claude.json (사용자 전역)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}"]
    }
  }
}

stdio 서버 설정

로컬 프로세스를 MCP 서버로 실행하는 가장 일반적인 방식입니다.

{
  "mcpServers": {
    "my-tool": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py", "--port", "8080"],
      "env": {
        "PYTHONPATH": "/path/to/lib",
        "API_KEY": "${MY_API_KEY}",
        "DEBUG": "false"
      }
    }
  }
}

| 필드 | 필수 | 설명 | |------|------|------| | command | 예 | 실행할 명령어 | | args | 아니오 | 명령어 인수 배열 | | env | 아니오 | 추가 환경 변수 |

원격 HTTP 서버 설정

원격 MCP 서버에는 Streamable HTTP를 우선 사용합니다. SSE 전송은 폐기 예정이므로 기존 서비스와의 호환이 필요한 경우에만 유지합니다.

{
  "mcpServers": {
    "remote-service": {
      "type": "http",
      "url": "https://mcp.myservice.com/v1",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}",
        "X-Team-ID": "${TEAM_ID}"
      }
    }
  }
}

| 필드 | 설명 | |------|------| | type | 원격 권장값 http (streamable-http도 별칭으로 허용) | | url | 서버 엔드포인트 URL | | headers | HTTP 요청 헤더 |

환경 변수 확장

설정 파일에서 ${VAR} 또는 ${VAR:-default} 구문으로 환경 변수를 참조할 수 있습니다. 이 값들은 Claude Code 시작 시 셸 환경에서 확장됩니다.

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": ["./mcp-db-server.js"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_PORT": "${DB_PORT}",
        "DB_NAME": "${DB_NAME:-myapp}",
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

비밀 키나 토큰을 설정 파일에 직접 기입하지 말고 반드시 환경 변수로 관리하세요.

설정 예시 모음

// 파일시스템 서버
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  }
}

// 팀이 직접 유지하는 PostgreSQL MCP 서버
{
  "postgres": {
    "command": "node",
    "args": ["./tools/postgres-mcp/dist/server.js"],
    "env": { "POSTGRES_URL": "${DATABASE_URL}" }
  }
}

// 원격 HTTP 통합
{
  "issue-tracker": {
    "type": "http",
    "url": "https://mcp.example.com/mcp",
    "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
  }
}

서드파티 패키지를 npx -y로 실행하면 설치 시점의 코드를 바로 실행하게 됩니다. 패키지 소유자와 소스, 버전을 검토하고 프로덕션에서는 버전 고정과 최소 권한을 적용하세요. 검토된 원격 커넥터는 Anthropic Directory에서 찾을 수 있지만, 최종 신뢰 판단과 권한 검토는 사용자의 책임입니다.