flespi AI integration

• Essentials
• MCP servers
• REST API tools
• AI credits
• Token security
• Troubleshooting

Essentials

The /ai/ module provides programmatic access to flespi capabilities for AI agents. It is currently experimental and subject to change.

There are two ways to access AI flespi services:

• MCP servers — for AI agents and IDEs (Claude Code, Cursor, etc.) that support the Model Context Protocol. MCP wraps the tools below with built-in instructions and the ability to execute flespi API calls directly. Two server types are available: one for development workflows and one for support diagnostics.
• REST API tools — standalone HTTP endpoints for scripts, CI/CD pipelines, or any system that needs direct request-response access without MCP. You control context and orchestration.

Both layers expose the same set of tools:

When choosing between search-flespi-documentation (5 credits) and consult-flespi-account (30 credits):

• use documentation search for general platform questions that can be answered from docs and API specs alone;
• use account consultation when the answer requires reading your actual account data — device status, logs, configuration issues, or cross-component analysis.

Tools that consume credits also count toward the per-minute ai_calls rate limit. When credits are exhausted the API returns HTTP 403; when the rate limit is exceeded — HTTP 429.

MCP servers

MCP (Model Context Protocol) is a standard that allows AI agents to discover and use external tools. flespi provides two MCP servers, each tailored for a specific workflow:

• develop — for AI agents building applications on top of flespi. Instructions cover platform entities, API namespaces, MQTT topics, message parameters, and flespi expression language.
• support — for AI agents diagnosing customer issues. Same tools as develop, plus built-in diagnostic patterns (connectivity checks, data gap analysis, stream failures, permission errors) and investigation guidance.

Both servers additionally expose flespi-api-read and flespi-api-write tools that execute REST API calls with the permissions of the provided token. This means your AI agent can read device messages, check logs, create entities, or send commands — all within the boundaries of the token's ACL.

Setup for Claude Code:

claude mcp add flespi "https://flespi.io/ai/mcp/develop" \
  -t http -H "Authorization: FlespiToken "

Generic MCP client configuration (JSON):

{
  "mcpServers": {
    "flespi": {
      "type": "http",
      "url": "https://flespi.io/ai/mcp/develop",
      "headers": {
        "Authorization": "FlespiToken "
      }
    }
  }
}

Replace develop with support for the support agent server.

REST API tools

The same tools are available as standalone REST API endpoints under /ai/tools/. Unlike MCP servers, REST API tools are stateless — each call is independent, and you control the context and orchestration in your application.

All tools accept a POST request and return a JSON object with result (text or structured data) and credits (AI credits consumed).

Recommended API discovery workflow for agentic systems:

1. Use search-api-methods to find relevant endpoints by natural language query.
2. Use get-api-schema to retrieve the full Swagger schema with parameters, fields, and selectors.
3. Call the flespi REST API directly using the discovered method.

API discovery tools (search-api-methods and get-api-schema) are free and instant — AI agents can use them liberally to navigate the flespi API.

For general flespi REST API usage, authentication, and response format details, see flespi API basics.

AI credits

AI credits are the unit of consumption for AI services accessed via REST API tools and MCP servers. Each tool has a fixed credit cost per call, listed in the tools table above.

Every flespi plan includes 1,000 AI credits per month. When the monthly budget is exhausted:

• Free accounts — AI tool calls are blocked until the next month.
• Commercial accounts — additional credits are charged at €1 per 100 credits.

The following do not consume AI credits: conversations with the AI assistant in HelpBox chat.

You can monitor credit usage and rate limits on the AI tile in the flespi panel dashboard or via the /ai/logs endpoint. Credit allocation for subaccounts is configurable through the ai_credits parameter in limit settings. To disable access to AI services for subaccounts you may zero ai_credits and ai_callssettings in their limits.

Token security

The flespi-api-read and flespi-api-write MCP tools execute flespi REST API calls using the permissions of the token you provide. The write tool can create, modify, and delete platform items if the token allows it.

Recommendations:

• Create a dedicated ACL token for each AI agent. ACL tokens deny everything by default, so you explicitly grant access only to the API sections and HTTP methods the agent needs.
• For read-only agents: grant only GET access to the required sections (e.g., gw/devices, gw/channels, storage/containers).
• Avoid providing Master or Standard tokens to AI agents — these grant broad access that cannot be restricted per-method.
• Set a reasonable TTL or expiration time on the token.

Troubleshooting

All AI tool calls are recorded to the /ai/logs subsystem with the following event codes:

Each log entry contains the tool name, credits consumed, call duration, status code, token ID, and request arguments. Use filter expressions to narrow down the logs, for example:

• tool=="search_flespi_documentation" — filter by tool name
• credits>0 — only calls that consumed credits
• status_code==2 — blocked calls only
• duration>10 — slow calls (over 10 seconds)

AI logs are also accessible in the flespi panel under Toolbox and via MQTT subscription to flespi/log/ai/# topic.