> For the complete documentation index, see [llms.txt](https://docs.salesmap.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.salesmap.kr/developers/mcp/getting-started.md).

# 시작하기

본 문서에서는 세일즈맵 MCP 연결 방법에 대해 다룹니다.

### 1단계: 세일즈맵 API 토큰 준비

1. [세일즈맵](https://salesmap.kr) 접속 → 좌측 하단 **설정**
2. **개인 → 연동 → API** 메뉴로 이동
3. **이미 토큰이 있다면 → 복사** / **토큰이 없다면 → 토큰 생성** 클릭 후 복사

{% hint style="warning" %}
**토큰은 절대 다른 사람과 공유하지 마세요.**\
토큰을 재발급하면 기존 연동이 끊어질 수 있습니다. 이미 토큰이 있다면 새로 만들지 말고 복사해서 사용하세요.
{% endhint %}

***

### 2단계: AI에 연결

{% tabs %}
{% tab title="Claude" %}
{% hint style="info" %}
요건: Claude 유료 플랜 (Pro/Max/Team/Enterprise)
{% endhint %}

1. [claude.ai](https://claude.ai) / Claude Desktop 접속 → 좌측 하단 프로필 → 설정 → **커넥터**
2. 추가 → **커스텀 커넥터 추가** 클릭<br>

   <figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2Fgit-blob-7791e05c3315445537ec49f10bbe07da72d6a1cf%2Fimage%20(11).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>
3. 아래와 같이 입력합니다.

   * 이름: `세일즈맵`
   * 원격 MCP 서버 URL: `https://mcp.ai.salesmap.kr/mcp`
   * 인증, OAuth 클라이언트, 전송 방식 항목은 아래 기본값 그대로 둔 뒤 추가를 클릭합니다.\
     인증: 지금 로그인\
     OAuth 클라이언트: 자동으로 등록\
     전송 방식: 스트리밍 HTTP

   <figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FPOJXsRirjRrP69wPJl5o%2Fimage.png?alt=media&amp;token=e0c5e2a7-b646-4b0c-a547-e38198894c7d" alt="" width="375"><figcaption></figcaption></figure>
4. **연결** 클릭
5. 복사해 둔 **API 토큰을 붙여넣고 \[연결 승인]** 클릭<br>

   <figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FTApZBUUhaRjq7vYYBHsj%2Fimage.png?alt=media&amp;token=1ea48d19-4885-4794-9643-d9abe30d215f" alt="" width="413"><figcaption></figcaption></figure>

{% endtab %}

{% tab title="ChatGPT" %}
{% hint style="info" %}
요건: ChatGPT 유료 플랜 (Plus/Pro/Business/Enterprise)
{% endhint %}

[chatGPT App 설정](https://docs.salesmap.kr/developers/mcp/getting-started#chatgpt-app)은 바로 오른쪽 탭에 있습니다.

1. [chatgpt.com](https://chatgpt.com) → 프로필 → **설정**
2. 플러그인 → 디렉토리 둘러보기
3. 추가 버튼 -> 사용자 지정 mcp 서버 추가 클릭 후 입력

* 이름: `세일즈맵`
* 연결: `https://mcp.ai.salesmap.kr/mcp`
* 인증: **OAuth**

<figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FcBeorOCFpjHh8Hi5bnZV%2Fimage.png?alt=media&amp;token=c5c14f42-11ae-4589-93e9-c867eb0fc3d0" alt="" width="345"><figcaption></figcaption></figure>

4. 만들기 클릭 → **세일즈맵 계정으로 로그인**
5. 복사해 둔 **API 토큰을 붙여넣고 \[연결 승인]** 클릭

<figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FO2ljhUvQjL8i5aKlMc27%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-10-16%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%209.21.50.png?alt=media&amp;token=c28443d7-ac0e-4a40-8ac1-f67fc05048e9" alt="" width="375"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="chatGPT App(codex App)" %}
{% hint style="info" %}
요건: ChatGPT 유료 플랜 (Plus/Pro/Business/Enterprise)
{% endhint %}

1. chatGPT app -> 프로필 -> 설정

   \- chatGPT 앱은 chatGPT classic, chatGPT로 2가지의 버전이 있습니다. 이 중 classic 버전은 mcp를 지원하지 않으니 [chatGPT 버전](https://chatgpt.com/ko-KR/download/)을 사용해주세요)

   * chatGPT classic

   <figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2Fhpzs6dkJ7LC5dOWCMFYe%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-10-15%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.15.22.png?alt=media&amp;token=42a91efd-39f5-4731-b948-39c801ddc8bf" alt="" width="159"><figcaption></figcaption></figure>

   * chatGPT

   <figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2F1uPXcAiFXG7tG2HAbYVv%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-10-15%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.15.27.png?alt=media&amp;token=dc8fea9d-4f2a-4c43-966a-9a5fbea0b6ee" alt="" width="109"><figcaption></figcaption></figure>
2. 플러그인-> 추가 버튼 -> mcp 서버 추가 클릭 후 입력<br>

* 이름: `세일즈맵`
* 유형: `스트리밍 가능한 HTTP`
* 연결: `https://mcp.ai.salesmap.kr/mcp`

<figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FqjNUTyIm4kRL3m7wbf8R%2Fimage.png?alt=media&amp;token=7f5c2e8f-2612-4893-9027-b66f858a53df" alt="" width="563"><figcaption></figcaption></figure>

3. 저장 클릭 후 인증 버튼 클릭

<figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FRkYF0SZLYyurSsHPFyvH%2Fimage.png?alt=media&amp;token=a8349ba8-a0ee-4f61-b919-69dcfcbb4858" alt=""><figcaption></figcaption></figure>

4. 복사해 둔 **API 토큰을 붙여넣고 \[연결 승인]** 클릭

<figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FjrIpYCg0zH5LCendwKad%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-10-16%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%209.20.43.png?alt=media&amp;token=42575749-8a20-46bb-8d2e-988c3cc3aa6d" alt="" width="375"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Gemini" %}
{% hint style="warning" %}
현재 Google 정책상 한국 계정에서는 MCP 연동을 지원하지 않습니다.
{% endhint %}

1. [gemini.google.com/apps](https://gemini.google.com/apps) 접속
2. 앱 추가에 서버 URL 입력: https//mcp.ai.salesmap.kr/mcp
3. 세일즈맵 연결 페이지가 열리면 **API 토큰을 붙여넣고 \[연결 승인]**<br>

   <figure><img src="https://2942044318-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDzTfUwOrTmhLAFmV5Ijz%2Fuploads%2FhQOs9cHf0x1c4GUBP6pR%2Fimage.png?alt=media&amp;token=af6fe84a-f118-46d4-af87-6cd20f9bc69e" alt="" width="413"><figcaption></figcaption></figure>

{% endtab %}

{% tab title="Claude Code" %}
터미널에서 한 줄:

```bash
claude mcp add --transport http salesmap https://mcp.ai.salesmap.kr/mcp \
  --header "Authorization: Bearer <API_토큰>"
```

{% endtab %}

{% tab title="Codex" %}
터미널에서 두 줄:

```bash
# ~/.zshrc 또는 ~/.bashrc 에 추가 후 터미널 재시작 (토큰을 파일에 남기지 않는 방식)
export SALESMAP_API_TOKEN="<API_토큰>"
```

{% code overflow="wrap" %}

```bash
codex mcp add salesmap --url https://mcp.ai.salesmap.kr/mcp --bearer-token-env-var SALESMAP_API_TOKEN
```

{% endcode %}
{% endtab %}

{% tab title="Antigravity" %}
Antigravity 설정 → **Customizations 탭 → Open MCP Config** 클릭\
(파일 위치: `~/.gemini/config/mcp_config.json`)

```json
{
  "mcpServers": {
    "salesmap": {
      "serverUrl": "https://mcp.ai.salesmap.kr/mcp",
      "headers": {
        "Authorization": "Bearer <API_토큰>"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

***

### 3단계: 연결 확인

연결 후 AI에게 이렇게 요청해 보세요:

```
세일즈맵에서 내 정보 조회해줘
```

사용자 정보가 나오면 연결 성공입니다.

***

### 문제 해결

| 증상                 | 해결                                                  |
| ------------------ | --------------------------------------------------- |
| "토큰이 유효하지 않습니다"    | 세일즈맵에서 토큰 다시 복사해 넣습니다. 토큰 앞뒤 공백을 제거 후 재시도합니다.       |
| ”npx를 찾을 수 없습니다”   | Node.js 설치를 확인합니다. (20버전 이상 필요)                     |
| "허용되지 않은 IP"       | 워크스페이스에 IP 접근 제한이 있는 경우로, 관리자에게 IP 허용 목록 확인을 요청합니다. |
| AI가 세일즈맵 도구를 찾지 못함 | AI 클라이언트를 재시작합니다. 설정 파일 문법에 문제 없는지 확인합니다.           |
| 도구 호출 시 타임아웃       | 네트워크 연결 상태를 확인합니다.                                  |

***

문의: 세일즈맵 [채널톡](https://salesmap.channel.io/home)으로 연락해주세요.