# 데브다이브 개발자 문서

> 데브다이브 AI를 MCP로, 또는 API 키로 내 프로그램에서 쓰는 방법

This file contains all documentation content in a single document following the llmstxt.org standard.

## 소개

## 데브다이브 개발자 문서

데브다이브의 AI(글쓰기, 이미지·영상·음성 생성, 문서·이미지 분석, 웹 검색, 에디터 워크플로우)를
MCP로 연결해서 쓸 수 있어요. 쓴 만큼 **데브다이브 계정의 크레딧**이 차감됩니다.

| 방법 | 이런 분께 | 필요한 것 | 시작하기 |
| --- | --- | --- | --- |
| **MCP**: ChatGPT·Claude 안에서 대화로 | 코딩 없이 쓰고 싶은 분 | 데브다이브 계정 | [ChatGPT·Claude에 연결하기](./mcp/connect-chat.md) |
| **MCP**: Claude Code·Cursor 같은 개발 도구에서 | 설정 파일로 AI 도구를 쓰는 분 | API 키 (`DDSK-…`) | [개발 도구에 연결하기](./mcp/connect-dev-tools.md) |
| **API**: 내 프로그램에서 직접 | 서비스·자동화에 붙이려는 개발자 | 준비 중 | [API로 쓰기](./api.md) |

### 주소

MCP 연결 주소는 `https://mcp.devdive.ai/mcp` 하나예요.

### MCP와 API, 무엇이 다른가요

- **MCP**는 ChatGPT·Claude 같은 AI 앱에 데브다이브를 도구로 붙이는 방식이에요. AI가 대화를 보고 알맞은
  도구를 골라 불러요. 오래 걸리는 작업은 기다렸다가 결과를 보여 주고, 결과 파일은 링크와 카드로 받아요.
  워크플로우(여러 단계를 이어 붙인 작업)를 저장하고 다시 실행하는 기능은 MCP에서만 쓸 수 있어요.
- **API**는 내 코드에서 모델을 직접 부르는 방식이에요. 지금은 준비 중이에요. → [API로 쓰기](./api.md)

:::tip 문서를 AI에게 통째로 주기
이 문서 전체를 한 파일로 [`/llms-full.txt`](https://docs.devdive.ai/llms-full.txt)에서, 목차는
[`/llms.txt`](https://docs.devdive.ai/llms.txt)에서 받을 수 있어요. 코딩 도우미에게 붙여 주면 예시 코드를 더 정확하게 써요.
:::

---

## API 키

데브다이브 API 키는 `DDSK-`로 시작하는 문자열이에요. 키 하나가 데브다이브 계정 하나를 가리키고, 그 키로
부른 모든 호출은 그 계정의 크레딧에서 차감돼요.

키는 **개발 도구를 MCP로 연결할 때** `Authorization: Bearer DDSK-…` 헤더에 넣어요.
→ [개발 도구에 연결하기](./mcp/connect-dev-tools.md)

내 프로그램에서 키로 직접 부르는 공개 API는 [준비 중](./api.md)이에요.

ChatGPT·Claude 웹에서 MCP로 쓸 때는 데브다이브 계정으로 로그인만 하면 돼서 키가 필요 없어요.

### 키 받기

1. 데브다이브 웹에 로그인하고 **설정 › API 키**를 열어요.
2. **새 키 발급**을 누르면 새 키가 창에 떠요.
3. **복사**를 눌러 바로 안전한 곳에 넣어 두세요.

:::caution 키는 발급할 때 한 번만 보여요
창을 닫으면 키 전체를 다시 볼 수 없어요. 목록에는 앞뒤 몇 글자만 보여요. 키를 잃어버렸으면 새로 발급하세요.
:::

계정을 만들 때 자동으로 생긴 키도 목록에 있지만 전체 값은 보이지 않아요. 새 키를 발급해서 쓰세요. 키를 여러 개
발급해도 모두 같은 계정의 크레딧에서 차감돼요.

### 사용량과 크레딧 보기

- **남은 크레딧**: 데브다이브 웹 **설정 › 크레딧**
- **키로 쓴 사용량**(기능·모델별 사용 금액과 호출 수): 데브다이브 웹 **설정 › 모델 사용량**
- MCP로 연결했다면 대화에서 "남은 크레딧 알려줘"라고 물어도 돼요(`get_credits`, `get_usage` 도구).

### 키 지키기

:::caution 키는 비밀번호와 같아요
키를 아는 사람은 누구나 내 크레딧으로 모델을 부를 수 있어요.

- 브라우저·앱처럼 **사용자 기기에서 도는 코드에 키를 넣지 마세요.** 키는 내 서버에서만 쓰고, 화면에는 결과만 보내 주세요.
- 키를 코드에 직접 쓰지 말고 환경 변수(`DEVDIVE_API_KEY` 등)로 읽으세요. 공개 저장소에 올라가지 않게 `.env`는 커밋하지 마세요.
- 키가 새어 나간 것 같으면 바로 데브다이브 팀에 알려 주세요. 아직 웹에서 키를 직접 폐기할 수는 없어요.
:::

---

## ChatGPT·Claude에 연결하기

ChatGPT나 Claude에 **연결 주소를 붙여 넣고 데브다이브 계정으로 로그인**하면 끝이에요. API 키는 필요 없어요.

연결 주소:

```text
https://mcp.devdive.ai/mcp
```

[데브다이브 MCP 연결 안내](https://www.devdive.ai/ko/mcp)에서 같은 과정을 화면으로 볼 수 있어요.

:::info
ChatGPT·Claude가 화면을 바꾸면 메뉴 이름과 순서가 아래와 조금 다를 수 있어요.
:::

### ChatGPT

1. 왼쪽 메뉴에서 **플러그인**을 열어요.
2. **추가 ⌄ › 사용자 지정 MCP 서버 추가**를 눌러요.
3. 창에 이렇게 넣어요.
   - **이름**: `데브다이브`
   - **연결**: 서버 URL에 `https://mcp.devdive.ai/mcp`
   - **인증**: `OAuth`. 고급 OAuth 설정은 그대로 두세요(자동으로 찾아요).
4. 안내를 읽고 **이해했으며 계속 진행하겠습니다**에 체크한 뒤 **플러그인으로 생성**을 눌러요.
5. **데브다이브 연결** 창이 뜨면 연결을 누르고, 새 탭에서 데브다이브 계정으로 로그인한 뒤 **허용**을 눌러요.
6. 새 채팅의 **+** 에서 데브다이브를 고르고 "데브다이브에서 쓸 수 있는 모델 알려줘"처럼 물어보세요.

ChatGPT는 크레딧을 쓰거나 무언가를 만들고 바꾸는 도구(이미지·영상 생성, 워크플로우 실행 등)를 실행하기 전에
확인을 물을 수 있어요. 모델 목록·크레딧 같은 조회는 바로 실행돼요.

### Claude

1. **설정 › 커넥터**를 열어요.
2. **+ 추가 ⌄ › 커스텀 커넥터 추가**를 눌러요.
3. 이름(`데브다이브`)과 MCP 서버 URL(`https://mcp.devdive.ai/mcp`)을 넣고 **계속**을 눌러요.
4. Claude가 서버를 확인하면 인증은 **지금 로그인**, OAuth 클라이언트는 **자동으로 등록**으로 나와요. 그대로 **추가**를 눌러요.
5. 데브다이브 로그인 창에서 로그인하고 **허용**을 눌러요.
6. 대화창의 **+ › 커넥터**에서 데브다이브가 켜져 있는지 확인하고 물어보세요.

Claude 데스크톱 앱도 claude.ai 계정의 커넥터를 같이 써요.

### 허용 화면에서 확인할 것

허용 화면에는 **어떤 앱이** 연결을 요청하는지와 **로그인 결과가 전달될 주소**가 나와요. 내가 방금 추가한
앱(ChatGPT → `chatgpt.com`, Claude → `claude.ai`)이 맞는지 보고 허용하세요. 모르는 요청이면 **거부**를 누르세요.

### 이렇게 말해 보세요

- "바닷가를 달리는 강아지 영상 만들어줘"
- "이 사진을 인스타그램 광고 이미지로 바꿔줘" (사진 첨부 → [파일 첨부](./files.md))
- "첨부한 PDF 세 줄로 요약해줘"
- "이 글을 차분한 목소리로 읽어줘"
- "내 워크플로우 중에 '상품 소개' 있으면 이번 상품으로 다시 돌려줘"
- "남은 크레딧 알려줘"

쓸 수 있는 도구 전체는 [쓸 수 있는 도구](./tools.md)에 있어요.

### 연결 끊기

데브다이브 웹 **설정 › API 키** 아래 **연결된 앱**에서 연결된 ChatGPT·Claude를 보고 바로 해제할 수 있어요.
ChatGPT·Claude 쪽에서 플러그인·커넥터를 지워도 돼요. 90일 동안 쓰지 않은 연결은 자동으로 풀려요.

---

## 개발 도구에 연결하기

설정 파일이나 명령으로 MCP 서버를 등록하는 개발 도구는 **연결 주소 + API 키 헤더**로 연결해요.
[API 키](../api-key.md)를 먼저 준비하세요.

| 항목 | 값 |
| --- | --- |
| 연결 주소 | `https://mcp.devdive.ai/mcp` |
| 전송 방식 | Streamable HTTP |
| 헤더 | `Authorization: Bearer DDSK-…` |

### Claude Code

```bash
claude mcp add --transport http --scope user devdive https://mcp.devdive.ai/mcp \
  --header "Authorization: Bearer $DEVDIVE_API_KEY"
```

`--scope user`로 등록하면 모든 프로젝트에서 쓸 수 있어요. 등록한 뒤 Claude Code에서 `/mcp`를 열면
`devdive`가 연결됨으로 보여요.

### Cursor

`~/.cursor/mcp.json`(모든 프로젝트) 또는 프로젝트의 `.cursor/mcp.json`에 넣어요.

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "devdive": {
      "url": "https://mcp.devdive.ai/mcp",
      "headers": { "Authorization": "Bearer DDSK-여기에-키" }
    }
  }
}
```

프로젝트의 `.cursor/mcp.json`에 키를 넣었다면 그 파일은 커밋하지 마세요.

### VS Code

프로젝트의 `.vscode/mcp.json`에 넣어요. 키는 파일에 쓰지 않고 처음 연결할 때 한 번 물어보게 했어요.

```json title=".vscode/mcp.json"
{
  "inputs": [
    { "type": "promptString", "id": "devdive-key", "description": "데브다이브 API 키", "password": true }
  ],
  "servers": {
    "devdive": {
      "type": "http",
      "url": "https://mcp.devdive.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:devdive-key}" }
    }
  }
}
```

### 그 밖의 도구

원격 MCP 서버(Streamable HTTP)와 헤더 설정을 지원하는 도구라면 위 표의 세 값으로 연결할 수 있어요.

### 연결이 안 될 때

- **401**: 키가 틀렸거나 `Bearer ` 뒤에 공백·줄바꿈이 섞였어요. 키 앞뒤를 다시 확인하세요.
- **503**: 데브다이브 로그인 서버가 잠시 답하지 않아요. 조금 뒤에 다시 연결하세요.
- 도구 목록이 비어 있으면 도구를 다시 시작하거나 MCP 서버를 새로 고침하세요.

---

## 쓸 수 있는 도구

연결하면 AI가 아래 도구를 알아서 골라 불러요. 도구 이름을 직접 말할 필요는 없지만, 원하는 도구가 있으면
"`generate_video`로 만들어줘"처럼 짚어 줘도 돼요.

### 계정

| 도구 | 하는 일 |
| --- | --- |
| `list_models` | 쓸 수 있는 모델 목록 |
| `get_credits` | 남은 크레딧 |
| `get_usage` | 날짜별 크레딧 사용 내역 |

### 글·검색

| 도구 | 하는 일 |
| --- | --- |
| `generate_text` | 글쓰기·요약·번역 (GPT-5.6, Claude 모델) |
| `web_search` | 웹 검색 결과 목록 (Brave, Perplexity) |
| `research` | 웹을 찾아 출처와 함께 답 쓰기 (Perplexity Sonar) |

### 이미지

| 도구 | 하는 일 |
| --- | --- |
| `generate_image` | 문장으로 이미지 만들기 (GPT Image 2.5) |
| `edit_image` | 사진을 참고해 바꾸기 (얼굴·제품을 유지하고 장면 바꾸기 등) |
| `analyze_image` | 사진 설명·질문에 답하기 |

### 영상

| 도구 | 하는 일 |
| --- | --- |
| `generate_video` | 문장으로 영상 만들기 (WAN 3.0, HappyHorse) |
| `animate_image` | 사진을 첫 장면으로 움직이게 하기 |
| `reference_to_video` | 인물·사물 참고 이미지로 영상 만들기 |
| `edit_video` | 영상을 문장으로 고치기 |
| `transfer_motion` | 사진 속 인물이 영상 속 동작을 따라 하게 하기 |

### 음성·음악·문서

| 도구 | 하는 일 |
| --- | --- |
| `text_to_speech` | 글을 목소리로 (ElevenLabs) |
| `list_voices` | 고를 수 있는 목소리 찾기 |
| `transcribe` | 오디오를 글로 (Whisper) |
| `generate_music` | 가사로 노래 만들기 (MiniMax) |
| `analyze_document` | PDF 등 문서 요약·마크다운으로 바꾸기 |

### 파일

| 도구 | 하는 일 |
| --- | --- |
| `upload_file` | 첨부 파일이나 공개 URL을 내 데브다이브 드라이브에 올리기 |
| `create_upload_link`, `get_upload_link` | 내 파일을 직접 올릴 일회용 링크 만들기·확인 |
| `list_drive` | 드라이브에 있는 파일과 생성 결과 찾기 |

자세한 사용법은 [파일 첨부](./files.md)에 있어요.

### 워크플로우

워크플로우는 데브다이브 에디터에 저장해 두고 다시 쓰는 여러 단계 작업이에요(보고서, 블로그 글, 포스터,
카드뉴스 등). 같은 일을 반복한다면 매번 처음부터 시키지 말고 워크플로우로 저장해 두세요.

| 도구 | 하는 일 |
| --- | --- |
| `search_workflows`, `list_workflows` | 저장해 둔 워크플로우 찾기 |
| `run_workflow_by_id` | 저장한 워크플로우를 이번 입력으로 실행 |
| `run_workflow` | 저장하지 않고 단계를 바로 실행 |
| `get_workflow_run`, `get_run_output` | 실행 진행 상황과 단계별 결과 |
| `create_workflow` | 새 워크플로우 저장 |
| `get_workflow`, `update_workflow`, `edit_workflow_step` | 워크플로우 보기·고치기 |
| `restore_workflow` | 고치기 전으로 되돌리기 |

### 오래 걸리는 작업

이미지·영상·음악 생성과 음성 인식은 몇십 초에서 몇 분 걸려요. 도구는 작업을 맡기고 `get_job`으로 결과를
기다려요. 한 번에 약 45초까지 기다리고, 그래도 안 끝나면 AI가 같은 작업을 이어서 기다려요(다시 만들지 않아요).
결과 파일은 링크로 받고, 링크는 **3일 동안** 열려요. 오래 둘 파일은 내려받아 두세요.

### 결과 카드

Claude(웹·데스크톱)와 ChatGPT처럼 MCP Apps를 지원하는 앱에서는 결과가 대화창에 **카드**로 떠요. 카드에서
이미지·영상·음성을 바로 보고 내려받을 수 있고, 워크플로우 카드는 단계별 진행과 결과를 보여 줘요.
카드를 지원하지 않는 앱에서는 같은 결과가 링크와 글로 와요.

---

## 파일 첨부

이미지 편집, 사진으로 영상 만들기, 문서 요약처럼 내 파일이 필요한 도구는 **파일을 링크로** 받아요.
그래서 파일을 먼저 내 데브다이브 드라이브에 올리고, 받은 링크를 도구에 넘겨요. AI가 알아서 하지만, 앱마다
첨부가 전달되는 방식이 달라서 아래처럼 동작해요.

### ChatGPT

채팅창에 파일을 첨부하고 평소처럼 부탁하세요. ChatGPT가 `upload_file`로 파일을 드라이브에 올린 뒤 그 링크를 씁니다.
첨부가 도구까지 전달되지 않을 때가 가끔 있어요(특히 모바일). 그럴 땐 파일을 다시 첨부해 주세요.

### Claude

Claude는 채팅에 첨부한 파일을 볼 수는 있지만, 파일 자체를 MCP 도구에 넘기지는 못해요. 그래서
`create_upload_link`로 **일회용 업로드 링크**를 만들어요.

- **코드 실행이 켜져 있고 `mcp.devdive.ai`로 나가는 네트워크가 허용돼 있으면** Claude가 첨부 파일을 그 링크로
  직접 올려요. Claude **설정 › 기능**의 코드 실행 허용 도메인에 `mcp.devdive.ai`를 추가하세요(팀·엔터프라이즈는 관리자가 설정).
- **그렇지 않으면** Claude가 링크(`https://mcp.devdive.ai/upload/…`)를 알려 줘요. 링크를 열어 파일을 고르고,
  대화로 돌아와 "다 올렸어"라고 하면 Claude가 `get_upload_link`로 파일을 가져다 써요. 로그인은 필요 없어요.

### 개발 도구 (Claude Code, Cursor 등)

- 공개 https 주소가 있는 파일은 `upload_file`의 `url`로 넘기면 돼요.
- 내 컴퓨터의 파일은 `create_upload_link`가 준 `upload_url`로 올려요.

  ```bash
  curl -F "file=@photo.png" "<upload_url>"
  ```

### 알아 두기

| 항목 | 내용 |
| --- | --- |
| 올릴 수 있는 파일 | 이미지·영상·오디오·PDF, 파일당 최대 50MB |
| 업로드 링크 | 만든 뒤 30분 동안, 링크 하나에 파일 10개까지 |
| 결과·업로드 파일 링크 | 3일 동안 열림 |

- 파일 형식은 이름이 아니라 내용으로 확인해요. 이름만 바꾼 실행 파일, SVG·HTML, 스크립트가 든 PDF는 올라가지 않아요.
- 올린 파일은 숨은 내용을 걸러 내고 다시 만들어 저장해요. 사진의 위치 정보 같은 메타데이터도 지워져요.
- 업로드 링크를 아는 사람은 누구나 내 드라이브에 파일을 올릴 수 있어요. 다른 사람과 나누지 마세요.
- 이미 올린 파일과 생성 결과는 `list_drive`로 다시 찾아 쓸 수 있어요.

---

## API로 쓰기

내 프로그램에서 API 키로 데브다이브 AI를 직접 부르는 공개 API를 준비하고 있어요. 열리면 이 자리에 주소와
요청 방법을 올릴게요.

그때까지는 MCP로 쓸 수 있어요. Claude Code·Cursor 같은 개발 도구는 API 키로 연결해요.
→ [개발 도구에 연결하기](./mcp/connect-dev-tools.md)

---

## 자주 묻는 질문

#### MCP로 쓰면 크레딧이 더 드나요?

아니요. MCP로 쓰든 데브다이브 웹에서 쓰든 같은 모델은 같은 크레딧이 차감돼요.

#### ChatGPT·Claude 요금제가 따로 필요한가요?

ChatGPT·Claude에서 커스텀 MCP 커넥터를 추가할 수 있는 요금제인지는 각 서비스의 안내를 확인하세요. 데브다이브
크레딧은 그와 별개로 데브다이브 계정에서 차감돼요.

#### 팀원 여러 명이 한 계정을 같이 써도 되나요?

네. 각자 자기 ChatGPT·Claude에서 같은 데브다이브 계정으로 로그인하면 돼요. 크레딧은 그 계정에서 함께 차감돼요.

#### 만든 이미지·영상은 어디에 있나요?

결과 링크는 3일 동안 열려요. 생성 결과는 데브다이브 드라이브에도 남아서, MCP에서는 `list_drive`로 다시 찾을 수
있어요.

#### 연결을 끊고 싶어요

데브다이브 웹 **설정 › API 키** 아래 **연결된 앱**에서 해제하세요. → [연결 끊기](./mcp/connect-chat.md#연결-끊기)

#### 결과를 기다리다 응답이 끊겼어요. 다시 시켜도 되나요?

같은 생성을 다시 시키면 두 번 만들고 두 번 차감될 수 있어요. 같은 대화에서 결과를 다시 물어보세요. AI가 받아 둔
작업 ID로 이어서 기다려요.