# MCP 서버

Pocket Alert는 [Model Context Protocol](https://modelcontextprotocol.io)을 지원하므로, AI 에이전트가 일반적인 도구 호출만으로 푸시 알림을 보내고, 메시지 기록을 읽고, 발송 통계를 확인할 수 있습니다.

실제로는 이런 식으로 쓰입니다. 에이전트가 오래 걸리는 작업을 시작하고, 언제 끝날지 모르는 시점에 완료되면 터미널을 확인하길 기다리는 대신 휴대폰으로 알려 줍니다.

```
https://mcp.pocketalert.app/mcp
```

## 연결하기

인증은 베어러 토큰 방식입니다. [API 키](https://pocketalert.app/account/apikeys) 페이지에서 발급받은 API 키를 `Authorization: Bearer <token>` 헤더로 보내면 됩니다.

**Claude Desktop / Claude Code**

```json
{
  "mcpServers": {
    "pocketalert": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.pocketalert.app/mcp",
        "--header",
        "Authorization: Bearer ${POCKETALERT_API_TOKEN}"
      ],
      "env": {
        "POCKETALERT_API_TOKEN": "your-api-key"
      }
    }
  }
}
```

**Native HTTP transport**

```json
{
  "mcpServers": {
    "pocketalert": {
      "type": "http",
      "url": "https://mcp.pocketalert.app/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}
```

설정 후 클라이언트를 재시작하고 도구 목록을 요청해 보세요. `pocketalert`가 보이면 연결된 것입니다.

## 사용 가능한 도구

| 도구 | 기능 |
|------|------|
| `list_applications` | 애플리케이션 목록 조회 |
| `get_application` | TID로 애플리케이션 하나 조회 |
| `list_devices` | 등록된 기기 목록 조회 |
| `get_device` | TID로 기기 하나 조회 |
| `list_messages` | 메시지 기록 조회 |
| `get_message` | TID로 메시지 하나 조회 |
| `create_message` | 푸시 알림 발송 |
| `create_message_with_attachment` | 이미지를 첨부해 푸시 알림 발송 |
| `delete_message` | 메시지 삭제 |
| `get_message_stats` | 발송 통계 조회 |

`create_message`는 REST API와 같은 `level` 및 `actions` 매개변수를 받으므로, 에이전트가 발송하는 알림을 [중요 알림](https://info.pocketalert.app/features/priority-levels.md)으로 설정하거나 [승인 버튼](https://info.pocketalert.app/features/action-buttons.md)을 붙일 수 있습니다.

## 이렇게 활용해 보세요

**장시간 작업.** 마이그레이션, 학습 실행, 일괄 가져오기 같은 작업이 끝나면 에이전트가 알려 줍니다. 터미널을 계속 확인할 필요가 없습니다.

**사람이 개입하는 승인.** 에이전트에 `create_message`를 허용하고, 되돌릴 수 없는 작업을 하기 전에 `http` 액션 버튼 두 개를 포함한 알림을 보내도록 설정하세요. 잠금 화면에서 승인하면 에이전트가 다음 단계를 진행합니다.

**자기 기록 읽기.** `list_messages`를 호출할 수 있는 에이전트는 별도로 전달받지 않아도 "밤사이 무엇이 잘못됐나요?" 같은 질문에 답할 수 있습니다.

> **Warning: API 키 분리하기**
>
> MCP 서버는 모델에게 맡기는 권한입니다. 운영 스크립트가 쓰는 API 키를 그대로 재사용하지 말고, 에이전트 전용 API 키를 따로 발급하세요. 그래야 에이전트의 접근 권한을 취소해도 다른 작업에는 영향이 없습니다.

## 관련 문서

- [우선순위 수준](https://info.pocketalert.app/features/priority-levels.md) — `level` 값이 전달되는 알림에 어떤 영향을 주는지
- [액션 버튼](https://info.pocketalert.app/features/action-buttons.md) — 알림에서 승인 워크플로 처리하기
- [메시지 생성](https://info.pocketalert.app/api/messages/create.md) — `create_message`에 해당하는 REST API
