# 빠른 시작 가이드

## 1. Bkend가 뭔가요?

**Bkend는 AI를 통해 백엔드를 만드는 서비스에요!**

### 🤔 쉽게 설명하면?

**원하는 걸 말하면, AI가 대화로 백엔드를 만들어줍니다.**

```
일반적인 방법:
서버 구축 → 데이터베이스 설치 → API 개발 → 배포 설정 (며칠~몇 주)

Bkend MCP 사용 시:
AI에게 "Todo 앱 백엔드 만들어줘" (5분)
```

### ✨ MCP 연동하면 뭐가 좋나요?

| 기본 방식 | **Bkend MCP 연동** |
| --- | --- |
| 콘솔 웹사이트에서 클릭으로 설정 | **AI 에디터에서 ****자연어****로 요청** |
| "테이블 생성" 버튼 클릭 → 폼 작성 | **"Todo 테이블 만들어줘"** |
| 스키마를 직접 JSON으로 작성 | **AI가 알아서 스키마 설계** |

**예시 대화:**

```
👤 사용자: "Todo 앱 백엔드를 만들어줘. 제목, 완료여부, 우선순위 필드가 필요해"

🤖 AI:
  ✓ my-todo-app 프로젝트 생성 완료
  ✓ dev 환경 생성 완료
  ✓ todos 테이블 생성 완료

  API 엔드포인트: https://api-enduser.bkend.ai/data/todos(예시)

  이제 프론트엔드에서 이 API를 바로 사용할 수 있습니다!
```

---

## 2. 사전 준비 체크리스트

### 1️⃣ AI 에디터 설치

다음 중 **하나**를 선택하여 설치하세요:

| 에디터 | 추천 대상 | 다운로드 |
| --- | --- | --- |
| **Claude Code** ⭐⭐⭐ | 바이브 코딩 및 MCP 초보자 | [https://claude.com/product/claude-code](https://claude.com/product/claude-code) CLI 기반 설치(터미널 명령어 사용) |
| **Cursor** | VS Code 사용 경험자 | [https://cursor.com](https://cursor.com) |
| **Google Antigravity** | 구글 계정 사용자 | [https://antigravity.google](https://antigravity.google) |

### 2️⃣ Bkend 회원가입 및 조직&프로젝트 생성

Bkend 콘솔에 접속해 회원가입 후 조직과 프로젝트를 생성하세요. 현재 무료 플랜으로 시작 가능해요!

⇒ [https://console.bkend.ai](https://console.bkend.ai)

![1. 회원가입](https://upload.cafenono.com/image/slashpageHome/20251204/192305_176dq0wTi8yhImUGzu?q=80&s=1280x180&t=outside&f=webp)

![2. 조직생성](https://upload.cafenono.com/image/slashpageHome/20251204/192031_nGmcLSSIF0Gr38PmxG?q=80&s=1280x180&t=outside&f=webp)

![3. 프로젝트 생성](https://upload.cafenono.com/image/slashpageHome/20251204/192213_eOrTXx16rCgzAhhZS6?q=80&s=1280x180&t=outside&f=webp)

---

## 3. 필수 정보 2가지 복사하기

MCP 연동에는 **아래 2가지 정보**가 필요합니다.

### 1) 📋 Organization ID

**찾는 방법:**

1. [https://console.bkend.ai](https://console.bkend.ai)  콘솔 접속

2. 상단바에서 프로젝트를 진행할 **조직 선택**

3. **조직 설정** 메뉴 선택

4. "조직 ID" 항목 옆 **복사 아이콘** 클릭

📸 **스크린샷 참고**

`조직 설정 화면에서 [조직 ID] 복사`

![Image](https://upload.cafenono.com/image/slashpageHome/20251204/193327_hs3Ahd2T79oMFmnnhz?q=80&s=1280x180&t=outside&f=webp)

### 2) 🔑 API 키

**발급 방법:**

1. **조직 설정** 메뉴 진입

2. 상단 탭에서 **API 키** 선택

3. **액세스 토큰으로 이동** 버튼 클릭

4. **+ 토큰 생성** 버튼 클릭

5. 토큰 이름 입력 (예: "MCP 연동용")

6. 토큰 타입 **API 키** 선택

7. **권한 체크** 및 생성

_어떤 항목을 체크해야 하나요?_

API 키의 권한은 사용 목적에 따라 선택하면 됩니다. 즉, AI가 수행할 작업에 따라 권한을 선택하세요.

**추천 설정:**

- MCP로 백엔드 전체 관리 ⇒ 최하단 ***:* (전체 권한)** 선택
- 

- MCP로 데이터 조회만 (읽기 전용): ***:read** 선택

_💡 Tip: 콘솔 없이 MCP만으로 프로젝트, 환경, 테이블, 데이터를 모두 관리하려면 *:*를 선택하세요._

8. **생성된 키를 복사해 안전한 곳에 보관**

📸 **스크린샷 참고**

`[API 키 생성 버튼 위치]`

![Image](https://upload.cafenono.com/image/slashpageHome/20251204/194341_dOSV6INpvf5FXDyrNG?q=80&s=1280x180&t=outside&f=webp)

`[API 키 생성]`

![Image](https://upload.cafenono.com/image/slashpageHome/20251204/204734_AjOmUXIYYbdr4lq4Kt?q=80&s=1280x180&t=outside&f=webp)

`[API 키 복사]`

![Image](https://upload.cafenono.com/image/slashpageHome/20251204/204831_uxERWr6EN6k5YGDm9Q?q=80&s=1280x180&t=outside&f=webp)

---

## 4. AI 에디터 설정하기

사용하는 에디터를 선택해 안내를 따라 세팅하세요:

### 📂 Claude Code

### 방법 1: 프로젝트별 설정 (추천)

프로젝트 단위로 MCP를 설정하려면 이 방법을 사용하세요.

**1단계:** Claude Code 실행 후 프로젝트 폴더 열기

**2단계:** Claude Code에게 아래 메시지를 그대로 복사해서 보내기

```
프로젝트 루트에 .mcp.json 파일을 만들어줘. 내용은 이거야:

{
  "mcpServers": {
    "mcp-bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp",
      "headers": {
        "X-Organization-Id": "여기에_Organization_ID_붙여넣기",
        "X-Api-Key": "여기에_API_키_붙여넣기"
      }
    }
  }
}
```

**3단계:** Claude가 파일을 만들면, `여기에_XXX_붙여넣기` 부분을 실제 값으로 수정 요청

```
X-Organization-Id를 org_abc123... 으로,
X-Api-Key를 sk_live_abc123... 으로 바꿔줘
```

**4단계:** Claude Code 재시작

- `exit` 입력하고 Enter → 다시 `claude` 입력해서 실행

---

**터미널로 직접 생성하고 싶다면:**

Mac/Linux:

```
touch .mcp.json && open .mcp.json
```

Windows (PowerShell):

```
New-Item .mcp.json -ItemType File; notepad .mcp.json
```

열린 파일에 위 2단계에 있는 JSON 내용을 붙여넣고 저장하세요.

---

### 방법 2: 전역 설정

모든 프로젝트에서 Bkend MCP를 사용하려면 이 방법을 사용하세요.

**1단계:** 홈 디렉토리에 설정 파일 생성

Mac/Linux:

```
~/.claude/settings.json
```

Windows:

```
%USERPROFILE%\.claude\settings.json
```

**2단계:** 아래 내용을 복사해서 붙여넣기

```
{
  "mcpServers": {
    "mcp-bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp",
      "headers": {
        "X-Organization-Id": "여기에_Organization_ID_붙여넣기",
        "X-Api-Key": "여기에_API_키_붙여넣기"
      }
    }
  }
}
```

**3단계:** `여기에_XXX_붙여넣기` 부분을 실제 값으로 교체

**4단계:** Claude Code 재시작

> 💡 **Tip:** 전역 설정을 사용하면 어느 폴더에서 Claude Code를 실행해도 Bkend MCP가 자동으로 연결됩니다.

### 📂 Cursor

### 방법 1: GUI에서 설정하기

**1단계:** Cursor 실행

**2단계:** 설정 열기

- Mac: `Cmd + Shift + p`

- Windows: `Ctrl + Shift + p`

**3단계:** Open MCP Settings 섹션 선택

**4단계:** New MCP Server 버튼 클릭**r** 버튼 클릭

**5단계:** 아래 메시지를 그대로 복사해서 붙여넣기

```
{
  "mcpServers": {
    "mcp-bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp",
      "headers": {
        "X-Organization-Id": "여기에_Organization_ID_붙여넣기",
        "X-Api-Key": "여기에_API_키_붙여넣기"
      }
    }
  }
}
```

**6단계:** `여기에_XXX_붙여넣기` 부분을 실제 값으로 수정 요청

```
X-Organization-Id를 org_abc123... 으로,
X-Api-Key를 sk_live_abc123... 으로 바꿔줘
```

**7단계:** 파일 저장하기

- Mac: `Cmd + s`

- Windows: `Ctrl + s`

**8단계:** Cursor 재시작

---

### 방법 2: 설정 파일로 직접 입력

**옵션 1. 전역 설정 파일 경로:**

**Mac/Linux:**

```
~/.cursor/mcp.json
```

**Windows:**

```
%USERPROFILE%\.cursor\mcp.json
```

**옵션 2. 프로젝트 설정 파일 경로:**

**Mac/Linux:**

```
프로젝트 루트/.cursor/mcp.json
```

**Windows:**

```
프로젝트 루트\.cursor\mcp.json
```

**파일 내용:**

```
{
  "mcpServers": {
    "mcp-bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp",
      "headers": {
        "X-Organization-Id": "여기에_Organization_ID_붙여넣기",
        "X-Api-Key": "여기에_API_키_붙여넣기"
      }
    }
  }
}
```

> **참고:** Cursor는 최대 40개의 MCP 도구를 동시에 사용할 수 있습니다. 필요한 MCP만 활성화하는 것을 권장합니다.

### 📂 Google Antigravity

> Google Antigravity는 2025년 11월 출시된 Google의 AI 기반 개발 플랫폼으로, Gemini 3 Pro를 사용합니다.

### 방법 1: GUI로 설정하기 (추천)

**1단계:** Google Antigravity 실행

**2단계:** Agent 세션에서 사이드 패널 상단의 **"…"** 드롭다운 클릭

**3단계:** **MCP Servers** 선택하여 MCP Store 열기

**4단계:** 상단의 **Manage MCP Servers** 클릭

**5단계:** **View raw config** 선택하여 설정 파일 편집

**6단계:** 아래 내용을 추가

```
{
    "mcpServers": {
        "mcp-bkend": {
            "command": "npx",
            "args": [
                "-y",
                "supergateway",
                "--streamableHttp",
                "https://api.bkend.ai/mcp",
                "--header",
                "X-Organization-Id: 여기에_Organization_ID_붙여넣기",
                "--header",
                "X-Api-Key: 여기에_API_키_붙여넣기"
            ]
        }
    }
}
```

---

### 방법 2: 설정 파일로 직접 입력

**전역 설정 파일 경로:**

**Mac/Linux:**

```
~/.gemini/antigravity/mcp_config.json
```

**Windows:**

```
C:\Users\<사용자명>\.gemini\antigravity\mcp_config.json
```

위 경로의 파일을 열어 동일한 JSON 내용을 입력하세요.

---

**설정 확인:**

Google Antigravity를 재시작한 후 MCP Store에서 도구 목록이 표시되는지 확인하세요.

⚠️ **중요:** Antigravity는 활성 MCP 도구를 **약 25개**로 제한하는 것을 권장합니다. 50개 초과 시 경고, 80개 초과 시 에러가 발생할 수 있습니다.

💡 **문제 발생 시:** `~/.gemini/antigravity/logs` 폴더에서 로그를 확인할 수 있습니다.

💡 Antigravity는 현재 프로젝트별 MCP 설정을 지원하지 않습니다.

---

## 5. AI에게 '잘' 요청하기

세팅은 완료! 이제 AI가 여러분이 원하는 백엔드를 정확하게 만들려면, **명확한 요청**이 매우 중요합니다.

### 좋은 요청의 3가지 요소

1. **무엇을** 하고 싶은지 (테이블 생성, 필드 추가, 검색 최적화 등)

2. **어떤 정보**가 필요한지 (이름, 이메일, 날짜 등)

3. **제약 조건**이 있는지 (필수/선택, 중복 금지, 특정 값만 허용 등)

**간단한 예시:**

> ❌ "테이블 만들어줘"

> ✅ "이벤트 관리용 테이블 만들어줘. 이벤트 이름, 시작일, 종료일 정보 필요해."

💡 Tip**:** 필드명이나 변수명은 AI가 알아서 적절히 정해줄 거예요. 여러분은 **개념**만 명확히 전달하세요!

**👉 더 자세한 가이드: **AI에게 '잘' 요청하는 법 

---

## (선택) 테스트 서비스 만들어보기

AI에게 자연어로 백엔드를 만들어달라고 요청해볼까요?

### 🎯 시나리오: Todo 관리앱 백엔드

**1단계: 프로젝트와 환경 준비 (콘솔에서)**

먼저 [Bkend 콘솔](https://console.bkend.ai)에서 프로젝트와 환경을 만듭니다:

1. 콘솔 접속 → 우측 상단 **새 프로젝트** 버튼 클릭

2. 프로젝트명 입력 (예: "my-todo-app")

3. 프로젝트 생성 완료 후, **dev 환경** 생성

> 💡 **왜 콘솔에서 만드나요?**
> 프로젝트와 환경은 조직의 중요한 리소스이기 때문에 콘솔에서 권한을 확인하고 생성합니다.
> MCP는 그 안에서 데이터 테이블과 인프라를 자유롭게 만들고 관리하는데 사용됩니다.**MCP는 그 안에서 데이터 테이블과 인프라를 자유롭게 만들고 관리하는데 사용됩니다.**

**2단계: AI에게 테이블 생성 요청**

AI에게 이렇게 말해보세요:

```
Todo를 관리하는 앱 서비스용 백엔드를 만들려고 해.

프로젝트 이름은 my-todo-app이고, dev 환경에서 작업할거야.
할 일/완료 여부/우선순위를 작성해 관리하고 싶어.
```

**🤖 AI가 하는일 1: 프로젝트 확인**

```
🤖 AI: "my-todo-app 프로젝트가 있는지 확인하겠습니다."

[project_list 도구 호출]

"프로젝트가 정상적으로 생성되어 있네요."

✓ 프로젝트 확인 완료
```

**🤖 AI가 하는일 2:  테이블 생성**

```
🤖 AI: "todos 테이블을 생성하겠습니다."

[table_create 도구 호출]

✓ todos 테이블 생성 완료

스키마:
- title: string (필수, 1-200자)
- completed: boolean (필수, 기본값: false)
- priority: string (enum: low, medium, high)

자동 생성 필드:
- createdBy: 생성한 사용자 ID
- createdAt: 생성 시간
- updatedAt: 수정 시간

API 엔드포인트:
https://api-enduser.bkend.ai/data/todos

이제 프론트엔드에서 이 API를 바로 사용할 수 있습니다!
```

### 🎉 축하합니다!

백엔드가 완성되었습니다. 이제 다음을 할 수 있습니다:

✅ **REST API 자동 생성됨**

- GET `/data/todos` - 목록 조회

- POST `/data/todos` - 생성

- PATCH `/data/todos/:id` - 수정

- DELETE `/data/todos/:id` - 삭제

✅ **자동 기능**

- 사용자 인증 (회원가입/로그인)

- 권한 관리 (역할별 CRUD 권한)

- 데이터 검증 (스키마 기반)

- 버전 관리 (스키마 변경 이력)

---

## 실제로 해보니까 이런 문제가 나타났어요

### 💡 **Case 1: AI가 데이터 스키마를 너무 복잡하게 만들었어요**

**문제: **

AI가 자동으로 `tags`, `dueDate`, `description`, `category` 같은 필드를 추가했는데, 당장 필요 없어요.

**해결:**

```
👤 사용자: "너무 복잡해. 제목, 완료여부, 우선순위만 있으면 돼."

🤖 AI: "스키마를 단순하게 수정하겠습니다."
[table_manage_fields 도구로 불필요한 필드 삭제]
```

### **💡 Case 2: 필요한 데이터가 더 생겼어요**

**요청:**

```
👤 사용자: "마감일(dueDate) 데이터도 필요해. 날짜 형식이면 돼."

🤖 AI: "dueDate 필드를 추가하겠습니다."
[table_manage_fields 도구 호출]

✓ 필드 추가 완료 (새 스키마 버전 생성됨)
```

### **💡 Case 3: 실수로 잘못 만들었어요**

**해결:**

```
👤 사용자: "방금 만든 테이블 삭제해줘."

🤖 AI: "todos 테이블을 삭제하겠습니다."
[table_delete 도구 호출]

✓ 테이블 삭제 완료 (소프트 삭제, 복원 가능)

다시 복원이 필요하면 "todos 테이블 복원해줘" 라고 요청하세요.
```

---

**문서 버전:** 0.1.0  |  **최종 수정: **2025-12-04

For the site tree, see the [root Markdown](https://slashpage.com/bkend.md).