Docs · Claude Code
Two setups, and they do different things
FreeModel is an AI model gateway: one key for 477 models across dozens of providers, routed by task with free capacity tried first. Claude Code can use FreeModel as a tool it calls, or as the thing that answers everything. Pick based on what you actually want to move.
Which one you want
| Question | MCP server | Base URL |
|---|---|---|
| What changes | Claude Code gains a tool that routes a task to another model | Every request Claude Code makes goes to FreeModel |
| Who answers normally | Claude, as before | Whichever model the router picks |
| Good for | Keeping Claude's behaviour, but sending some work elsewhere | Cutting cost or switching model without changing how you work |
| Config file | ~/.claude/mcp.json | Environment or ~/.claude/settings.json |
| Reversible by | Deleting the MCP entry | Unsetting one variable |
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 a tool that picks a model based on the task you describe.
{
"mcpServers": {
"freemodel": {
"command": "npx",
"args": ["-y", "freemodel-mcp"],
"env": {
"FREEMODEL_KEY": "sk-your-key",
"FREEMODEL_API": "https://freemodel.online/api/gateway"
}
}
}
}
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.
FREEMODEL_API is the base without a trailing /v1. The package
appends its own paths.
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
| Symptom | Cause |
|---|---|
| MCP server not listed | Bad JSON in mcp.json, or npx is not on PATH for the GUI process |
| Server listed, tool errors | Wrong FREEMODEL_KEY, or FREEMODEL_API has a trailing slash |
| 404 from every request | Base URL has /v1 in it when it should not |
| 401 from every request | Key missing the sk- prefix, or the environment variable is not exported in the shell that launched the client |
| Worked in one terminal, not another | export only affects the shell it ran in. Check ~/.claude/settings.json if you want it everywhere |