Flespi

Connect Flespi IoT telematics to CloudThinker for GPS device management, fleet telemetry, and IoT data analysis

Connect your Flespi account to enable CloudThinker agents to manage GPS devices, monitor telemetry, inspect channels and streams, and operate fleet infrastructure through the Flespi MCP server.

Flespi authenticates with an API token (Standard or ACL type) generated in the Flespi panel.

---

Supported platforms

Platform	Support
Flespi Free	1,000 AI credits/month
Flespi Commercial	1,000 AI credits/month + paid overage

---

Prerequisites

• A Flespi account at flespi.io.
• Access to the Flespi panel to create and manage API tokens.
• For production workloads, an ACL token with permissions scoped to the modules CloudThinker needs.

---

Setup

CloudThinker connects to Flespi via their official MCP server using a Flespi API token.

1. Create a Flespi account

   Sign up at flespi.io if you don’t have an account.

2. Generate an API token

   In the flespi panel, navigate to Tokens in the left menu and click the ”+” button:

   • Name: CloudThinker Agent
   • Type: Standard (development) or ACL (production)
   • TTL: Set expiration — e.g., 7776000 (90 days). Flespi requires all tokens to have a TTL or expiration date.

   Copy the 64-byte token immediately.

3. Add connection in CloudThinker

   Navigate to Connections → Flespi and enter the token you just generated.

4. Test connection

   Click Connect. CloudThinker verifies the token and shows a Connected status.

Flespi uses FlespiToken — not Bearer — as the authorization prefix. CloudThinker handles this automatically, but keep it in mind if debugging API calls manually.

---

Connection details

Field	Description	Example
Flespi Token	Flespi API token (64 bytes)	7Bf3...xK9z

---

Required permissions

Token types

Type	Access level	When to use
Standard	Full CRUD on all Telematics entities (devices, channels, streams, plugins, geofences, calculators)	Development and testing
ACL	Granular — deny-all by default, grant per module/method/item	Production recommended
Master	Full admin including platform APIs	Never use with AI agents

Token expiration

Flespi requires all tokens to expire. Set at least one:

• ttl — seconds of inactivity before expiration (resets on each API call)
• expire — Unix timestamp for hard expiration

For long-running integrations, use ttl (e.g., 7776000 = 90 days). The timer resets on every API call, so active tokens won’t expire unexpectedly.

Recommended ACL permissions (production)

Read-only (minimum):

Module	Methods	Purpose
gw/devices	GET	Device list, status, telemetry, messages
gw/channels	GET	Channel list, configuration, status
gw/streams	GET	Stream list, health, delivery stats
gw/calculators	GET	Calculator configurations
ai	POST	Required for MCP tool calls

Read-write (if write operations needed):

Module	Methods	Purpose
gw/devices	GET, POST, PUT	Create/update devices
gw/channels	GET, POST, PUT	Create/update channels
gw/streams	GET, POST, PUT, DELETE	Full stream management

ACL tokens deny everything by default. Only explicitly granted permissions are allowed. A token with POST on gw/devices will not have GET unless also granted.

---

Agent capabilities

Once connected, agents can:

Capability	Description
Device management	List devices, view status, read telemetry and message history
Channel monitoring	Inspect channel configuration, status, and connected protocols
Stream health	Monitor stream delivery stats and health
Fleet telemetry	Query GPS positions, speed, fuel, and sensor data across devices
Geofences	View and manage geofence zones and triggers
Calculators	Inspect calculator configurations for trip detection, fuel consumption, etc.

Available MCP tools

Free tools (0 credits):

Tool	Description
search-api-methods	Discover flespi REST API methods by natural language query
get-api-schema	Retrieve full Swagger schema for a specific API method
flespi-api-read	Execute a read-only GET request to the flespi REST API
flespi-api-write	Execute a write operation (POST/PUT/PATCH/DELETE)

Paid tools:

Tool	Credits	Description
search-flespi-documentation	5	Search flespi platform documentation
search-device-documentation	10	Search device/protocol manufacturer docs
generate-flespi-expression	2	Generate flespi expressions for selectors, calculators
generate-pvm-code	10	Generate PVM (Protocol Virtual Machine) code
consult-flespi-account	30	Delegate complex analysis to flespi AI expert with account read access

AI credits

Plan	Free credits/month	Overage
Free	1,000	Blocked until next month
Commercial	1,000	€1 per 100 additional credits

Monitor usage via the AI tile in the flespi panel, the GET /ai/logs API, or MQTT topic flespi/log/ai/#.

Verify the connection

@alex list all Flespi devices and report their last known positions

Example prompts

@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"

---

Troubleshooting

Invalid or expired access token

• Token may have expired — check TTL and expiration settings in the flespi panel.
• Create a new token and update the connection in CloudThinker.
• Expired tokens are automatically deleted by flespi.

Action is not permitted by ACL

• Your ACL token lacks the required module + HTTP method combination.
• Update the token ACL to grant the needed permission.
• Remember: ACL is deny-all by default — each permission must be explicitly granted.

HTTP 403 on AI tools

• Monthly AI credits are exhausted.
• Free plan: wait for next month. Commercial plan: check overage settings.
• Monitor credit usage via GET /ai/logs or event code 1710.

HTTP 429 rate limit

• flespi calculates combined API + MQTT + traffic usage per minute.
• Reduce request frequency or batch operations.
• The highest-usage token gets blocked first; other tokens continue working.

Using token from unauthorized location

• IP whitelist is configured on the token but your server IP is not included.
• Update the token’s IP whitelist in flespi panel: Token settings → IPs whitelist.

---

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Dedicated token — create a separate token for CloudThinker; never share it across integrations or use a Master token
• ACL for production — use ACL tokens with only the minimum required permissions; ACL tokens are deny-all by default

---

Related

MCP Connection

Custom MCP integrations

Kubernetes Connection

Container orchestration for IoT workloads