MCP Tools

Give a FreeRouter inference 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.

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.

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 non-streaming OpenAI-shaped chat completion runs a short tool loop:

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 a few rounds, 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.

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 non-streaming POST /v1/chat/completions (OpenAI shape, including the dashboard playground). stream: true, Anthropic /v1/messages, and Google generateContent skip MCP and return a normal model reply.
• 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