Flux Cloud MCP server

An MCP server that lets any AI agent use Flux Cloud, the decentralized cloud: quote an app in US dollars, deploy it, pay for it, watch it come up, read its logs, update it, and cancel it. Works with Claude Code, Claude Desktop, Cursor, Windsurf, OpenCode and every other MCP host.

There is no account. Two keys are the whole identity:

The server generates a pair for you (flux_generate_keys); fund the payment address with FLUX and deploy.

Pricing policy

Every price this 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 percent pay-in-FLUX discount. Quotes come from the network itself (/apps/calculatefiatandfluxprice), so they include the $0.99 minimum, hardware and term discounts, and update credits.

The blockchain's own acceptance threshold is several times lower. It is never shown as a price; it is only checked as a guard before a payment is broadcast.

Install

npm install -g @runonflux/flux-cloud-mcp     # or: yarn global add @runonflux/flux-cloud-mcp

Or run it without installing: npx @runonflux/flux-cloud-mcp.

Claude Code

claude mcp add flux-cloud -s user \
  -e FLUX_ID_PRIVATE_KEY=<wif> -e FLUX_PAYMENT_PRIVATE_KEY=<wif> \
  -- npx -y @runonflux/flux-cloud-mcp

Claude Desktop, Cursor, Windsurf (JSON config)

{
  "mcpServers": {
    "flux-cloud": {
      "command": "npx",
      "args": ["-y", "@runonflux/flux-cloud-mcp"],
      "env": {
        "FLUX_ID_PRIVATE_KEY": "<wif of the Flux ID>",
        "FLUX_PAYMENT_PRIVATE_KEY": "<wif of the payment address>"
      }
    }
  }
}

Keys are optional. Without them every read-only tool works, and flux_generate_keys will create a pair to put into the config.

OpenCode

{
  "mcp": {
    "flux-cloud": {
      "type": "local",
      "command": ["npx", "-y", "@runonflux/flux-cloud-mcp"],
      "environment": {
        "FLUX_ID_PRIVATE_KEY": "<wif>",
        "FLUX_PAYMENT_PRIVATE_KEY": "<wif>"
      }
    }
  }
}

Tools

Resources flux://guide/overview, flux://guide/spec-format, flux://guide/pricing and flux://guide/gotchas give the agent the domain knowledge; the deploy_on_flux prompt walks it through a deployment.

A typical session

> deploy nginx on flux, 3 instances, one month

flux_get_identity      -> Flux ID 1Ab..., payer t1Cd..., 996.98 FLUX ($48.74)
flux_build_spec        -> v8 spec, port 39978 -> 80, r:/data, valid
flux_quote_app         -> $0.99 for 1 month, pay 19.24 FLUX (5% FLUX discount)
   user agrees
flux_deploy_app confirm=true
                       -> message hash 8d2f..., paid 19.24 FLUX, txid 0c41...
flux_wait_for_app      -> accepted at height 2941560, 3/3 instances running
                          https://myapp.app.runonflux.io

How a deployment works

1. The spec is verified by a FluxOS node exactly as it will be at registration (image reachable, architecture, ports, name free).

2. The network quotes the USD price; the server checks the payer's balance.

3. With confirm=true the Flux ID signs the spec, one node broadcasts it to the network and returns a 64-character message hash.

4. The payment address sends the quoted FLUX to the network deployment address with the hash in an OP_RETURN output. Right before signing, the amount is re-checked against a freshly fetched price table, because an underpaid message is dropped silently and the FLUX is not refunded.

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

Updates use the same tool: an existing app of the same owner gets a fluxappupdate message and the network credits the unused part of the old term. Private (enterprise) apps are supported through the enterprise argument: components are encrypted for the network and only ArcaneOS nodes can run them.

Configuration

Security notes

• Private keys stay in the server process. No tool ever returns a configured key; flux_generate_keys returns only the keys it just created.

• Nothing is spent unless a tool is called with confirm=true. Hosts that ask before tool calls will show the USD amount in the arguments' context.

• FluxOS sessions are self-issued signed phrases valid for a few hours; no password or token is stored anywhere.

• Use a dedicated payment address holding only what you intend to spend.

Development

yarn install
yarn type-check && yarn lint && yarn format:check && yarn build && yarn test
yarn test:live      # differential test of the USD estimator against the network

The USD estimator, the specification formatter and the consensus guard mirror the FluxOS code (appSpecHelpers.js, appUtilities.js, messageVerifier.js) and the live test checks the estimator against the network on every run.

License

MIT