Skip to main content

​
Flespi

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.

​
Supported Platforms

PlatformSupport
Flespi Free1,000 AI credits/month
Flespi Commercial1,000 AI credits/month + paid overage

​
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 Test to verify the connection. The status will show as Connected.
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

FieldDescriptionExample
Flespi TokenFlespi API token (64 bytes)7Bf3...xK9z

​
Token Configuration

​
Token Types

TypeAccess LevelWhen to Use
StandardFull CRUD on all Telematics entities (devices, channels, streams, plugins, geofences, calculators)Development and testing
ACLGranular — deny-all by default, grant per module/method/itemProduction recommended
MasterFull admin including platform APIsNever 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.
Read-only (minimum):
ModuleMethodsPurpose
gw/devicesGETDevice list, status, telemetry, messages
gw/channelsGETChannel list, configuration, status
gw/streamsGETStream list, health, delivery stats
gw/calculatorsGETCalculator configurations
aiPOSTRequired for MCP tool calls
Read-write (if write operations needed):
ModuleMethodsPurpose
gw/devicesGET, POST, PUTCreate/update devices
gw/channelsGET, POST, PUTCreate/update channels
gw/streamsGET, POST, PUT, DELETEFull 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:
CapabilityDescription
Device ManagementList devices, view status, read telemetry and message history
Channel MonitoringInspect channel configuration, status, and connected protocols
Stream HealthMonitor stream delivery stats and health
Fleet TelemetryQuery GPS positions, speed, fuel, and sensor data across devices
GeofencesView and manage geofence zones and triggers
CalculatorsInspect calculator configurations for trip detection, fuel consumption, etc.

​
Example Prompts

@alex list all flespi devices and their last known positions
@alex check stream health and identify any delivery failures
@alex query telemetry for device 12345 over the last 24 hours
@alex show all active channels and their connected protocol types
@alex list geofences and check which devices are inside zone "warehouse-01"

​
MCP Tools

​
Free Tools (0 credits)

ToolDescription
search-api-methodsDiscover flespi REST API methods by natural language query
get-api-schemaRetrieve full Swagger schema for a specific API method
flespi-api-readExecute a read-only GET request to the flespi REST API
flespi-api-writeExecute a write operation (POST/PUT/PATCH/DELETE)
ToolCreditsDescription
search-flespi-documentation5Search flespi platform documentation
search-device-documentation10Search device/protocol manufacturer docs
generate-flespi-expression2Generate flespi expressions for selectors, calculators
generate-pvm-code10Generate PVM (Protocol Virtual Machine) code
consult-flespi-account30Delegate complex analysis to flespi AI expert with account read access

​
AI Credits

PlanFree Credits/MonthOverage
Free1,000Blocked until next month
Commercial1,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/#.

​
Troubleshooting

  • Token may have expired — check TTL and expiration settings in flespi panel
  • Create a new token and update the connection in CloudThinker
  • Expired tokens are automatically deleted by flespi
  • 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
  • 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
  • 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
  • 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 Best Practices

  • Dedicated token — create a separate token for CloudThinker; don’t share across integrations
  • ACL for production — use ACL tokens with minimum required permissions
  • Set TTL — 90 days recommended; auto-renews on active use
  • Never use Master tokens — Master tokens have full platform access including billing and subaccounts
  • IP whitelist — optionally restrict the token to your server IP
  • Rotate regularly — create new tokens and update connections periodically

​
References

MCP Connection

Custom MCP integrations

Kubernetes Connection

Container orchestration for IoT workloads