Inside the Flux Cloud MCP Server: How It Actually Works

Fluxers! We have written about what the Flux Cloud MCP server does — it lets any AI agent deploy and run applications on the decentralized cloud. This article is about how, in detail: the fifteen tools, what happens in the five steps of a deployment, how private applications are handled, and the design decisions behind the hosted version.

If you are building agent tooling against infrastructure, there is a lot in here that generalises.

The tool surface

Fifteen tools, and only two of them can spend anything. That split is deliberate and it is the first thing to understand about the design.

Identity and pricing — flux_get_identity returns the Flux ID, payment address and balance in both FLUX and USD. flux_generate_keys creates a fresh pair with setup instructions. flux_get_pricing returns the USD rate card, the live FLUX rate, discounts and reference sizes. flux_get_network_info gives node counts, chain height and the deployment address.

Building a deployment — flux_build_spec turns a plain description (image, ports, CPU, RAM, disk, months) into a full v8 specification. flux_validate_spec checks it against local rules and verifies it on a real FluxOS node. flux_quote_app returns the USD price and the FLUX to pay, for a registration or an update.

Deploying — flux_deploy_app plans by default, and only signs, broadcasts and pays when called with confirm=true. flux_wait_for_app polls until the application is accepted and its instances are running, then returns the URLs.

Running it — flux_get_app returns any application’s spec, expiry, instances and URLs. flux_list_my_apps lists what the Flux ID owns with instance counts and days remaining. flux_get_app_logs and flux_get_app_stats return container logs and live CPU, memory and network from an instance, for the owner only. flux_control_app restarts, redeploys or removes instances, per node or globally. flux_cancel_app ends an application early by shortening its term.

Alongside the tools are four resources — an overview, the spec format, pricing and a gotchas guide — plus a deploy_on_flux prompt that walks an agent through a deployment. Giving the agent documentation as resources rather than stuffing it into every tool description keeps the schemas small, which on a long agent conversation is the difference between a usable context budget and a wasted one.

Plan by default

The single most important line in the whole design: flux_deploy_app plans unless you pass confirm=true.

An agent that calls the deploy tool because it seemed like the next reasonable step gets a plan and a price, not a transaction. Spending requires a second, explicit call that the agent has to decide to make — which is the moment a well-behaved agent stops and asks you.

The same applies to cancelling. Thirteen of the fifteen tools cannot spend anything at all, so an agent can explore the network, size a workload, price it and compare options with an empty wallet and no possibility of surprise.

What actually happens in a deployment

Five steps, and each has a reason to exist.

1. The spec is verified exactly as it will be at registration. Image reachable, architecture supported, ports valid, name free. This runs through the load-balanced API — and if the balancer refuses, the server probes a few healthy nodes and tries them in turn. A decentralized network means there is always another node to ask, and the client may as well use that.

2. The network quotes the USD price and the server checks the payer’s balance. Finding out you cannot afford something before signing it is better than after.

3. With confirmation, the Flux ID signs the spec, the same endpoint broadcasts it to the network, and a 64-character message hash comes back.

4. The payment address sends the quoted FLUX to the network deployment address, with that hash in an OP_RETURN output. And here is the detail worth copying: right before signing, the amount is re-checked against a freshly fetched price table. An underpaid message is dropped silently and the FLUX is not refunded, so a price that moved between the quote and the broadcast must not be allowed to cost you the payment. Re-checking at the last possible moment closes that window.

5. Nodes pair the confirmed payment with the message and publish the application. Instances spawn and pull the image.

Notice what is absent from all five steps. No account. No session. No API token issued by anyone. The Flux ID signs, the payment address pays, and the network verifies both — which is exactly why a program can do this alone.

Pricing you can trust

Every price the server shows is the Flux Cloud USD price — the same one home.runonflux.io charges — converted to FLUX at the live market rate with the 5% pay-in-FLUX discount applied.

Quotes come from the network itself, so they already include the $0.99 minimum, hardware and term discounts, and update credits. The blockchain’s own acceptance threshold is several times lower than that, and the server never shows it as a price — it is only checked as a guard before a payment is broadcast. An agent quoting a number you would not actually have paid in the web interface would be a defect, not a feature.

Private applications

Enterprise applications on Flux encrypt their components, and only ArcaneOS nodes can run them. On chain they publish an empty component list — which is correct for privacy and unhelpful for an agent trying to tell you why your app is not responding.

So flux_get_app, flux_get_app_logs and flux_get_app_stats fetch the decrypted specification from an ArcaneOS node using the owner key, when that key is configured or passed.

The boundary is drawn carefully: only component names, images, ports and sizes come back. Environment variables, commands and registry credentials never leave the server. The agent gets exactly enough to reason about the deployment and nothing that would be damaging in a chat transcript.

Telling you why something is down

A lot of the work since the first release went into diagnostics, because “my app is not responding” is the question an agent is least equipped to answer on its own.

flux_get_app now distinguishes three situations that look identical from the outside and have completely different fixes: an application with nothing listening, a service that is running but is not HTTP, and a private application. It also queries the responsible gateway node directly — so when a gateway is having a bad day, the diagnosis names the gateway rather than blaming your container.

Getting this right is what separates a tool an agent can debug with from one that just reports failure. The agent does not have to guess, because the tool already asked the right question.

Updates, and the credit for unused time

Updating is the same tool. An existing application belonging to the same owner receives an update message, and the network credits the unused part of the old term against the new one — so changing an application mid-term does not throw away what you already paid for.

The hosted server

Some hosts cannot start a local process — claude.ai connectors, ChatGPT, browser and mobile agents. So the same server also runs on Flux Cloud itself, over Streamable HTTP, at mcp.runonflux.com/mcp (and mcp.runonflux.io/mcp).

The hosted server holds no keys. Read-only tools need none at all. Tools that sign or pay take the keys as call arguments, used in memory for that call, never logged and never stored.

The server’s own instructions tell agents to create a dedicated pair with flux_generate_keys and to have you fund only what a deployment actually needs, rather than asking for keys from a wallet you use elsewhere. The reasoning is plain: anything typed into a chat passes through the AI vendor and the host’s history, so a pair used that way should be treated as disposable and kept on a small balance. For larger budgets, run the local server, where keys never leave your machine.

We would rather give that advice prominently than let someone learn it the hard way.

Run your own

The server is stateless, so any number of instances can sit behind one load balancer, and GET /healthz reports liveness:

docker run -p 3000:3000 runonflux/flux-cloud-mcp

The Flux application specification that runs the public instance is in the repository under deploy/cloudmcp.json — the hosted MCP server is itself a Flux app, deployed the same way it deploys yours.

A session, end to end

What “deploy nginx on Flux, three instances, one month” actually looks like:

• flux_get_identity — Flux ID, payer address, 996.98 FLUX ($48.74)
• flux_build_spec — a v8 spec, port mapped, volume set, valid
• flux_quote_app — $0.99 for one month, pay 19.24 FLUX with the 5% discount
• you agree
• flux_deploy_app confirm=true — message hash, 19.24 FLUX paid, transaction id
• flux_wait_for_app — accepted at a block height, 3 of 3 instances running, here is your URL

Under a dollar, no account, and the only human decision in the loop is the one that spends money.

Get it

Install with npm install -g @runonflux/flux-cloud-mcp, or run it with npx and no install at all. It is registered with the MCP Registry, and the documentation lives on docs.runonflux.com under Deploy with AI Agents.

Ask your agent what something would cost before you give it any keys. That part is free, and it is the fastest way to see whether this fits how you work.