MCP Tools

Give a FreeRouter key tools from catalog MCP servers — weather, finance, web search, and others — without changing your app or locking the model to one provider. Enable servers in Settings, attach them per key, and keep routing as usual.

Why MCP on a router

Most MCP setups bind tools to a single model host. FreeRouter sits in front of the gateways you already use. The same fr_live_… key can fail over or split across OpenRouter, Vercel, Cloudflare, and the rest, and still offer those tools. Swap a provider, remap a model, or add a backup — the MCP catalog stays attached to the key, not to one vendor.

Your app keeps calling POST /v1/chat/completions. FreeRouter offers the enabled tools to the model, runs the calls, and folds the results into the reply. No extra request field. No SDK change.

Two different MCP surfaces. This page is FreeRouter as an MCP client during inference. The MCP Server is the other direction: agents manage keys and routing at https://api.freerouter.com/mcp with a fr_mgmt_… key. FreeRouter keys do not authenticate that endpoint, and management keys do not run chat.

Set it up

  1. Settings → MCP. Turn on the catalog servers this workspace should use. Nothing is on by default. Some servers let you paste your own vendor API key; some require it. If a server has a Docs link, that is the vendor's own setup page.
  2. API Keys → Enable MCPs. Each FreeRouter key opts in on its own. A workspace can enable weather for production and leave a staging key plain. The ? next to Enable MCPs opens the same three steps in the dashboard.
  3. Test in Playground. Pick that key, ask something the tools can answer, and read the reply. Playground uses the same MCP loop as live traffic for that key. Runs are never written to Logs.

We add catalog servers over time. New rows show up under Settings → MCP; they stay off until you opt in.

Monid

Monid is a catalog of third-party data endpoints (social, people, news, scrapers, and more). FreeRouter wraps Monid's HTTP API so you can paste an API key. We do not use Monid's native MCP at https://mcp.monid.ai/v1 — that path is OAuth-only and cannot take a key.

  1. Create a key at app.monid.ai/access/api-keys.
  2. Settings → MCP → turn on Monid and paste the key. FreeRouter never runs your calls against a FreeRouter-held Monid key; spend hits your Monid wallet.
  3. Choose Enable all, Enable none, or a custom subset of endpoints. Enable all is a standing mode: newly cataloged endpoints become allowed automatically. Enable none stays empty as the catalog grows. A custom subset leaves new endpoints off until you opt in.

The model sees two kinds of Monid tool: one tool per enabled endpoint (next section), plus four catalog tools — discover, inspect, run, get_run — for anything keyword ranking did not surface. run and inspect refuse endpoints that are not allowed. Then enable Monid on the FreeRouter key as usual.

Enabled endpoints become tools

Each endpoint you enable in Settings → MCP → Monid is offered to the model as its own tool, named after the provider and endpoint (mcp__monid__cars_com__search_listings) and carrying the provider name, the endpoint's description, its price, and its real input fields. You do not have to mention Monid in a prompt: "find Tesla Model 3 listings on cars.com near 78738" ranks the Cars.com tool on its own words, and the request runs through Monid in one turn.

  • Only what fits is sent. The tool loop preloads at most 24 tools per turn, ranked by relevance to the prompt (a hard cap of 64 tools per upstream request covers what find_tools adds). Enable five endpoints or five hundred; the model sees the few that match, and reaches the rest through find_tools.
  • A short catalog line. The system prefix names the Monid endpoints loaded for the turn (up to twelve) and says how many more are available, so the model knows to prefer them over general web search for that kind of request.
  • Schemas. Input fields come from Monid's inspect. The nightly catalog job stores them; anything still missing is fetched the first time that endpoint is offered.
  • Async runs. Endpoints that answer with a run id are polled to completion inside the tool call, so the model gets the result in one step. If a run is still going after about half a minute, the model gets the run id and can poll it.
  • Enable all. With the whole catalog enabled, the same mechanism applies: relevant endpoints are offered directly, and discover, inspect, and run remain for anything keyword ranking misses.

Steering message

Attaching tools tells the model what it can call. A steering message tells it when. It is a short instruction FreeRouter appends to the system prompt of every request made with a key, after your application's own system prompt and before the request reaches the provider. Nothing in your code changes.

Set it in two places:

  • Workspace default — Settings → Steering message. Applies to every key that has no message of its own.
  • Per key — API Keys → the key's Advanced section, or steering_message on the management API and MCP server. A key's message replaces the workspace default; it does not add to it.

Examples that work well with the catalog servers:

Use Monid for anything about real estate listings.
Check Monid for a matching tool before answering from memory.
Prefer Parallel web search for news questions.

Plain text, up to 2000 characters. When a request already carries a system message the steering text is appended to it after a blank line; when it does not, FreeRouter adds one. On requests that offer MCP tools, the steering text is placed after the MCP tool prefix and marked as your standing instruction, so it is the last thing the model reads before choosing a tool. Both fields are optional: leave them empty and requests go upstream exactly as your app sent them. The steering message applies on all three API shapes and whether or not MCP servers are attached.

Bring your own key

Each catalog server can use a FreeRouter-held global key for tool discovery, a workspace key you paste, or both:

  • Optional BYOK — paste a vendor key in Settings to use yours instead of the FreeRouter key. Leave it blank to keep the FreeRouter key.
  • Required BYOK — that server will not run on inference until the workspace pastes a key. Enablement is blocked until you do. Discovery (listing tools in admin) can still use the global key.

Workspace keys are encrypted at rest and used only for that workspace's handshakes. They are not copied onto individual API keys. Clearing an optional key falls back to the FreeRouter key; a required server has no fallback.

What happens on a request

When a key has at least one MCP server enabled, a request on any API shape runs a short tool loop — streaming included:

  1. FreeRouter offers the enabled tools (capped, relevance-ranked) plus a find_tools helper so the model can ask for more.
  2. If the model returns tool_calls, FreeRouter executes them against the matching MCP servers, in parallel when there are several.
  3. Tool results go back to the same model on the same routing rule. After 6 rounds (operators can set 1–10 with FR_MCP_MAX_ITERS), tools are stripped so the model has to answer.

If a server is down, rejects credentials, or times out, that tool fails open: the chat still returns. MCP never turns a good model call into a 5xx.

Budgets inside the loop. A remote catalog server gets 8 seconds to list its tools and 20 seconds per tool call; past that the call fails open. Each tool result is cut to 24,000 characters before it goes back to the model, so a verbose endpoint cannot blow the context window. Each model round still waits on the key's own timeouts.

The client request is unchanged:

curl https://api.freerouter.com/v1/chat/completions \
  -H "Authorization: Bearer $FREEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "What's the weather in Paris?" }]
  }'

Use a model that will actually call tools. If the key has no MCP servers enabled, the request is plain inference — same as before.

Limits

  • The loop runs on every shape: POST /v1/chat/completions (OpenAI, including the dashboard playground), POST /v1/responses, Anthropic /v1/messages, and Google generateContent. The Anthropic and Google bodies are translated to the OpenAI form first, the loop runs, and the final reply is translated back.
  • stream: true runs the loop too, on /v1/chat/completions and /v1/responses. You still receive one response: the turns are merged, so any prose the model produces along the way ("let me look that up") arrives in order, while the tool calls FreeRouter ran on your behalf stay hidden. Only the final turn carries a finish_reason, and there is exactly one data: [DONE]. The Anthropic shape streams the loop too, merged into one message. The Google shape does not support streaming at all yet.
  • Tools you send yourself are never executed by FreeRouter. If your client runs its own MCP servers (OpenCode, Codex CLI, or anything using the OpenAI SDK tool loop), your tools ride the request untouched and their tool_calls come straight back for you to execute — streamed or buffered. FreeRouter only runs tools from servers attached to the key, and tells them apart by name. A turn that mixes both is handed to you whole rather than half-answered.
  • Catalog servers are remote HTTP / SSE. Command / npx (stdio) servers are not supported yet. You cannot add an arbitrary URL from the workspace — only servers in the FreeRouter catalog.
  • A required-BYOK server with no workspace key is omitted from the tool list for that request. Other enabled servers still run.

Troubleshooting

What you seeWhat it means
No tools, plain chatMCP is off for that key, or the workspace has not opted into any servers. Enable MCPs on the key after Settings → MCP. (Streaming is no longer a reason — the loop runs on streams for the OpenAI shapes.)
Enable MCPs says to configure Settings firstThe workspace has not turned on any catalog servers. Opt in under Settings, then return to the key.
Settings asks for your API keyThat server is marked required BYOK. Paste the vendor key (or leave the server off). Optional BYOK can stay empty and use the FreeRouter key.
The model never calls a toolThe prompt may not need it, or the model is weak at tool use. Try a tool-capable model and a question the catalog can actually answer. Playground is the fastest check.
Chat succeeds but a tool looks skippedThat server timed out, 401'd, or is required-BYOK without a workspace key. Inference still returns. Check Settings for a saved key, and Logs for a normal model path.
Next MCP Server