Set up the Flux tools server (MCP)

Your agent reaches models through the Flux base URL. It reaches Flux abilities, such as reading a web page or making an image, through the Flux tools server: a remote MCP (Model Context Protocol) server on the same key. Add it once and your agent sees the Flux tools next to its own. Live

Keep the trailing slash on the URL. Without it the server answers with a redirect, which some clients do not follow.

Before you start#

• A Flux key. Copy one from your keys page. The tools server takes the same sk-flux key your agent already uses for models. It does not take provider keys, and it does not take a sign-in: set the key in a header, as below.
• A paid, cleared plan for most tools. Page reading, images, search, transcription and speech are paid abilities. On the Free plan your agent still sees them, and a call returns a clear refusal with a link to upgrade. See Plans.
• An agent that can add a remote MCP server with a header. Most can. If yours only runs local (stdio) servers, see Tools that need a workaround.

Add the server to your agent#

Pick your agent. Each tab is copied from that agent's own docs, with the date we checked it. Restart the agent after you add the server, so it loads the tool list.

claude mcp add --transport http flux-tools https://api.fluxrouter.ai/mcp-tools/ \
  --header "Authorization: Bearer sk-YOUR-FLUX-KEY"

[mcp_servers.flux-tools]
url = "https://api.fluxrouter.ai/mcp-tools/"
bearer_token_env_var = "FLUX_API_KEY"

{
  "mcpServers": {
    "flux-tools": {
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": {
        "Authorization": "Bearer sk-YOUR-FLUX-KEY"
      }
    }
  }
}

mcp_servers:
  flux-tools:
    url: "https://api.fluxrouter.ai/mcp-tools/"
    headers:
      Authorization: "Bearer sk-YOUR-FLUX-KEY"

{
  "mcpServers": {
    "flux-tools": {
      "type": "streamableHttp",
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": {
        "Authorization": "Bearer sk-YOUR-FLUX-KEY"
      }
    }
  }
}

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);

The curl, Python and TypeScript tabs call the server directly, which is handy for checking a key before you touch an agent's config. The server is stateless, so one tools/call needs no handshake first, and the reply arrives as a server-sent event (a data: line holding the JSON).

Anything not listed: any OpenAI-compatible tool, any Anthropic-compatible tool or a custom endpoint. Many agents use the same mcpServers JSON shape:

{
  "mcpServers": {
    "flux-tools": {
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": { "Authorization": "Bearer sk-YOUR-FLUX-KEY" }
    }
  }
}

Check it works#

Ask your agent: "Call the Flux list_capabilities tool and tell me what it returns." The answer shows your plan (tier), whether paid abilities are unlocked on this key (premium_unlocked), and each ability you can use under enabled, with an estimate of what a call costs. list_capabilities is never billed.

Then try a real task, for example: "Read https://example.com with the Flux web_fetch tool and summarise it in one line."

If the agent cannot find the tools, see Tools server problems.

The tools#

The server shows each account the tools it can use. list_capabilities is always there. Each tool calls the matching Flux API route with your key, so it behaves and bills exactly like that route.

Some things are only in the API, not in the tools:

• Image edits. There is no edit tool. Edit with reference images from your own code; see Make and edit images.
• Rendered page reads. web_fetch takes a url only. To render a page's JavaScript first, call the API with render; see Read a web page.

A tool that is built but not switched on for your account answers ability_disabled, and the server tells your agent not to retry it. It starts working when the ability is switched on, with no change on your side.

Tool limits that differ from the API:

• transcribe takes audio up to 8 MB, from a public https URL or inline as base64.
• speak takes up to 1,000 characters per call, fewer than the API, so the audio it returns does not flood your agent's context.
• apps_execute runs exactly one action per call.

Full schemas, return values and the route behind each tool are in the tools server reference.

What it costs#

The tools server adds no charge of its own. A tool call is billed exactly like the matching API call on the same key, and lands on the same bill.

Each paid tool returns its cost with the result. For how charges reach your bill, see How billing works.

When a tool says no#

The server never answers with a raw error. A refused call comes back as a normal tool result with an error code, a plain-English message your agent can act on, and a retryable flag.

Each fix is on Tools server problems. For HTTP errors across the whole API, see Errors.

The routing server#

Flux runs a second MCP server at https://api.fluxrouter.ai/mcp. It does not add abilities. It lets an MCP client work with routing directly:

• flux_route sends a prompt through Flux.
• flux_explain shows which model answered a routed prompt and what it cost.
• flux_models lists the models.

Connect it with the same key in the Authorization header:

{
  "mcpServers": {
    "flux-router": {
      "url": "https://api.fluxrouter.ai/mcp",
      "headers": { "Authorization": "Bearer sk-YOUR-FLUX-KEY" }
    }
  }
}

Most agents do not need it: they already reach every model through the base URL. Add the tools server first. The routing server's details are in the tools server reference.