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

# Flespi

> GPS 디바이스 관리, 차량 텔레메트리, IoT 데이터 분석을 위해 Flespi IoT 텔레매틱스를 CloudThinker에 연결하세요

Flespi 계정을 연결하여 CloudThinker 에이전트가 Flespi MCP 서버를 통해 GPS 디바이스를 관리하고, 텔레메트리를 모니터링하며, 채널과 스트림을 검사하고, 차량 인프라를 운영할 수 있도록 합니다.

Flespi는 Flespi 패널에서 생성된 **API 토큰**(Standard 또는 ACL 유형)으로 인증합니다.

***

## 지원 플랫폼

| 플랫폼                   | 지원                        |
| --------------------- | ------------------------- |
| **Flespi Free**       | 월 1,000 AI 크레딧            |
| **Flespi Commercial** | 월 1,000 AI 크레딧 + 유료 초과 사용 |

***

## 사전 요구 사항

* [flespi.io](https://flespi.io/#/)의 **Flespi 계정**.
* API 토큰을 생성하고 관리하기 위한 Flespi 패널 접근 권한.
* 프로덕션 워크로드의 경우, CloudThinker가 필요한 모듈로 권한이 범위 지정된 ACL 토큰.

***

## 설정

CloudThinker는 Flespi API 토큰을 사용하여 공식 MCP 서버를 통해 Flespi에 연결합니다.

<Steps>
  <Step title="Flespi 계정 생성">
    계정이 없는 경우 [flespi.io](https://flespi.io/#/)에서 가입합니다.
  </Step>

  <Step title="API 토큰 생성">
    Flespi 패널의 왼쪽 메뉴에서 **Tokens**로 이동하여 **"+"** 버튼을 클릭합니다:

    * **Name**: `CloudThinker Agent`
    * **Type**: Standard (개발) 또는 ACL (프로덕션)
    * **TTL**: 만료 설정 — 예: `7776000` (90일). Flespi는 모든 토큰에 TTL 또는 만료 날짜를 요구합니다.

    64바이트 토큰을 즉시 복사합니다.
  </Step>

  <Step title="CloudThinker에 연결 추가">
    **Connections → Flespi**로 이동하여 방금 생성한 토큰을 입력합니다.
  </Step>

  <Step title="연결 테스트">
    **Connect**를 클릭합니다. CloudThinker가 토큰을 확인하고 **Connected** 상태를 표시합니다.
  </Step>
</Steps>

<Warning>
  Flespi는 `Bearer` 대신 `FlespiToken`을 인증 접두사로 사용합니다. CloudThinker가 이를 자동으로 처리하지만, API 호출을 수동으로 디버깅할 때 참고하세요.
</Warning>

***

## 연결 세부 정보

| 필드               | 설명                    | 예시            |
| ---------------- | --------------------- | ------------- |
| **Flespi Token** | Flespi API 토큰 (64바이트) | `7Bf3...xK9z` |

***

## 필요 권한

### 토큰 유형

| 유형           | 접근 수준                                                     | 사용 시기                 |
| ------------ | --------------------------------------------------------- | --------------------- |
| **Standard** | 모든 텔레매틱스 엔터티(디바이스, 채널, 스트림, 플러그인, 지오펜스, 계산기)에 대한 완전한 CRUD | 개발 및 테스트              |
| **ACL**      | 세분화 — 기본적으로 모두 거부, 모듈/메서드/항목별 권한 부여                       | **프로덕션 권장**           |
| **Master**   | 플랫폼 API를 포함한 완전한 관리 권한                                    | **AI 에이전트에 절대 사용 금지** |

### 토큰 만료

Flespi는 모든 토큰이 만료되도록 **요구**합니다. 다음 중 하나 이상을 설정하세요:

* **`ttl`** — 비활성 상태 후 만료까지의 초 (API 호출 시마다 재설정)
* **`expire`** — 하드 만료의 Unix 타임스탬프

<Tip>
  장기 실행 통합의 경우 `ttl`을 사용하세요 (예: 7776000 = 90일). 타이머는 모든 API 호출 시 재설정되므로 활성 토큰이 예기치 않게 만료되지 않습니다.
</Tip>

### 권장 ACL 권한 (프로덕션)

**읽기 전용 (최소):**

| 모듈               | 메서드  | 목적                      |
| ---------------- | ---- | ----------------------- |
| `gw/devices`     | GET  | 디바이스 목록, 상태, 텔레메트리, 메시지 |
| `gw/channels`    | GET  | 채널 목록, 구성, 상태           |
| `gw/streams`     | GET  | 스트림 목록, 상태, 전달 통계       |
| `gw/calculators` | GET  | 계산기 구성                  |
| `ai`             | POST | MCP 도구 호출에 필요           |

**읽기-쓰기 (쓰기 작업이 필요한 경우):**

| 모듈            | 메서드                    | 목적           |
| ------------- | ---------------------- | ------------ |
| `gw/devices`  | GET, POST, PUT         | 디바이스 생성/업데이트 |
| `gw/channels` | GET, POST, PUT         | 채널 생성/업데이트   |
| `gw/streams`  | GET, POST, PUT, DELETE | 스트림 전체 관리    |

<Info>
  ACL 토큰은 기본적으로 모든 것을 거부합니다. 명시적으로 부여된 권한만 허용됩니다. `gw/devices`에 POST 권한이 있는 토큰은 GET 권한도 명시적으로 부여하지 않으면 GET이 불가합니다.
</Info>

***

## 에이전트 기능

연결 후 에이전트는 다음을 수행할 수 있습니다:

| 기능           | 설명                                   |
| ------------ | ------------------------------------ |
| **디바이스 관리**  | 디바이스 목록 조회, 상태 확인, 텔레메트리 및 메시지 이력 읽기 |
| **채널 모니터링**  | 채널 구성, 상태, 연결된 프로토콜 검사               |
| **스트림 상태**   | 스트림 전달 통계 및 상태 모니터링                  |
| **차량 텔레메트리** | 디바이스 전체의 GPS 위치, 속도, 연료, 센서 데이터 쿼리   |
| **지오펜스**     | 지오펜스 구역 및 트리거 조회 및 관리                |
| **계산기**      | 트립 감지, 연료 소비 등에 대한 계산기 구성 검사         |

### 사용 가능한 MCP 도구

**무료 도구 (0 크레딧):**

| 도구                   | 설명                               |
| -------------------- | -------------------------------- |
| `search-api-methods` | 자연어 쿼리로 flespi REST API 메서드 검색   |
| `get-api-schema`     | 특정 API 메서드의 전체 Swagger 스키마 조회    |
| `flespi-api-read`    | flespi REST API에 읽기 전용 GET 요청 실행 |
| `flespi-api-write`   | 쓰기 작업(POST/PUT/PATCH/DELETE) 실행  |

**유료 도구:**

| 도구                            | 크레딧 | 설명                                      |
| ----------------------------- | --- | --------------------------------------- |
| `search-flespi-documentation` | 5   | flespi 플랫폼 문서 검색                        |
| `search-device-documentation` | 10  | 디바이스/프로토콜 제조사 문서 검색                     |
| `generate-flespi-expression`  | 2   | 셀렉터, 계산기용 flespi 표현식 생성                 |
| `generate-pvm-code`           | 10  | PVM(Protocol Virtual Machine) 코드 생성     |
| `consult-flespi-account`      | 30  | 계정 읽기 접근 권한으로 flespi AI 전문가에게 복잡한 분석 위임 |

### AI 크레딧

| 플랜         | 월 무료 크레딧 | 초과 사용          |
| ---------- | -------- | -------------- |
| Free       | 1,000    | 다음 달까지 차단      |
| Commercial | 1,000    | 100 추가 크레딧당 €1 |

flespi 패널의 **AI 타일**, `GET /ai/logs` API, 또는 MQTT 토픽 `flespi/log/ai/#`을 통해 사용량을 모니터링하세요.

### 연결 확인

```text theme={null}
@alex list all Flespi devices and report their last known positions
```

### 예시 프롬프트

```text theme={null}
@alex check stream health and identify any delivery failures
@alex query telemetry for device 12345 over the last 24 hours
@alex list geofences and check which devices are inside zone "warehouse-01"
```

***

## 문제 해결

<Accordion title="유효하지 않거나 만료된 액세스 토큰">
  * 토큰이 만료되었을 수 있습니다 — flespi 패널에서 TTL 및 만료 설정을 확인하세요.
  * 새 토큰을 생성하고 CloudThinker에서 연결을 업데이트합니다.
  * 만료된 토큰은 flespi에 의해 **자동으로 삭제**됩니다.
</Accordion>

<Accordion title="ACL에 의해 작업이 허용되지 않음">
  * ACL 토큰에 필요한 모듈 + HTTP 메서드 조합이 없습니다.
  * 필요한 권한을 부여하도록 토큰 ACL을 업데이트합니다.
  * 기억하세요: ACL은 기본적으로 모두 거부 — 각 권한은 명시적으로 부여해야 합니다.
</Accordion>

<Accordion title="AI 도구에서 HTTP 403">
  * 월간 AI 크레딧이 소진되었습니다.
  * Free 플랜: 다음 달까지 기다립니다. Commercial 플랜: 초과 사용 설정을 확인합니다.
  * `GET /ai/logs` 또는 이벤트 코드 `1710`을 통해 크레딧 사용량을 모니터링합니다.
</Accordion>

<Accordion title="HTTP 429 속도 제한">
  * flespi는 분당 API + MQTT + 트래픽 사용량을 통합 계산합니다.
  * 요청 빈도를 줄이거나 작업을 일괄 처리합니다.
  * 사용량이 가장 많은 토큰이 먼저 차단되고, 다른 토큰은 계속 작동합니다.
</Accordion>

<Accordion title="허가되지 않은 위치에서 토큰 사용">
  * 토큰에 IP 화이트리스트가 구성되어 있지만 서버 IP가 포함되어 있지 않습니다.
  * flespi 패널에서 토큰의 IP 화이트리스트를 업데이트합니다: **Token settings → IPs whitelist**.
</Accordion>

***

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **전용 토큰** — CloudThinker 전용 토큰을 생성하고, 통합 간에 공유하거나 Master 토큰을 사용하지 마세요.
- **프로덕션에 ACL 사용** — 최소 필요 권한만 있는 ACL 토큰을 사용하고, ACL 토큰은 기본적으로 모두 거부임을 기억하세요.

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="MCP 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/mcp.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c89b6087a9d233901dea5e354452eff6" href="/ko/guide/connections/mcp" width="24" height="24" data-path="images/icons/mcp.svg">
    커스텀 MCP 통합
  </Card>

  <Card title="Kubernetes 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/kubernetes.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=7c03292954ff635a1994623a5c39971b" href="/ko/guide/connections/kubernetes" width="24" height="24" data-path="images/icons/kubernetes.svg">
    IoT 워크로드를 위한 컨테이너 오케스트레이션
  </Card>
</CardGroup>