> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 서버

> SUNRA의 MCP 서버를 Cursor, VS Code, Cline, Windsurf 및 기타 개발 환경과 통합하여 AI 모델에 원활하게 액세스하는 방법을 알아보세요.

# SUNRA MCP 서버 설정

SUNRA 모델 컨텍스트 프로토콜(MCP) 서버는 널리 사용되는 개발 환경과 원활하게 통합되어 편집기나 IDE에서 직접 SUNRA의 AI 모델에 액세스할 수 있도록 합니다. 이 가이드에서는 다양한 도구를 사용하여 MCP 서버를 설정하는 방법을 안내합니다.

## MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 AI 도우미가 외부 리소스 및 도구에 안전하게 액세스할 수 있는 표준화된 방법입니다. SUNRA MCP 서버를 사용하면 다음을 수행할 수 있습니다.

* SUNRA에서 사용 가능한 **AI 모델 목록을 보고 검색**합니다.
* 모든 모델 엔드포인트에 **요청을 제출**합니다.
* 대기열 시스템에서 **상태를 확인**하고 결과를 검색합니다.
* **파일을 업로드**하고 모델 스키마를 관리합니다.
* **API 인증을 원활하게 관리**합니다.

## 전제 조건

MCP 서버를 설정하기 전에 다음을 확인하십시오.

1. **Node.js** 설치(버전 18 이상)
2. [대시보드](https://sunra.ai/dashboard/api-tokens)에서 **SUNRA API 키**
3. 선호하는 편집기/IDE 설치

## 설치

SUNRA MCP 서버는 npm 패키지로 제공됩니다.

```bash theme={null}
npm install -g @sunra/mcp-server
```

또는 npx와 함께 직접 사용합니다(권장).

```bash theme={null}
npx @sunra/mcp-server
```

## 편집기별 구성

### 커서

커서는 구성 파일을 통해 MCP를 지원합니다. 프로젝트 루트에 `.cursor/mcp.json`을 만들거나 업데이트합니다.

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"]
    }
  }
}
```

**대체 전역 구성** 사용자 설정:

1. 커서 설정 열기
2. "MCP 서버"로 이동
3. 다음을 사용하여 새 서버 추가:
   * **이름**: `sunra-mcp-server`
   * **명령**: `npx`
   * **인수**: `@sunra/mcp-server`

### VS Code

MCP를 지원하는 VS Code(호환 확장 프로그램 필요):

`.vscode/mcp.json` 만들기:

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "your-api-key-here"
      }
    }
  }
}
```

### 클라인

Cline은 설정을 통해 MCP 서버를 지원합니다. Cline 구성에 추가:

```json theme={null}
{
  "mcpServers": {
    "sunra": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "description": "SUNRA AI 모델 액세스"
    }
  }
}
```

### 윈드서프

Windsurf IDE의 경우 작업 공간 설정에서 MCP를 구성합니다.

```json theme={null}
{
  "mcp": {
    "servers": {
      "sunra-mcp-server": {
        "command": "npx",
        "args": ["@sunra/mcp-server"],
        "timeout": 30000
      }
    }
  }
}
```

### 클로드 데스크톱

Claude 데스크톱 구성 파일에 추가:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"]
    }
  }
}
```

### 기타 MCP 호환 도구

MCP를 지원하는 다른 모든 도구에 대해 이 일반 구성 패턴을 사용합니다.

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "${SUNRA_KEY}"
      }
    }
  }
}
```

## 환경 설정

### API 키 설정

SUNRA API 키를 여러 가지 방법으로 구성할 수 있습니다.

#### 옵션 1: 환경 변수(권장)

```bash theme={null}
export SUNRA_KEY="your-api-key-here"
```

Windows의 경우:

```cmd theme={null}
set SUNRA_KEY=your-api-key-here
```

#### 옵션 2: 구성 파일

일부 편집기에서는 MCP 구성에서 직접 환경 변수를 설정할 수 있습니다.

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### 옵션 3: 런타임 구성

MCP 서버는 `set-sunra-key` 도구를 사용하여 런타임에 API 키를 설정하는 것도 지원합니다.

## 사용 가능한 MCP 도구

구성되면 AI 도우미를 통해 이러한 도구에 액세스할 수 있습니다.

### 모델 관리

* `list-models` - 사용 가능한 모든 AI 모델 찾아보기
* `search-models` - 키워드로 모델 찾기
* `model-schema` - 특정 모델에 대한 입력/출력 스키마 가져오기

### 요청 관리

* `submit` - 모델 엔드포인트에 요청 제출
* `status` - 요청 상태 및 로그 확인
* `result` - 완료된 결과 검색
* `cancel` - 실행 중인 요청 취소
* `subscribe` - 제출하고 완료될 때까지 기다립니다.

### 파일 관리

* `upload` - SUNRA 스토리지에 파일 업로드

## 사용 예

### 사용 가능한 모델 목록 보기

```
list-models 도구를 사용하여 사용 가능한 AI 모델을 보여주세요.
```

### 이미지 생성

```
submit 도구를 사용하여 black-forest-labs/flux-1.1-pro/text-to-image 엔드포인트로 이미지를 생성합니다. 
프롬프트 사용: "일몰의 고요한 산 풍경"
```

### 요청 상태 확인

```
요청 ID 상태 확인: pd_xxxxxx
```

## 문제 해결

### 일반적인 문제

**MCP 서버를 찾을 수 없음**

* Node.js가 설치되어 있고 액세스 가능한지 확인
* 전역적으로 설치 시도: `npm install -g @sunra/mcp-server`
* 명령 경로가 올바른지 확인

**인증 오류**

* SUNRA\_KEY 환경 변수가 설정되어 있는지 확인
* [SUNRA 대시보드](https://sunra.ai/dashboard/api-tokens)에서 API 키가 유효한지 확인
* `set-sunra-key` 도구를 사용하여 키 설정 시도

**연결 시간 초과**

* 구성에서 시간 초과 값 늘리기
* 인터넷 연결 확인
* SUNRA API 상태 확인

**권한 오류**

* 구성 파일에 대한 적절한 파일 권한 확인
* 적절한 사용자 권한으로 실행 시도

### 도움 받기

문제가 발생하면 다음을 수행하십시오.

1. [SUNRA 설명서](https://docs.sunra.ai) 확인
2. 편집기의 MCP 설명서 검토
3. [GitHub](https://github.com/sunra-ai/sunra-clients/issues)에 문제 제기

## 다음 단계

MCP 서버가 구성되면 다음을 수행하십시오.

1. **모델 탐색**: `list-models`를 사용하여 사용 가능한 모든 AI 기능 확인
2. **예제 시도**: 간단한 텍스트-이미지 또는 텍스트-비디오 생성부터 시작
3. **워크플로 구축**: 복잡한 AI 파이프라인을 위해 여러 모델 결합
4. **사용량 모니터링**: [SUNRA 대시보드](https://sunra.ai/dashboard/)에서 API 사용량 추적

MCP 통합을 통해 강력한 AI 모델을 개발 워크플로에 직접 쉽게 통합하여 애플리케이션에서 빠른 프로토타이핑과 원활한 AI 기반 기능을 사용할 수 있습니다.