# MCP 연결하기

팝빌의 MCP(Model Context Protocol) 서버를 활용하는 방법에 대해 소개합니다.

## 팝빌 MCP

MCP는 AI를 외부 서비스와 표준화된 방식으로 연결해 필요한 정보를 직접 조회할 수 있도록 하는 개방형 프로토콜입니다. MCP 서버를 AI 도구에 한 번만 연결해두면, AI가 최신 문서와 API 스펙을 실시간으로 참고해 더 정확하고 신뢰할 수 있는 코드를 작성합니다.

![팝빌 MCP](https://developers.popbill.com/images/guide/mcp/popbill-mcp-light.webp)

### 활용 예시

- 코드 생성 - 팝빌의 API 상품 연동에 필요한 예제 코드 작성\
  예) “착오에 의한 이중발급 수정세금계산서를 발행하는 Java 코드를 작성해 줘.”

- 오류 해결 - 일반적인 오류에 대한 빠른 해결책\
  예) “전자세금계산서 작성일자를 과거 2개월 전 날짜로 발행하면 -11002014 에러가 나와. 원인이랑 해결법을 알려줘.”

- 정보 제공 - 팝빌 API 서비스에 대한 정보 제공\
  예) “전자세금계산서 즉시발행 시 여러 담당자에게 메일을 보내려면 어떻게 해야하는지 방법을 알려줘.”

> **팝빌이 처음이라면 연동신청을 완료해 주세요.**\
> 연동을 신청하면 API Key를 발급받고 빠르게 개발을 시작할 수 있습니다.\
> 쉽고 빠른 연동이 가능한 팝빌에서 지금 바로 시작하세요. [\[연동신청\]](https://developers.popbill.com/customer-center/partner-request)

## 팝빌 MCP 연결하기

팝빌은 원격 MCP 서버를 지원하며 서버 정보는 다음과 같습니다.

| 항목     | 설명                             |
| ------ | ------------------------------ |
| 서버 URL | https\://mcp.popbill.com/mcp   |
| 전송 방식  | Streamable HTTP (JSON-RPC 2.0) |

사용 중인 AI 도구에 팝빌 MCP를 빠르게 연결할 수 있도록 다양한 연결 방식을 제공하고 있습니다.\
팝빌이 제공하는 MCP 연결 방식은 다음과 같습니다.

### 원클릭 연결

| AI 도구   | 원클릭 설치                                                                                                                                                                          | 공식 가이드                                                                       |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Cursor  | [원클릭 설치](https://cursor.com/en/install-mcp?name=popbill\&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3BiaWxsLmNvbS9tY3AifQ%3D%3D)                                                       | [공식 가이드](https://cursor.com/docs/mcp)                                        |
| VS Code | [원클릭 설치](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22popbill%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.popbill.com%2Fmcp%22%7D) | [공식 가이드](https://code.visualstudio.com/docs/agent-customization/mcp-servers) |

### 터미널에서 연결

터미널에서 다음 명령어를 실행합니다.

**Claude Code**

```bash
claude mcp add --transport http popbill https://mcp.popbill.com/mcp
```

**Codex CLI**

```bash
codex mcp add popbill --url https://mcp.popbill.com/mcp
```

**VS Code**

```bash
code --add-mcp '{\"name\":\"popbill\",\"type\":\"http\",\"url\":\"https://mcp.popbill.com/mcp\"}'
```

### 설정파일로 연결

대부분의 도구가 아래 형식을 사용합니다. 사용하는 도구의 `mcp.json` 에 다음 내용을 추가합니다.

**mcp.json**

```json
{
    "mcpServers": {
        "popbill": {
            "type": "http",
            "url": "https://mcp.popbill.com/mcp"
        }
    }
}
```

VS Code는 `mcpServers` 대신 `servers` 키를 사용합니다. 프로젝트 루트의 `.vscode/mcp.json` 에 다음 내용을 추가합니다.

**.vscode/mcp.json**

```json
{
    "servers": {
        "popbill": {
            "type": "http",
            "url": "https://mcp.popbill.com/mcp"
        }
    }
}
```

Codex는 JSON이 아닌 TOML 형식을 사용합니다. `~/.codex/config.toml` 에 다음 내용을 추가합니다.

**\~/.codex/config.toml**

```toml
[mcp_servers.popbill]
url = "https://mcp.popbill.com/mcp"
```

### 데스크톱 앱에서 연결

사용중인 데스크톱 앱에서 하단 안내된 메뉴 경로로 이동하여 팝빌 MCP 연결을 완료합니다.

| AI 도구          | 메뉴 경로                                 | 공식 가이드                                                                                   |
| -------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
| Claude Desktop | 설정 > 커넥터 > 추가 > 커스텀 커넥터 추가            | [공식 가이드](https://modelcontextprotocol.io/docs/2026-07-28/develop/connect-remote-servers) |
| Codex Desktop  | Codex 모드 > 설정 > 플러그인 > 추가 > MCP 서버 추가 | [공식 가이드](https://learn.chatgpt.com/docs/extend/mcp?surface=app)                          |

### 연결이 잘 되지 않을 경우

- MCP 서버 URL이 정확한지 확인합니다.
- 회사 네트워크, VPN, 프록시, 방화벽이 외부 MCP 접속을 막고 있지 않은지 확인합니다.
- AI 도구를 완전히 종료한 뒤 다시 실행합니다.
- MCP 로그 또는 Output 패널에서 오류 메시지를 확인합니다.

### AI가 MCP를 사용하지 않을 경우

- AI 도구의 MCP 설정에 팝빌 MCP가 연결되어 있고 활성 상태인지 확인합니다.
- 연결이 되었음에도 AI가 MCP를 참조하지 않는 것 같다면, AI에게 “반드시 팝빌 MCP를 호출해서 답변해줘” 처럼 명시적으로 요청할 수 있습니다.

## MCP 서버가 제공하는 도구

| 도구                    | 설명                                    |
| --------------------- | ------------------------------------- |
| `search_popbill_docs` | 사용자가 입력한 프롬프트를 키워드 단위로 분석해 문서를 조회합니다. |

> **MCP 연결 문제가 해결되지 않는다면 문의해 주세요.**\
> 사용하는 AI 도구의 자세한 상황을 함께 알려주시면 더욱 정확한 기술 지원이 가능합니다. [\[기술문의\]](https://developers.popbill.com/customer-center/techinquiry)