Tools server problems

Each entry gives the symptom, the cause and the fix. The setup guide is Set up the Flux tools server; the exact contract is in the tools server reference.

The agent shows no Flux tools#

Cause. One of these:

• The agent was not restarted after you added the server.
• The URL is missing its trailing slash. https://api.fluxrouter.ai/mcp-tools answers 307, and some clients do not follow it.
• The server entry is in the wrong file or under the wrong key for that agent.

Fix. Use https://api.fluxrouter.ai/mcp-tools/, with the slash, and restart the agent. Check the entry against your agent's tab on the setup page.

Every call says auth_failed, or the server answers 401#

Cause. The header is missing or malformed, or the key is revoked or expired. The tools server only takes Flux keys: provider keys do not work.

Fix. The header must read Authorization: Bearer followed by your full sk-flux key. Keys are only shown in full when you create them, so make a new one on your keys page if you did not keep it. Check the agent reads the key where you think it does: some read it from an environment variable.

The agent asks me to sign in#

Cause. Some MCP clients try a browser sign-in when they first meet a server. The Flux tools server does not use one.

Fix. Cancel the sign-in and set the key in the Authorization header, as on the setup page. If your agent cannot send a header to a remote server, see Tools that need a workaround.

A tool is listed, but calling it says premium_locked#

Cause. The tool needs a paid, cleared plan. Paid tools are listed on the Free plan on purpose, so your agent knows they exist; each description says an upgrade is required.

Fix. Upgrade in Billing. See Plans.

A tool disappeared from the list#

Cause. After a paid tool refuses your account with premium_locked, it is listed once more and then hidden from that account's tool list, so the agent stops spending turns on it.

Fix. Upgrade, then restart the agent so it fetches the list again.

web_fetch says payment_required#

Cause. Page reading is paid, and the page route refused the key. The tools server reports any payment refusal from a route as payment_required.

Fix. Upgrade, or add credit, in Billing.

A tool says ability_disabled#

Cause. The ability is built but not switched on for your account yet. The server tells your agent not to retry.

Fix. Nothing to change on your side. The tool starts working when the ability is switched on. Current status is on Set up the Flux tools server.

A tool says rate_limited#

Cause. Too many calls in a short time. Transcription, speech and search share one per-account limit of 60 requests a minute.

Fix. Wait retry_after_seconds when it is given, then retry.

A tool says invalid_request or too_large#

Cause. An argument was refused: a private URL, an unknown voice, a file over the limit, or text too long for the tool. message says which.

Fix. Fix the argument. Retrying the same call fails the same way. Two tool limits are lower than the API's: transcribe takes up to 8 MB and speak takes up to 1,000 characters per call.

A tool says capability_unavailable#

Cause. A temporary fault. The result has a reason instead of a message.

Fix. Retry shortly when retryable is true.

My agent only supports local servers#

Cause. Some agents cannot add a remote server with a header yet.

Fix. See Tools that need a workaround.

Still stuck#

See My tool won't connect for base URL and key problems, or ask support.