For AI agents: the complete documentation index is at https://docs.routebase.dev/llms.txt. Every page is also available as Markdown by appending index.md to its URL or by sending Accept: text/markdown.
MCP Reference

MCP CLI Reference

routebase-mcp is the command-line MCP server for Routebase. Your AI agent launches it as a stdio Model Context Protocol server, and it bridges every call to the hosted Routebase MCP endpoint. This page is the complete reference for its environment variables, its subcommands, and what the npm package actually runs on your machine.

One variable is required. That variable is ROUTEBASE_API_KEY, and everything else has a working default.

Installation

The CLI is published on npm as routebase-mcp. Run it on demand with npx, or install it once globally:

# On demand (always the latest)
npx routebase-mcp@latest --stdio

# Or install once
npm install -g routebase-mcp
routebase-mcp --stdio

The package exposes a single binary called routebase-mcp. It needs Node.js 18+.

What npx routebase-mcp actually runs

The npm package is deliberately small, because it contains a launcher script and a list of checksums and nothing else. The MCP server itself is a self-contained native binary, so you do not need the .NET runtime installed to run it.

On the first run the launcher does four things:

  1. It picks the binary for your platform, which is macOS (arm64 or x64), Windows (x64) or Linux (x64). An unsupported platform stops with a message naming the supported ones, and it never falls back to something else.
  2. It downloads that binary from https://releases.routebase.dev/cli/<version>/routebase-mcp-<platform>, pinned to the exact version of the npm package you invoked. There is no floating "latest" in that URL.
  3. It verifies the download against a SHA-256 checksum baked into the package at publish time. On a mismatch the file is deleted and the launcher exits with both hashes in the error. If the package carries no checksum for your platform's file, it refuses to download at all rather than run something unverified.
  4. It caches the verified binary under ~/.routebase/bin/<version>/.

Every later run execs the cached binary directly, with no network call and no checksum re-check. Because the cache path carries the version, upgrading fetches a new binary instead of overwriting the old one, and npx routebase-mcp@<older-version> still runs the binary it was published with.

The launcher writes all of its own output to stderr and never to stdout, because stdout belongs to the JSON-RPC protocol, and a single stray line there corrupts the session.

The launcher script is MIT-licensed, while the binary it downloads is governed by the Routebase terms.

Configuration

routebase-mcp connects to the hosted Routebase MCP endpoint at https://mcp.routebase.dev. That is the default, so you do not configure it. Supply your API key and the CLI is ready:

export ROUTEBASE_API_KEY=<your-api-key>
routebase-mcp --stdio

US-region accounts add one more variable, as described under Regions below.

Environment variables

Variable Required Description
ROUTEBASE_API_KEY Yes API key used to authenticate. Generate one under Settings → API Keys. See the MCP Authentication guide.
ROUTEBASE_REGION US accounts Home region of your account: us or eu. Defaults to eu when unset. Sent as the X-RB-Region header so your requests reach the right region, as described below.
ROUTEBASE_URL No Overrides the target host. Defaults to https://mcp.routebase.dev, and the older https://api.routebase.dev also works. The /mcp path is appended automatically, so set the host, not the full endpoint.
ROUTEBASE_LOG_LEVEL No Log verbosity: verbose, debug, info, warning, error, fatal. Default: warning.

Regions

The hosted endpoints (https://mcp.routebase.dev and the older https://api.routebase.dev) serve both the EU and the US region behind one address each, and pick the region from a signal the client sends. A stdio MCP server has no browser cookie jar, so routebase-mcp sends ROUTEBASE_REGION as the X-RB-Region header instead.

If your account lives in the US region, set it, because otherwise your requests reach the EU region, where your account does not exist:

export ROUTEBASE_REGION=us

The init wizard asks for your region (or takes --region us) and writes the value straight into the generated mcp.json, so configs created with the wizard need no manual export.

Because API keys are stored per region, an unset ROUTEBASE_REGION on a US account does not report a region problem, and it fails as if the key were invalid. If a key you just created is rejected, this is the first thing to check. EU accounts need no setting, because eu is the default.

Values other than us and eu are ignored and fall back to the EU default, so an unresolved ${ROUTEBASE_REGION} in a config file is harmless. The hosted connector for Claude uses a ?region=us query parameter instead of this header, as the MCP Quickstart describes.

Subcommands

(default) — run the stdio server

With no subcommand, routebase-mcp runs as a stdio MCP server. The --stdio flag makes that explicit (it is the default):

routebase-mcp --stdio

The server reads JSON-RPC on stdin and writes responses on stdout. All logging goes to stderr, so it never corrupts the JSON-RPC channel.

init — interactive setup wizard

Generates an IDE-specific mcp.json and prints the environment variables to export.

routebase-mcp init
Flag Description
--api-key <key> API key (skips the interactive prompt).
--url <url> Overrides the Routebase MCP host. Omit it to use https://mcp.routebase.dev.
--region <eu|us> Home region of your API key (skips the interactive prompt). Written into the generated config, so nothing is left to export manually.
--target <ide> Target IDE: claude-code, cursor, or vscode (default: auto-detect).
--output <path> Custom output path for the mcp.json file.

Interactively the wizard walks through three prompts, and each one already offers the right answer as its default:

  1. Choose connection mode 1 (Remote).
  2. Accept the offered host https://mcp.routebase.dev.
  3. Pick your region, where EU is the default.

It asks for your API key first unless --api-key already supplied one, and it detects your IDE on its own, prompting for one only when detection finds nothing. You can also run it fully non-interactively:

routebase-mcp init --api-key "$ROUTEBASE_API_KEY" --region us --target cursor

version — print the version

routebase-mcp version

Logging

Logs are written to stderr only, because stdout is reserved for the JSON-RPC transport. Control verbosity with ROUTEBASE_LOG_LEVEL (default warning). The server's own diagnostics (Routebase.Mcp) are always emitted at Information or above, while noisier framework logs are capped at Warning.

ROUTEBASE_LOG_LEVEL=debug routebase-mcp --stdio

Exit codes

Code Meaning
0 Normal shutdown (stdin closed or interrupted).
1 Fatal runtime error.
2 Configuration error, because ROUTEBASE_API_KEY is not set. Export it, or run routebase-mcp init to write a config that carries it.