Skip to Content

MCP Endpoint

IronFlock is an MCP server. Claude, and any other client that speaks the Model Context Protocol, can list your projects, read their devices, apps and data, and act on them with the tools IronFlock offers, within what your API key allows. The endpoint is part of the same API service as the REST API and uses the same API keys.

Address and Authentication

URL in the IronFlock cloudhttps://api.ironflock.com/mcp
URL on an appliancehttps://api. followed by the appliance’s domain, then /mcp, once the appliance runs the IronFlock API service
TransportStreamable HTTP
AuthenticationAuthorization: Bearer <your API key>

Create the API key in Studio as described in Creating an API Key. Every request carries the key. A request without a key, or with one that is not valid (deleted, expired, or from another IronFlock), is answered with HTTP 401. The server does not offer sign-in through a browser (OAuth): the key is the only way in.

The server keeps no sessions. Every request is answered on its own, so a client can connect, disconnect and reconnect freely. It answers every request with one JSON body and has no event stream to listen to.

Connect Claude

You enter the key yourself, in Claude’s own settings. Never paste it into a chat.

Claude Code

Claude Code connects through the ironflock plugin, which declares IronFlock’s MCP server. It works in the terminal, in the IDE extensions and in the Code tab of the Claude desktop app.

  1. Add the marketplace and install the plugin in a Claude Code session:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. The install opens a dialog with two settings. IronFlock API address is https://api.ironflock.com for the cloud, and https://api. followed by the appliance’s domain for an appliance, in both cases without /mcp and without a slash at the end. IronFlock API key is the key from Studio. Claude Code keeps it in the system’s secure credential store, not in a settings file.

  3. Restart Claude Code. /mcp then lists the server plugin:ironflock:ironflock as connected.

Change the settings later with /plugin configure ironflock@ironflock, and restart Claude Code. Until the key is set, the server does not start. An install from a shell (claude plugin install) does not open the dialog, so complete it with /plugin configure ironflock@ironflock in a session. Build with Claude Code describes the plugins and their skills.

Claude on the Web, on the Desktop and on a Phone, and Cowork

The plugin’s own connection works in Claude Code only. In the chat of the Claude app and in Cowork you add IronFlock once as a custom connector with the key as a request header. Request headers on custom connectors are a beta that is available to a limited set of organizations. If the dialog below has no Request headers section, your organization does not have it yet, and IronFlock cannot be connected there for now: Claude Code works.

  1. Open Customize > Connectors, choose Add, then Add custom connector.
  2. Enter the name IronFlock and the server URL https://api.ironflock.com/mcp.
  3. Set Authentication to No sign-in.
  4. Under Request headers, add the header Authorization with the value Bearer followed by your key: the word Bearer, one space, then the key. Without Bearer IronFlock refuses the request.
  5. Choose Add.

On Team and Enterprise plans an owner adds the connector under Organization settings > Connectors, Add, then Custom; the request headers may be under Advanced. Everybody who uses that connector acts with the one key the owner entered, so give it only the scopes and projects that all of them may use.

A connector’s request headers cannot be edited: to change the key, remove the connector and add it again. The connector connects from Anthropic’s servers, so the address must be reachable from the internet. That is the case for the cloud. An appliance that only your company network reaches usually cannot be connected there, while Claude Code on a computer in that network can.

Other MCP Clients

Any client that supports Streamable HTTP and a request header connects with the URL and the header Authorization: Bearer <your API key>. Keep the key out of files you share or commit.

Check the Connection

Ask Claude to list your IronFlock projects, then the devices of one of them. Claude calls list_projects and list_devices, which only read.

Tools

The server offers 33 tools in these areas. Most of them work in one project and take its swarm_key, which list_projects gives. A tool that changes or deletes something is marked as such, so that clients like Claude can ask you before they call it.

Projects

ToolScopeWhat it does
list_projectsdevices:readLists the projects the key can work in

Devices

ToolScopeWhat it does
list_devicesdevices:readLists a project’s devices, the apps installed on each, whether they run and whether the device is online
create_devicedevices:writeCreates a device in the project and answers its key and name
delete_devicedevices:writePermanently deletes a device from the project

Apps in a Project

ToolScopeWhat it does
list_project_appsapps:readLists the apps installed in the project and on how many devices each runs
check_app_statusapps:readShows whether an app runs on its devices and whether its data arrives
install_appapps:writeInstalls a store app into the project, and optionally onto devices
set_app_stateapps:writeStarts or stops an installed app on devices
update_appapps:writeUpdates an installed app to its newest release
uninstall_appapps:writeRemoves an app from devices, or from the whole project

App Store and Costs

ToolScopeWhat it does
search_appsapps:readSearches the app store by capability and returns matching apps with their prices
get_app_detailsapps:readReads the description, README and price of one to three store apps
get_install_quoteapps:readLooks up what installing an app would cost and what would stop it
estimate_project_costapps:readEstimates the yearly cost of a project setup; nothing is bought
sync_app_to_storeapps:writeOn an appliance only: copies an app of the IronFlock cloud store into the appliance’s own store

Data

ToolScopeWhat it does
get_schemadata:readDescribes the project’s database: its tables, views and columns
execute_sqldata:readRuns one read-only SELECT query on the project’s database
list_dashboardsdata:readLists the project’s dashboards
list_app_filesdata:readLists and searches the files an app stores in the project
read_app_filedata:readReads one file an app stores: text, an image or another file
save_transformdata:writeCreates or replaces a custom transform that keeps a derived figure live for boards
delete_transformdata:writePermanently deletes a custom transform

Alarms

ToolScopeWhat it does
list_alarmsalarms:readLists the project’s alarms with their state, triggers and recipients
create_alarmalarms:writeCreates an alarm that watches an app’s data table
update_alarmalarms:writeChanges an alarm’s trigger or recipients, or pauses and resumes it
delete_alarmalarms:writePermanently deletes an alarm and its history

Logs and Audit Log

ToolScopeWhat it does
get_app_logslogs:readReads an app’s own log output from the devices it runs on
get_device_logslogs:readReads what a device itself has been doing: apps, downloads, disk, network, agent updates
query_audit_loglogs:readRuns one read-only query on the audit log: who changed the project, its devices, groups and apps, and when
get_appliance_healthdevices:readOn an appliance only: checks the state of the appliance’s own platform services, disk, memory, license and updates
get_appliance_logslogs:readOn an appliance only: reads the log of one part of the appliance’s platform

App Tools

Apps bring tools of their own with their AI agents: functions of the app that run on a device, such as reading a machine’s state or changing a setting. Two tools reach them.

ToolScopeWhat it does
list_app_toolsapptools:callLists the tools of an installed app, with their arguments and the instructions of the app’s agents
call_app_toolapptools:callRuns one of them on one device of the project

call_app_tool runs on a device, and an app’s tool can change things there. The device must be one of the project’s devices that the key’s owner can see, and the owner needs the right to use the app’s data, as when operating the app from its board. The app gets exactly the arguments given and nothing else. Only the tools of the installed release are listed, not those of an app’s development version. The texts of a tool are written by the app’s developer and are cut to a fixed length.

Scopes

Each tool needs the one scope shown in the tables above. The server offers a client only the tools the key may use, and refuses every other tool as if it did not exist. Whatever the key allows, a tool never does more than the key’s owner may do in IronFlock. releases:publish has no tool: it is for the REST operations that build releases. See Scopes for all of them, and Creating an API Key for how to choose them in Studio.

A key restricted to projects sees only those projects. A key restricted to one app is offered only the tools that act for an app, so not list_projects. Neither is offered the tools that reach beyond one project: query_audit_log, whose query can name assets of any project the owner may read, the two appliance tools, which belong to no project, and sync_app_to_store, which changes the appliance’s store for everyone.

Some tools carry extra rules:

  • install_app takes the answer of get_install_quote that you were shown, and installs nothing when the price or anything else of that quote has changed since. Installing a paid app costs money.
  • set_app_state and update_app change at most 10 devices in one call.
  • create_device answers the new device’s key and name, and never its configuration file, which holds the device’s credentials. Download the file in Studio, in the device’s settings under Maintenance > Device Configuration File > Download config file, or set the device up on the machine with ironflock agent install --project <project> --name <name>, which creates the device and keeps the file on the machine (Log In & Manage Devices).
  • A project saves one custom transform at a time. A second save_transform while the first runs is refused.
  • An account may run query_audit_log once at a time and six times a minute, because the database behind it is shared.
  • A change that does not finish within its call’s time may still be made. The result says so, and the tool does not repeat it.

Results

A result is JSON, as structured content and as the same JSON in a text block. A long list is cut to fit 50,000 characters, and its cut member says how many entries were left out and how to read on. Images (PNG, JPEG, GIF and WebP) come as images, and other files, such as a PDF, as embedded resources with their media type.

When a tool cannot do what was asked, its result is marked as an error and says why in a sentence, for example that a project does not exist or that the platform did not answer in time.

Limits

These are the defaults, per API key:

Limit
Requests120 per minute, in bursts of up to 30
Requests open at the same time8
Request body1,114,112 bytes: 1 MiB of arguments and the message around them
One tool call90 seconds
A database query30 seconds; execute_sql answers 100 rows unless you ask for more, 1,000 at most
One result50,000 characters; the result of call_app_tool is cut at 45,000

Errors

AnswerMeaningWhat to do
401The key is missing, mistyped or cut off, deleted, expired, or from another IronFlock. In a connector, Bearer may be missingCreate a new key in the Studio of the IronFlock you connect to and enter it again
404 at /mcp/mcp appears twice in the address, or the instance does not offer the endpoint yet, as an appliance that does not run the IronFlock API serviceFix the address; otherwise use the cloud
405GET and DELETE on /mcp: the server has no event stream and no session to endUse POST
413The request body is too largeSend less in one call
429The key made too many requests, or has too many open at once. The Retry-After header says how many seconds to waitWait that long, then go on with fewer calls at once
503The platform is not available at the moment, or the service is shutting downTry again in a minute
504The platform did not answer in timeTry again in a minute

A tool that cannot do what was asked does not answer with an HTTP error: its result is marked as an error and explains in a sentence what went wrong.

Keep Your Key Safe

  • Never paste a key into a chat. If you did, it is part of that conversation: delete the key in Studio, create a new one and enter it in the settings.
  • Studio shows a new key only once, when you create it. Store it in the client’s settings right away.
  • Use one key for each place that uses it, so that you can delete one without breaking the others, and delete keys you no longer use. A key is valid for one year.
  • Give a key only the scopes and projects that Claude needs: a key that may do Everything in All my projects lets Claude do whatever you may do in IronFlock. Tools that change or delete something are marked as such, so that clients like Claude can ask you first. Read what Claude is about to change before you agree.
  • A connector shared by an organization acts with one key for all its users. Use a key of an account that may see only what all of them may see.
Last updated on