Flux tools server reference

The Flux tools server gives an agent every Flux ability as an MCP tool. To add it to an agent, see Set up the Flux tools server. This page is the exact contract.

Transport and auth#

curl https://api.fluxrouter.ai/mcp-tools/ \
  -H "Authorization: Bearer sk-YOUR-FLUX-KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_capabilities","arguments":{}}}'

import json
import requests

resp = requests.post(
    "https://api.fluxrouter.ai/mcp-tools/",
    headers={
        "Authorization": "Bearer sk-YOUR-FLUX-KEY",
        "Accept": "application/json, text/event-stream",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {"name": "list_capabilities", "arguments": {}},
    },
)
resp.raise_for_status()

# The reply is a server-sent event: read the JSON after "data:".
for line in resp.text.splitlines():
    if line.startswith("data:"):
        message = json.loads(line[len("data:"):])
        print(message["result"]["structuredContent"])

const resp = await fetch('https://api.fluxrouter.ai/mcp-tools/', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-YOUR-FLUX-KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json, text/event-stream',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: { name: 'list_capabilities', arguments: {} },
  }),
});

// The reply is a server-sent event: read the JSON after "data:".
const text = await resp.text();
const line = text.split('\n').find((l) => l.startsWith('data:'));
const message = JSON.parse(line!.slice('data:'.length));
console.log(message.result.structuredContent);

How tools bill#

The tools server writes no charge of its own. Each tool calls the matching Flux API route over the server's own network, with your key, so the route authenticates, gates and bills the call exactly as if you had sent it yourself. The bill, the limits and the errors are the route's.

The tools#

list_capabilities#

Always listed, never billed. Live

• Arguments: none.
• Returns: tier (your plan), premium_unlocked (whether paid abilities work on this key) and enabled, an object keyed by ability. Each entry has premium (whether it needs a paid plan) and either est_microcents (an advisory cost per call, in millionths of a US dollar) or tools (each tool's billing rule, for abilities billed per unit). Entries may carry other fields; ignore any you do not use.

web_fetch#

Live Calls POST /v1/fetch; see the fetch reference.

• Returns: markdown, format, url and cost_microcents. Always a plain read: render is API only.

web_search#

Rolling out Calls POST /v1/search; see the search reference.

• Returns: answer, citations (URLs), searches, cost_microcents and cost_usd.

image_generate#

Live Calls POST /v1/images/generations; see the images reference.

• Returns: the generation response (created, data with the base64 image) plus cost_microcents. Your agent decodes b64_json and saves the file itself.
• There is no edit tool. Edits are API only.

transcribe#

Shipping Calls POST /v1/audio/transcriptions; see Speech to text.

• Audio up to 8 MB.
• Returns: text, billed_seconds and cost_usd.

speak#

Shipping Calls POST /v1/audio/speech; see Text to speech.

• Returns: an audio content block (base64) plus voice, format, mime_type, bytes, billed_chars and cost_usd. Your agent writes the audio to a file itself.

Apps tools#

Shipping apps_list, apps_connect, apps_find_actions and apps_execute connect your Flux account to apps such as Gmail or Slack and run actions in them.

What they return, and how to chain them, is on the apps page.

Which tools you see#

• tools/list shows every tool your account can call, including paid tools on a Free plan.
• A paid tool called on a Free plan answers premium_locked. After that refusal it appears once more in tools/list, then drops out of that account's list, so the agent stops trying it. It comes back once the plan is paid and cleared.
• Each paid tool's description carries your plan and an advisory cost per call.

Tool error objects#

A refusal is a normal tool result, never a protocol fault. Its structured content is:

{
  "error": "premium_locked",
  "capability": "web_search",
  "message": "Web search needs a paid, cleared Flux plan. Upgrade at https://fluxrouter.ai/home/billing.",
  "upgrade_url": "https://fluxrouter.ai/home/billing",
  "retryable": false
}

Fixes are on Tools server problems.

The routing server#

A second MCP server at https://api.fluxrouter.ai/mcp exposes routing, not abilities. Status: Live

Errors on this server are JSON-RPC errors: the standard codes -32700 to -32603, plus these Flux codes: