MCP Reference

MCP Quickstart

Connect your AI agent to Routebase in a couple of minutes. The Routebase MCP (Model Context Protocol) server exposes your entire API lifecycle — designing specs, running tests, managing mock servers, authoring docs — as 401 tools across 31 toolsets that agents like Claude Code, Claude Desktop, Cursor, and VS Code can call directly. Alongside the tools sit 12 resources and 13 prompts — see Resources & Prompts.

Your client won't list all 401 — how many it lists depends on how you authenticate. A key with scopes sees every tool those scopes allow, and an OAuth sign-in sees every tool your organization role allows — both right from the first tools/list. Only a key without scopes starts lean: the five core toolsets (context, navigation, projects, API specs, endpoints — 48 tools), with the agent adding what it needs via list_toolsets and enable_toolset. Either way, hidden is not disabled — a tool can be called by name before its toolset is enabled. OAuth or a scoped key is the better setup for MCP connectors, which often never refresh their tool list mid-session.

How it connects

There are two ways to reach the server, and each client below uses whichever is cleanest for it:

  • Remote connector (Claude). Claude.ai, Claude Desktop, and the Claude mobile apps add the server as a custom connector and sign you in with your Routebase account (OAuth) — no API key, nothing to install. See the section below.
  • Remote HTTP. Claude Code, Cursor, and VS Code talk to the hosted Routebase endpoint directly over Streamable HTTP — nothing to install.
  • stdio bridge. The small routebase-mcp CLI runs locally and proxies every call to the API. It's the universal fallback for any stdio-only client, and it needs a single environment variable — see the MCP CLI Reference.

The HTTP and stdio paths authenticate with a Routebase API key; the Claude connector signs you in instead. See the MCP Authentication guide for how to create a key and which scopes to pick.

Endpoint

The hosted MCP server is reachable at:

https://mcp.routebase.dev

The older address https://api.routebase.dev/mcp points at the same server and keeps working — existing connectors need no change.

If your account lives in the US region, use https://mcp.routebase.dev/?region=us instead — see the Regions section below for why (getting this wrong shows up as a connector with no tools available, not as an error). EU accounts need nothing.

Start here: the card on your dashboard

Before wiring anything up by hand, look at your Routebase dashboard. The MCP connection card sits below the health widgets — and on the welcome screen of a brand-new workspace — with a tab per client, three numbered steps, and a copy button on every value you need.

It is not a shortcut around the instructions below; it is the same setup with your values already filled in. The URL it hands you already carries your organization's region, which removes the single most common setup mistake in this guide before you can make it, and the IDE tab creates an API key for you on the spot (or tells you to ask an org admin, if your role cannot).

Use the sections below when you want to understand what the card wrote, when you are configuring a client it has no tab for, or when you need a key with different scopes than the one it creates. Details of the card itself are in the Dashboard guide.

Prerequisites

  • A Routebase account with at least one project — the agent needs something to work on.
  • For Claude Code, Cursor, VS Code, and the stdio bridge: a Routebase API key with the scopes you need (specs:read is enough to explore). See MCP Authentication. The Claude connector needs none — you sign in instead.
  • For the stdio bridge: Node.js 18+ (to run npx routebase-mcp), or a global install (npm install -g routebase-mcp).

Claude: the remote connector

Claude.ai, Claude Desktop, and the Claude mobile apps connect through a custom connector. There is no config file and no API key — you authorize with your Routebase account, and the agent gets exactly your permissions (tool visibility follows your organization role):

  1. Copy the MCP URL: https://mcp.routebase.dev — US-region accounts use https://mcp.routebase.dev/?region=us (see Regions).
  2. Add it in Claude: Settings → Connectors → Add custom connector, then paste the URL.
  3. Sign in and go: a Routebase login window opens; authorize, and the tools appear in the connector.

Under the hood this is OAuth 2.1 with short-lived tokens — nothing lands on disk to rotate or leak (see MCP Authentication). The same connector works across Claude.ai, Desktop, and mobile once added.

The fast path for IDEs: the setup wizard

The CLI ships an interactive wizard that writes the right config for Claude Code or Cursor and prints the environment variables to export:

npx routebase-mcp@latest init

It asks for your API key, the connection mode (choose Remote), and your IDE, then writes mcp.json. Prefer to wire things up by hand? Use the per-client sections below.

Claude Code

Claude Code speaks remote HTTP natively — one command, no install:

claude mcp add --transport http routebase https://mcp.routebase.dev \
  --header "X-API-Key: <your-api-key>"

Start Claude Code and the routebase tools are available. (Prefer a checked-in config? Claude Code also reads a project .mcp.json with the mcpServers stdio shape shown in the Cursor section.)

Claude Desktop (stdio bridge)

For Claude Desktop the remote connector above is the simpler path — use the stdio bridge when you specifically want an API key's fixed scopes instead of your own account's permissions. Claude Desktop launches the bridge from its config: open Settings → Developer → Edit Config — the file lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) — and add:

{
  "mcpServers": {
    "routebase": {
      "command": "npx",
      "args": ["-y", "routebase-mcp@latest", "--stdio"],
      "env": {
        "ROUTEBASE_API_KEY": "<your-api-key>",
        "ROUTEBASE_URL": "https://mcp.routebase.dev"
      }
    }
  }
}

Then completely quit and reopen Claude Desktop. (Installed the CLI globally? Use "command": "routebase-mcp", "args": ["--stdio"].)

Cursor

Run routebase-mcp init --target cursor, or add this to .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all projects):

{
  "mcpServers": {
    "routebase": {
      "command": "routebase-mcp",
      "args": ["--stdio"],
      "env": {
        "ROUTEBASE_API_KEY": "${ROUTEBASE_API_KEY}",
        "ROUTEBASE_URL": "https://mcp.routebase.dev"
      }
    }
  }
}

Export your key (export ROUTEBASE_API_KEY=… in your shell profile) so the ${ROUTEBASE_API_KEY} reference resolves — keeping it out of the committed file (see MCP Authentication). Cursor can also connect over HTTP directly: drop command/args and use "url": "https://mcp.routebase.dev" with "headers": { "X-API-Key": "<your-api-key>" }.

VS Code

VS Code reaches the hosted endpoint over HTTP. Create .vscode/mcp.json — note the top-level key is servers (not mcpServers):

{
  "servers": {
    "routebase": {
      "type": "http",
      "url": "https://mcp.routebase.dev",
      "headers": { "X-API-Key": "${input:routebase-api-key}" }
    }
  },
  "inputs": [
    {
      "id": "routebase-api-key",
      "type": "promptString",
      "description": "Routebase API key",
      "password": true
    }
  ]
}

VS Code prompts for the key on first connect and stores it securely. Start the server from the Start lens above the mcp.json entry, or via the MCP: List Servers command.

Regions

Routebase serves the EU and US regions behind the same addresses and picks your region from a signal the client sends. Which signal you can send depends on the client:

  • Claude connector: the URL query — US accounts add the connector as https://mcp.routebase.dev/?region=us. A hosted connector can send neither a cookie nor a custom header, so the query string is the only signal available to it.
  • IDE clients and the stdio bridge: the ROUTEBASE_REGION environment variable (us or eu; default eu) — the CLI sends it as the X-RB-Region header. US accounts add "ROUTEBASE_REGION": "us" to the env block of the configs above, or export it in the shell. Details in the MCP CLI Reference.

Getting the region wrong produces two different symptoms, neither of which mentions regions:

  • A connector lands in the EU region, where your US account does not exist — it connects successfully but shows no tools available.
  • An API key is rejected as if it were invalid: keys are stored per region, so the EU side simply does not know your US key.

EU accounts need no setting anywhere — eu is the default.

Your first tool call

Routebase tools operate inside a working context — an organization and usually a project — so the agent establishes that first. A plain-English ask is enough; the agent chains the right tools:

"List my Routebase organizations, set context to Acme and the Billing API project, then list the specs."

Under the hood that is list_organizations → set_context → list_projects → set_context (now with the project) → list_specs. set_context takes the organization and project public IDs (GUIDs); list_organizations and list_projects return them, so you rarely type a GUID yourself.

From there the agent can read endpoints, draft schemas, generate tests, manage mock rules, and author docs. Every tool is catalogued in the MCP Tool Reference — one page per toolset, generated from the server itself. Tools are not the whole surface: see Resources & Prompts for the read-only context URIs and the guided workflows.

Sessions

The connection is stateful, and two things live in the session rather than in your config:

  • your working context — the organization and project you set with set_context, and
  • which toolsets are enabled — see the next section.

A session that sits unused for one hour is discarded, and every reconnect starts a fresh one — so a client restart or a dropped connection has the same effect. The new session has no context, and is back to the core tools. That is the whole explanation behind the most common confusion with this server — "the tools I enabled yesterday are gone" and "it says no project is selected, I definitely set one". Nothing was lost or revoked; you are simply in a different session. Ask the agent to set the context again, and re-enable the toolsets you need.

Two things make this smaller than it sounds. Setting context is a plain-English sentence, not a lookup — the agent chains list_organizations → set_context for you. And if you authenticate with a scoped key or via OAuth, tool visibility does not depend on the session at all: your entitled tools are advertised from the first tools/list every time, so only the context needs re-establishing.

What a session has cost so far

get_session_usage reports on the current session: total tool calls, how many of them errored, aggregate duration, total response bytes, a per-tool call count, and when the session started and was last used. Useful when an agent run feels slow or expensive, and for finding the one tool it called forty times.

One caveat it states in its own response: totalResponseBytes is payload size, not LLM token usage. This server never invokes a model, so it cannot report tokens — the number is a proxy for how much text your agent had to read, nothing more. The metrics are in memory and reset with the session.

Toolsets

The 401 tools are grouped into 31 toolsets. Five of them are core and always visible — 48 tools covering context, navigation, projects, API specs and endpoints. That is the starting point for a key without scopes; a scoped key or an OAuth sign-in skips the whole mechanism and sees everything it is entitled to immediately (see MCP Authentication).

Two tools manage the rest:

  • list_toolsets — all 31 with their descriptions and whether they are currently enabled.
  • enable_toolset — takes a comma-separated list of slugs, e.g. testing,mock-server. Pass an unknown slug and the error lists every valid one, so the agent can correct itself without a round trip.

Hidden is not disabled. A tool in a toolset you have not enabled can still be called directly by name and will execute normally, subject to the same permission checks as any other call. Enabling a toolset only makes it advertised — which matters because many agents will not reach for a tool they cannot see.

The slugs, since they appear in every error message:

Slug Toolset Covers
api-specs (core) API Specifications Create, read, update and delete API specifications.
context (core) Context & Session Session context, organizations, projects and toolset management.
endpoints (core) Endpoints Endpoints with parameters, request bodies, responses and security.
navigation (core) Navigation & Search Project dashboard and cross-entity search.
projects (core) Projects & Environments Projects and their environments.
api-design-insight Promotions, Sync & Audit Promotion history, artifact sync reviews and the audit log of a spec.
auth Auth Configuration Auth configurations for test environments (org defaults and per-environment).
billing Plan & Usage (read-only) Read-only plan, usage limits, credit balance and trial status.
branches Branches & Merge Requests Spec branches, clones and merge requests.
components Reusable Components Reusable parameter, response and security-scheme components.
deprecation Deprecation Deprecation lifecycle for endpoints, schemas and versions.
documentation Documentation Doc hub pages, tree, versions, snapshots and snippets.
folders Folders Folders that organize endpoints within a spec.
governance Governance Spec validation, score weights, custom rules and severities.
header-components Header Components Reusable header components on org, project and spec level.
header-policies Header Policies Header policies on org, project and spec level.
identity Organization & Access (read-only) Read-only members, teams, custom roles and effective permissions.
mock-server Mock Server Mock server rules, responses, smart matching and org defaults.
monitoring Monitoring Monitors, checks, alert policies, incidents and maintenance windows.
notifications Notifications & Webhooks Notifications, notification preferences and webhooks.
portal-admin Portal Administration Portal branding, custom domains and build management.
portal-docs Portal Docs Search Search across published portal docs.
request-body-components Request Body Components Reusable request body components.
schemas Schemas Schemas within a spec.
security Security Security scans, findings, scan profiles and personas.
shared-library Shared Library Shared schema library on project and org level.
style-guide Style Guide & Governance Style guide rules and naming conventions.
tags Tags Endpoint tags: create, assign, reorder and bulk update.
testing Testing Test suites, cases, runs, fixtures, seeds, snapshots and schedules.
variables Variables Org and project variables (secret values are never readable).
versions Versions Spec versions: lifecycle, publishing, promotion and environment pins.

Recipe: testing against a token-protected mock server

When a mock server has requireToken enabled, its access token is a secret: get_mock_server never returns it, and there is no read tool for it. The only MCP path to a usable token is regenerate_mock_server_token — which issues a fresh token and invalidates the old one immediately, so every client still sending the old token starts failing. Rotate deliberately, then store the new token once instead of asking for it again:

  1. Rotate: call regenerate_mock_server_token. The response contains the new token — this is the only moment it is readable.
  2. Store as a secret variable: call set_environment_variables and save it as e.g. { "key": "mockToken", "value": "<token>", "isSecret": true } in the environment your tests run against. (Mind the tool's full-replace semantics — send the complete variable set.)
  3. Reference, never paste: in test case headers use Authorization: Bearer {{mockToken}}. The test runner substitutes the secret at execution time; the token never appears in test definitions, tool responses, or chat transcripts again.

Troubleshooting

  • The connector connects, but shows no tools. Almost always the region: a US account added without ?region=us lands in the EU region, where the account does not exist — the handshake succeeds, the toolbox is empty. Remove the connector and re-add it with https://mcp.routebase.dev/?region=us. See Regions.
  • A key you just created is rejected as invalid. Same root cause for IDE clients: API keys exist per region, so a US key sent without ROUTEBASE_REGION=us reaches the EU region and fails as an unknown key — the error says "invalid API key", not "wrong region". Set the variable and restart the client. See Regions.
  • ROUTEBASE_API_KEY environment variable is required (exit 2). The key isn't reaching the server. Check the env/headers block in your config and restart the client.
  • The tools I enabled are gone, and it says no project is selected. You are in a new session — reconnecting starts one, and an hour of inactivity discards the old one. Context and enabled toolsets live in the session, so both need setting again; ask the agent to set the context and re-enable the toolsets. See Sessions. A scoped key or an OAuth sign-in avoids half of this: those see their full tool surface on every connect, so only the context has to be re-established.
  • A tool you expect is missing. Two possible reasons: (1) your key has no scopes and its toolset isn't enabled yet — most toolsets start hidden then; call list_toolsets to see them and enable_toolset to add them (hidden tools can still be called directly by name). If your client doesn't refresh its tool list mid-session — many connectors don't — give the key explicit scopes instead: scoped keys see every entitled tool from the start. (2) tools/list only advertises tools your key's scopes allow — a read-only key won't show write tools; widen the scopes (see MCP Authentication).
  • Forbidden: … required scope … on a call. The key is valid but lacks the scope for that specific tool.
  • Where are my org / project IDs? You rarely need the raw GUIDs — the agent discovers them via list_organizations and list_projects.