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: ROUTEBASE_API_KEY. 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: routebase-mcp. It needs Node.js 18+.

What npx routebase-mcp actually runs

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

On the first run the launcher:

  1. Picks the binary for your platform: macOS (arm64 or x64), Windows (x64), or Linux (x64). An unsupported platform stops with a message naming the supported ones — it never falls back to something else.
  2. Downloads it 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. 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. Caches the verified binary under ~/.routebase/bin/<version>/.

Every later run execs the cached binary directly — no network call, 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, never stdout: stdout belongs to the JSON-RPC protocol, and a single stray line there corrupts the session.

The launcher script is MIT-licensed; 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 — 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 — see 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 — see below.
ROUTEBASE_URL No Overrides the target host. Defaults to https://mcp.routebase.dev; 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 — 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 — 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; 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 — see the MCP Quickstart.

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 asks four things, and three of them have the right default already: choose connection mode 1 (Remote), accept the offered host https://mcp.routebase.dev, pick your region (EU is the default), and confirm the detected IDE. 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 — 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 — ROUTEBASE_API_KEY is not set. Export it, or run routebase-mcp init to write a config that carries it.