flespi AI integration

• Essentials
• MCP servers
• REST API tools
• AI skills
• 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 four 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.
• AI skills — Point your AI agent or IDE to SKILL.md to bootstrap its knowledge about flespi. This is the recommended starting point for agents that need foundational platform context.
• flespi AI agents — skip the integration entirely and let flespi host the agent: an autonomous AI worker living in your account that acts on your behalf, monitors your data, and asks your approval for account-changing operations.

The MCP servers and the REST API tools expose the same set of tools:

On the MCP servers two tools are split: generate-pvm-code lives on the develop server only, search-device-documentation on the support one.

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, and message parameters.
• support — for AI agents diagnosing customer issues, with 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.

The recommended way to connect a client is through a realm: the realm owner enables the realm OAuth server and allows the client, then each user signs in and approves access through the realm login flow — no token is created or shared, and the realm's Info tab provides ready integration buttons for Claude Code, Claude, Cursor, VS Code, LM Studio, and Goose. Alternatively, connect directly with a token.

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.

Each tool accepts one method: GET for search-api-methods and api-method-schema, POST for the rest. Every tool returns 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 api-method-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 api-method-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 skills

flespi publishes a machine-readable SKILL.md following the Agent Skills specification. The skill file provides AI agents with a compact, token-efficient overview of the flespi platform — core concepts, entity types and relationships, REST API guidelines (methods, selectors, response format), MQTT broker usage, flespi expression syntax, and pointers to further documentation and AI tools.

Claude Code (plugin)

/plugin marketplace add flespi-software/skills
/plugin install flespi@flespi-software-skills

VS Code / GitHub Copilot

Add to your .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "flespiToken",
      "type": "promptString",
      "description": "Flespi Token",
      "password": true
    }
  ],
  "servers": {
    "flespi-develop": {
      "type": "http",
      "url": "https://flespi.io/ai/mcp/develop",
      "headers": {
        "Authorization": "FlespiToken ${input:flespiToken}"
      }
    }
  }
}

For knowledge context, also copy .github/copilot-instructions.md to your project's .github/ directory.

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "flespi-develop": {
      "url": "https://flespi.io/ai/mcp/develop",
      "headers": {
        "Authorization": "FlespiToken ${FLESPI_TOKEN}"
      }
    }
  }
}

For knowledge context, also copy .cursorrules to your project root.

Windsurf

Add to your .windsurf/mcp.json:

{
  "mcpServers": {
    "flespi-develop": {
      "serverUrl": "https://flespi.io/ai/mcp/develop",
      "headers": {
        "Authorization": "FlespiToken ${FLESPI_TOKEN}"
      }
    }
  }
}

For knowledge context, also copy .windsurfrules to your project root.

OpenCode

Copy AGENTS.md to your project root, or add to your opencode.json:

{
  "instructions": ["path/to/skills/flespi/SKILL.md"]
}

Manual (any agent)

Copy SKILL.md into your agent's context or instructions file. The content is plain Markdown and works with any LLM-based coding assistant. More information on our GitHub page.

AI credits

AI credits are the unit of consumption for flespi AI services: the REST API tools and MCP servers above, and flespi AI agents. Each tool has a fixed credit cost per call, listed in the tools table above. An agent consumes 50 credits per reasoning step — everything inside the step is covered, and its computational processing between steps is free.

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

• Free accounts — AI tool calls and agents are blocked until the next month.
• Commercial accounts — additional credits are charged at €1 per 100 credits (per-plan maximum limits exist).

Agents blocked by exhausted credits do not lose their tasks: they resume once the counter recovers. Conversations with the AI assistant in HelpBox chat consume no AI credits.

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_calls settings 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 MCP servers, grant POST access to the ai/mcp module — it opens the MCP session and covers every tool called through it.
• For REST API tools, grant GET access to ai/tools for the discovery tools (search-api-methods, api-method-schema) and POST access to ai/tools for the rest.
• Grant the downstream API sections separately: flespi-api-read, flespi-api-write, and consult-flespi-account are checked a second time against the actual path they call, using the same token.
• 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.
• For realm users, prefer connecting via realm OAuth: access is approved through the realm login flow and no token is shared with the client.
• Set a reasonable TTL or expiration time on the token.

Troubleshooting

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

Each tool call 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 and delayed agent steps
• duration>10 — slow calls (over 10 seconds)
• event_code==1703&&agent==123 — reasoning steps of one agent

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

Subscribe to the flespi AI and MCP change log to stay in sync with any updates.