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

# OneSignal MCP 서버

> 호스팅된 MCP 서버 URL로 원격 MCP 서버를 지원하는 모든 AI 도구나 에이전트를 OneSignal에 연결하세요. Claude Code, Codex CLI, Cursor, VS Code, 사용자 지정 커넥터 설정과 Journey 도구를 포함해 서버가 지원하는 모든 도구를 다룹니다.

OneSignal MCP 서버 URL을 추가하여 원격 Model Context Protocol(MCP) 서버를 지원하는 모든 AI 도구나 에이전트에 OneSignal을 연결하세요. 이 페이지에서 Cursor, Claude Code, Codex CLI, VS Code 또는 자체 에이전트를 연결하거나 전체 도구 목록을 확인할 수 있습니다. Claude 또는 ChatGPT 디렉터리에서 OneSignal을 설치하려면 [Claude와 ChatGPT에서 OneSignal 사용하기](https://documentation.onesignal.com/docs/en/onesignal-in-claude-chatgpt.md)를 참조하세요.

[MCP](https://modelcontextprotocol.io/docs/getting-started/intro)는 AI 앱을 외부 시스템에 연결하기 위한 개방형 표준입니다. OneSignal MCP 서버는 사용자 조회나 메시지 전송과 같은 OneSignal 작업을 AI 도구가 호출할 수 있는 도구로 제공합니다.

## 사전 요구 사항 \\

* 관리하려는 OneSignal 앱에 액세스할 수 있는 OneSignal 계정.
* OneSignal이 사용하는 브라우저 기반 로그인인 OAuth를 통해 OneSignal 액세스를 승인할 수 있는 권한.
* OAuth를 사용하는 HTTP 기반 원격 MCP 서버를 지원하는 AI 도구.

## 연결 세부 정보 \\

모든 AI 도구는 동일한 호스팅 엔드포인트에 연결합니다:

```text theme={null}
https://api.onesignal.com/mcp/oauth
```

브라우저에서 OneSignal에 로그인하고 액세스를 승인하여 인증합니다. 구성할 REST API 키는 없습니다. OAuth 클라이언트 ID와 클라이언트 시크릿 필드는 비워 두세요. OneSignal이 AI 도구를 자동으로 등록하며, 값을 입력하면 연결이 실패합니다.

## AI 도구 설정하기 \\

### Cursor \\

Cursor Marketplace에서 OneSignal을 설치합니다.

**1. OneSignal 플러그인 열기**

[Cursor Marketplace의 OneSignal](https://cursor.com/marketplace/onesignal)로 이동하거나 Cursor의 마켓플레이스에서 **OneSignal**을 검색합니다.

**2. 플러그인 설치**

**Add to Cursor**를 클릭합니다. Cursor가 MCP 서버를 포함한 OneSignal 플러그인을 설치합니다.

**3. OneSignal에 로그인**

**Settings > MCP & Integrations**를 열고 OneSignal 옆의 **Authenticate**를 클릭합니다. 브라우저에서 로그인하고 **Agree & Allow Access**를 클릭합니다.

**4. Agent 채팅에서 OneSignal 사용**

새 Agent 채팅을 시작하고 OneSignal 앱 목록 조회와 같은 읽기 전용 확인을 실행하도록 요청합니다.

Cursor를 직접 구성하려면 `mcp.json`에 OneSignal을 추가합니다:

```json theme={null}
{
  "mcpServers": {
    "onesignal": {
      "url": "https://api.onesignal.com/mcp/oauth"
    }
  }
}
```

### Claude Code \\

**1. OneSignal MCP 서버 추가**

터미널에서 다음 명령을 실행합니다:

```bash theme={null}
claude mcp add --transport http onesignal https://api.onesignal.com/mcp/oauth
```

**2. Claude Code 내에서 인증**

`claude`를 시작한 다음 `/mcp`를 입력하여 MCP 패널을 엽니다. **onesignal**을 선택한 다음 **Authenticate**를 선택하여 브라우저에서 OneSignal 로그인 페이지를 엽니다.

**3. 액세스 승인**

로그인하고 **Agree & Allow Access**를 클릭합니다. Claude Code로 돌아갑니다. 서버 상태가 **connected**로 바뀝니다.

도구 수를 확인하려면 `claude mcp list`를 실행하거나 Claude Code 내에서 `/mcp`를 실행하세요.

### Claude 사용자 지정 커넥터 \\

[Claude 디렉터리](https://claude.ai/directory/connectors/onesignal)에서 OneSignal을 설치할 수 없는 경우에만 사용자 지정 커넥터를 사용하세요. 원격 MCP 서버는 로컬 `stdio` 서버 전용인 `claude_desktop_config.json`을 통해 추가할 수 없습니다.

**1. 사용자 지정 커넥터 추가**

**Customize > Connectors**로 이동하여 **Add custom connector**를 클릭합니다.

**2. 서버 세부 정보 입력**

**Name**을 `OneSignal`로, **Remote MCP server URL**을 `https://api.onesignal.com/mcp/oauth`로 설정합니다. **Advanced settings** 아래의 **OAuth Client ID**와 **OAuth Client Secret**은 비워 둡니다.

**3. OneSignal에 로그인**

**Add**를 클릭한 다음 브라우저에서 OneSignal 로그인을 완료하고 **Agree & Allow Access**를 클릭합니다.

### Codex CLI \\

**1. 플러그인 브라우저 열기**

`codex`를 실행한 다음 `/plugins`를 입력합니다.

**2. OneSignal 설치**

**OneSignal**을 찾아 열고 설치합니다.

**3. 새 세션 시작 및 로그인**

새 세션을 시작합니다. Codex가 인증을 요청하면 브라우저에서 OneSignal에 로그인하고 **Agree & Allow Access**를 클릭합니다.

Codex IDE 확장 프로그램은 플러그인을 지원하지 않습니다. Codex에서 OneSignal을 사용하려면 Codex CLI 또는 ChatGPT 데스크톱 앱의 **Plugins** 탭에서 설치하세요.

### VS Code의 GitHub Copilot \\

팀과 공유하려면 워크스페이스의 `.vscode/mcp.json`에 OneSignal을 추가하고, 사용자 프로필에 설치하려면 명령 팔레트에서 **MCP: Open User Configuration**을 실행하세요:

```json theme={null}
{
  "servers": {
    "onesignal": {
      "type": "http",
      "url": "https://api.onesignal.com/mcp/oauth"
    }
  }
}
```

Copilot이 처음으로 OneSignal 도구를 필요로 할 때 VS Code가 인증을 요청하고 OneSignal 로그인 페이지를 엽니다.

### 기타 AI 도구 및 에이전트 \\

AI 도구의 원격 MCP 서버 설정에 `https://api.onesignal.com/mcp/oauth`를 추가합니다. AI 도구가 처음으로 OneSignal 도구를 호출하면 브라우저에서 OneSignal 로그인 페이지가 열립니다. 로그인하고 **Agree & Allow Access**를 클릭합니다. 연결에 성공하면 AI 도구에 OneSignal 도구가 표시됩니다.

## 연결 확인하기 \\

새 채팅이나 세션을 시작하고 다음을 보냅니다:

```text theme={null}
Use the list_apps tool to list the OneSignal apps I can access.
```

응답에 OneSignal 앱이 나열되면 연결이 정상적으로 작동하는 것입니다. "tool access is not enabled for this application"이 반환되면 [문제 해결](#troubleshooting)을 참조하세요.

AI 도구가 서버에 연결되는지만 확인하려면 `onesignal_health`를 호출하세요. 이 도구는 AI 도구 액세스가 활성화되기 전에도 응답하므로, 정상 결과가 다른 도구의 작동을 보장하지는 않습니다.

## 문제 해결 \\

* **다시 인증하세요.** AI 도구의 MCP 또는 커넥터 설정에서 OneSignal을 다시 연결한 다음 새 세션을 시작합니다.

* **서버 URL을 확인하세요.** URL은 정확히 `https://api.onesignal.com/mcp/oauth`여야 하며 추가 경로나 후행 문자가 없어야 합니다.

* **OAuth 클라이언트 필드를 비우세요.** AI 도구에 OAuth 클라이언트 ID 또는 시크릿 필드가 있으면 비워 두세요.

* **AI 도구 액세스를 확인하세요.** 도구가 "tool access is not enabled for this application"을 반환하는 경우:

  OneSignal이 아직 귀하의 OneSignal 로그인에 대해 AI 도구 액세스를 활성화하지 않았습니다. OneSignal 지원팀에 문의하세요.

* **AI 도구를 다시 시작**하고 새 세션을 시작하세요. 이렇게 하면 대부분의 일시적인 연결 문제가 해결됩니다.

## 도구 \\

아래 도구를 살펴보세요. 도구 검색은 OneSignal 앱 또는 계정의 MCP 활성화 여부에 따라 달라집니다. 각 작업은 OneSignal 앱 권한도 확인합니다.

### 앱 (도구 2개) \\

| 작업 | 도구 |
| - | - |
| 인증된 사용자가 액세스할 수 있는 앱 나열 | `list_apps` |
| 앱에서 활성화된 메시징 채널 확인 | `get_app_channel_availability` |

### Journeys (도구 9개) \\

| 작업 | 도구 |
| - | - |
| 앱의 Journeys 나열 | `list_journeys` |
| Journey의 구조와 현재 동시성 키 보기 | `get_journey` |
| Journey, 단계, 분기, 메시지 통계 보기 | `get_journey_stats` |
| Journey 또는 단계를 생성, 복제, 업데이트하기 위한 JSON Schema 가져오기 | `get_journey_schema` |
| Journey를 초안으로 생성 | `create_journey_draft` |
| Journey를 새 초안으로 복제 | `duplicate_journey` |
| Journey 필드 업데이트 또는 상태 변경 | `update_journey` |
| 개별 Journey 단계 업데이트 | `update_journey_node` |
| Journey 영구 삭제 | `delete_journey` |

> [card] [MCP로 Journeys 관리하기](https://documentation.onesignal.com/docs/en/mcp-journeys.md)
>
> 도구 요청을 구성하고, 스키마를 가져오고, Journey 변경 사항을 안전하게 적용하세요.

### 메시징 (도구 3개) \\

| 작업 | 도구 |
| - | - |
| 푸시 알림, 이메일 또는 SMS 전송 | `send_message` |
| 최근 알림 나열 | `list_messages` |
| 알림 세부 정보 및 전송 통계 보기 | `view_message` |

Live Activity를 시작하거나 업데이트하려면 아래의 [Live Activities](#live-activities-2-tools)를 참조하세요.

### 사용자 및 구독 (도구 12개) \\

| 작업 | 도구 |
| - | - |
| 별칭으로 사용자 조회 | `view_user` |
| 사용자의 ID 별칭 가져오기 | `get_user_identity` |
| 구독 ID로 ID 가져오기 | `get_user_identity_by_subscription` |
| 속성이 포함된 새 사용자 생성 | `create_user` |
| 사용자 속성(태그, 언어 등) 업데이트 | `update_user` |
| ID 별칭 추가 또는 업데이트 | `create_or_update_alias` |
| 구독 ID로 별칭 추가 | `create_alias_by_subscription` |
| 푸시, 이메일 또는 SMS 구독 추가 | `create_subscription` |
| 기존 구독 업데이트 | `update_subscription` |
| 토큰으로 구독 업데이트 | `update_subscription_by_token` |
| 이메일 주소 구독 취소 | `unsubscribe_email` |
| 구독을 다른 사용자에게 이전 | `transfer_subscription` |

### 템플릿 (도구 4개) \\

| 작업 | 도구 |
| - | - |
| 템플릿 나열 | `list_templates` |
| 템플릿 보기 | `get_template` |
| 템플릿 생성 | `create_template` |
| 템플릿 업데이트 | `update_template` |

### 세그먼트 (도구 4개) \\

| 작업 | 도구 |
| - | - |
| 세그먼트 나열 | `list_segments` |
| 세그먼트 및 필터 보기 | `get_segment` |
| 세그먼트 생성 | `create_segment` |
| 세그먼트 업데이트 | `update_segment` |

### Live Activities (도구 2개) \\

| 작업 | 도구 |
| - | - |
| iOS Live Activity 시작 | `start_live_activity` |
| Live Activity 업데이트 또는 종료 | `update_live_activity` |

### 내보내기 (도구 2개) \\

| 작업 | 도구 |
| - | - |
| 구독을 CSV로 내보내기 | `export_subscriptions_csv` |
| 알림 대상 활동을 CSV로 내보내기 | `export_audience_activity_csv` |

### 사용자 지정 이벤트 (도구 2개) \\

| 작업 | 도구 |
| - | - |
| 사용자에 대한 사용자 지정 이벤트 생성 | `create_custom_events` |
| 인덱싱된 사용자 지정 이벤트 정의 나열 | `get_custom_events` |

### 이메일 전달성 (도구 4개) \\

| 작업 | 도구 |
| - | - |
| 이메일 도메인 DNS 인증 상태(SPF, DKIM, DMARC) 확인 | `get_email_domains` |
| 앱 전체의 반송률 및 스팸 신고율 보기 | `get_email_reputation` |
| 도메인의 수신함 제공업체별 전달성 지표 가져오기 | `get_provider_metrics` |
| 제공업체 전달성 지표의 시계열 가져오기 | `get_provider_metrics_timeseries` |

### 이메일 워밍업 (도구 5개) \\

| 작업 | 도구 |
| - | - |
| 전송에 IP 또는 도메인 워밍업이 필요한지 확인 | `check_send_volume` |
| 세그먼트 및 필터로 수신자 수 추정 | `estimate_recipient_count` |
| 권장 단계별 워밍업 일정 가져오기 | `recommended_warm_up_schedule` |
| 초안 캠페인에 워밍업 일정 적용 | `apply_warm_up_schedule` |
| 현재 진행 중인 워밍업 일정 나열 | `get_active_warm_up_schedules` |

### 분석 및 유틸리티 (도구 4개) \\

| 작업 | 도구 |
| - | - |
| 성과 분석 보기 | `view_outcomes` |
| 서버 상태 확인 | `onesignal_health` |
| 서버 구성 보기 | `onesignal_config` |
| 모든 도구의 참조 개요 보기 | `onesignal_reference_overview` |

## 안전 및 보호 장치 \\

* OneSignal은 `send_message`를 영향도가 높은 도구로 표시하므로, 도구 주석을 따르는 AI 도구는 실행 전에 확인을 요청할 수 있습니다.
* `send_message`는 전송 전에 타겟팅을 검증합니다. 요청당 하나의 타겟팅 방법만 사용할 수 있으며 필터 수에는 상한이 있습니다.
* OneSignal은 식별자, 이메일 주소, 전화번호를 포함한 입력을 실행 전에 검증합니다.
* Journey 동시성 요구 사항, 수명 주기 제어, 불확실한 쓰기 이후의 복구에 대해서는 [Journey 요청 가이드](https://documentation.onesignal.com/docs/en/mcp-journeys.md)를 참조하세요.
* OneSignal은 각 OneSignal 로그인별로 AI 도구 액세스를 켜거나 끕니다.
* MCP 서버는 고객 데이터(구독자, 메시지, 내보내기)를 저장하지 않습니다.

## 제한 및 사용량 \\

OneSignal 연결은 무료입니다. 각 작업은 일반 OneSignal API 사용 한도에 포함됩니다. AI 제공업체의 요금제에는 별도의 비용이 발생할 수 있습니다.

* 도구 호출에는 도구가 통제 불능 루프에 빠지는 것을 방지하기 위한 속도 제한이 있습니다.
* 연결은 로그인한 사용자의 권한을 따르며 해당 사용자가 관리할 수 있는 모든 OneSignal 앱에 액세스할 수 있습니다.
* 유틸리티 도구 이외의 도구가 작동하려면 OneSignal이 귀하의 로그인에 대해 AI 도구 액세스를 활성화해야 할 수 있습니다.

## FAQ \\

### REST API 키가 필요한가요? \\

아니요. 모든 연결은 OneSignal OAuth를 사용합니다. 브라우저에서 로그인하고 액세스를 승인하므로 복사, 저장, 교체할 API 키가 없습니다.

### 여러 OneSignal 앱으로 작업하려면 어떻게 하나요? \\

하나의 연결로 OneSignal 계정이 관리할 수 있는 모든 앱을 사용할 수 있습니다. `list_apps`를 호출하여 앱 ID를 찾으세요. 앱별로 별도의 구성이 필요하지 않습니다.

### 로컬 stdio 서버만 지원하는 AI 도구를 연결할 수 있나요? \\

아니요. OneSignal MCP 서버는 HTTP 기반의 원격 서버입니다. AI 도구가 OAuth를 사용하는 원격 MCP 서버를 지원해야 합니다.

### AI 도구의 액세스를 해지하려면 어떻게 하나요? \\

OneSignal에서 \*\*[Settings > Account settings > Connected apps](https://dashboard.onesignal.com/settings/connected-apps)\*\*로 이동하여 연결을 해지하세요. 연결을 해지해도 팀원의 연결에는 영향을 주지 않습니다.

## 관련 페이지 \\

> [card] [Claude와 ChatGPT에서 OneSignal 사용하기](https://documentation.onesignal.com/docs/en/onesignal-in-claude-chatgpt.md)
>
> Claude 또는 ChatGPT 디렉터리에서 OneSignal을 설치합니다.

> [card] [MCP로 Journeys 관리하기](https://documentation.onesignal.com/docs/en/mcp-journeys.md)
>
> MCP 클라이언트에서 초안을 생성하고, Journey 단계를 업데이트하고, Journey 상태를 관리합니다.

> [card] [REST API 개요](https://documentation.onesignal.com/reference/rest-api-overview.md)
>
> OneSignal MCP 서버가 호출하는 엔드포인트에 대한 참조입니다.

> [card] [메시지 생성 API](https://documentation.onesignal.com/reference/create-message.md)
>
> `send_message`의 기반이 되는 엔드포인트 참조입니다.

> [card] [AI 데이터 관행](https://documentation.onesignal.com/docs/en/ai-data-practices.md)
>
> OneSignal이 AI 기능과 연결된 AI 도구의 데이터를 처리하는 방법입니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.