How do I connect Claude Code to FreeModel? Two setups, different results

Which one you want

If you are unsure: start with the MCP server. It is the setup the package ships for, and it does not change what happens when you do not invoke the tool.

Setup A: MCP server

The package runs as a local MCP server. Claude Code launches it, and it exposes four tools: browse the catalogue, read your tiers and account, and send one prompt.

{
  "mcpServers": {
    "freemodel": {
      "command": "npx",
      "args": ["-y", "freemodel-mcp"],
      "env": {
        "FREEMODEL_KEY": "sk-your-key"
      }
    }
  }
}

Restart Claude Code after saving. The server appears in the MCP list; if it does not, run npx -y freemodel-mcp by hand once to see whether it starts at all — that separates a config problem from a network one.

The four tools are freemodel_models (public — it works with no key at all), freemodel_tiers, freemodel_account and freemodel_chat. FREEMODEL_API is optional and defaults to https://freemodel.online/v1; set it only to point the server at another deployment.

Setup B: send everything through FreeModel

If you want Claude Code's own requests routed rather than just gaining a tool, point its Anthropic base URL at FreeModel:

export ANTHROPIC_BASE_URL="https://freemodel.online/api/gateway"
export ANTHROPIC_API_KEY="sk-your-key"

The base is the gateway root, not the gateway root plus /v1. Claude Code appends /v1/messages itself; adding /v1 here gives you /v1/v1/messages and a 404.

This changes who answers. Everything Claude Code sends, including tool-use turns, goes through the router, and the router picks the model. To undo it, unset the variable.

Checking it works

Before blaming the client, check the two things it depends on. The model list is public, so this needs no key at all:

# 1. is the gateway reachable and does it serve models?
curl -s https://freemodel.online/v1/models | grep -o '"id"' | wc -l

# 2. is the Anthropic-shaped endpoint there? 401 means yes, key required
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://freemodel.online/api/gateway/v1/messages \
  -H "Content-Type: application/json" -d '{}'

A 401 on the second command is the answer you want. It means the endpoint exists and is waiting for a valid key. A 404 means the path is wrong.

Common problems

Next

Doing it in three steps

Pick the setup first, because the two write to different places. Everything after that is one edit and a restart.

1. Step 1: Decide what you are moving. If Claude should keep answering and only some work should go elsewhere, use the MCP server. If every request should be routed, use the base URL.
2. Step 2: Write the value where Claude Code reads it. The MCP setup goes in ~/.claude/mcp.json under mcpServers. The base URL setup goes in the environment, or in the env block of ~/.claude/settings.json, as ANTHROPIC_BASE_URL plus ANTHROPIC_API_KEY.
3. Step 3: Restart Claude Code and confirm. With the MCP setup the server appears in the MCP list; with the base URL setup any request that comes back has already been through the router.

Pick one, not both. Running them together routes Claude Code's own requests through FreeModel and also hands it a tool that routes further work, a setup that is harder to reason about than either half alone.

What the router is choosing from

With the base URL setup, the model that answers is whichever one the router lands on. That is only a problem if the catalogue behind it is thin, and it is not: the 199 listed models put chat, image, video, speech and embeddings in one list, and 77% of them are chat models[1]. Every turn, including the tool-use turns that read a file or write a patch, is re-decided per request rather than pinned to one model.

For chat there is a second way to hand the choice over: three subscription tier aliases, fm-v1-lite, fm-v1-standard and fm-v1-pro. Name one instead of a concrete id and the router re-resolves it on every call, so a provider that starts failing loses the next request rather than the whole turn. That is the trade the aliases exist for: no stable model name, but nowhere for a dead provider to strand the run.

Claude Code FAQ

Sources

Every third-party figure quoted on this site was read from the vendor documentation linked below, on the date stated. None of these links are affiliate links and none of these vendors paid to be listed. If a number here disagrees with the page it came from, the page is right — tell us and it gets corrected.

• OpenRouter — credit-purchase fees and free-model rate limits
• OpenRouter — rate-limit reference
• OpenRouter — public model list
• LiteLLM — licence, deployment options and supported models
• Cloudflare AI Gateway — features and pricing
• Vercel AI Gateway — features
• Portkey — plans
• Helicone — plans
• Model Context Protocol — specification
• OpenAI Python SDK — base_url and OPENAI_BASE_URL
• Anthropic Messages API — request format

Where the percentages come from

Every share quoted on this site is counted from the live model list, not estimated. Divide the two counts in the last column, round to the nearest whole percent, and you get the number in the first.

[1] Counted on 29 September 2026 from GET https://freemodel.online/v1/models, which needs no key and no account. Every row uses all 199 listed entries as the denominator, because the only thing the endpoint states for every entry is its modality. It no longer publishes per-model capability flags such as tool calling or reasoning, so this site quotes no shares for them. Fetch the list and recount whenever you want to check the arithmetic.