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 as tools grouped into toolsets. Agents like Claude Code, Claude Desktop, Cursor, VS Code and Codex call them directly to design specs, run tests, manage mock servers and author docs. Alongside the tools sit 12 resources and 13 prompts, which are covered in Resources & Prompts.

Your client will not list every tool, and how many it lists depends on how you authenticate. A key without scopes is full access and sees every tool right from the first tools/list. A key with scopes sees every tool those scopes allow, and an OAuth sign-in sees every tool your organization role allows, again from the first list. The lean start with the five core toolsets covering context, navigation, projects, API specs and endpoints applies only to a session that has not authenticated yet. Such a session adds what it needs via list_toolsets and enable_toolset. Either way, hidden is not disabled, because a tool can be called by name before its toolset is enabled. If you want a lean list for an agent, give the key scopes, because scopes decide both what the agent may do and what it sees.

How it connects

There are three 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. They sign you in with your Routebase account over OAuth, so there is no API key and nothing to install. See the section below.
Remote HTTP. Claude Code, Cursor, VS Code, and Codex talk to the hosted Routebase endpoint directly over Streamable HTTP, with nothing to install.
stdio bridge. The small routebase-mcp CLI runs locally and proxies every call to the API. It is the universal fallback for any stdio-only client, and it needs a single environment variable, which the MCP CLI Reference describes.

The HTTP and stdio paths authenticate with a Routebase API key, while 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, so existing connectors need no change.

If your account lives in the US region, use https://mcp.routebase.dev/?region=us instead. The Regions section below explains why, and getting this wrong shows up as a connector with no tools available rather than 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 it also appears on the welcome screen of a brand-new workspace. It gives you 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, because 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 most common setup mistake in this guide before you can make it. The IDE tab also creates an API key for you on the spot, or tells you to ask an org admin if your role cannot.

The MCP connection card on the dashboard with the Claude Code tab, its three setup steps and the config block

Use the sections below in three cases. You want to understand what the card wrote, you are configuring a client it has no tab for, or 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, because the agent needs something to work on.
Claude Code, Cursor, VS Code and the stdio bridge each need a Routebase API key with the scopes you want, and specs:read is enough to explore. See MCP Authentication. The Claude connector needs no key, because you sign in instead.
The stdio bridge needs Node.js 18+ to run npx routebase-mcp, or a global install with 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, because you authorize with your Routebase account. The agent then gets exactly your permissions, and tool visibility follows your organization role.

Copy the MCP URL https://mcp.routebase.dev. US-region accounts use https://mcp.routebase.dev/?region=us instead, as described under Regions.
In Claude, open Settings → Connectors → Add custom connector and paste the URL.
Authorize in the Routebase login window that opens. The tools then appear in the connector.

Under the hood this is OAuth 2.1 with short-lived tokens, so nothing lands on disk to rotate or leak. See MCP Authentication for the details. Once added, the same connector works across Claude.ai, Desktop and mobile.

The fast path for IDEs: the setup wizard

The CLI ships an interactive wizard that writes the right config for Claude Code, Cursor or VS Code, each in the shape that client actually reads. It also prints the environment variables to export:

npx routebase-mcp@latest init

It asks for your API key, the connection mode and your IDE, then writes mcp.json. Choose Remote as the connection mode. For VS Code it writes the HTTP form shown below and declares the key as an input variable, so you paste the key into VS Code's prompt rather than into the file. To wire things up by hand, use the per-client sections below.

Claude Code

Claude Code speaks remote HTTP natively, so one command is enough and nothing gets installed:

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. For 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, which you open with Settings → Developer → Edit Config. The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and at %APPDATA%\Claude\claude_desktop_config.json on Windows. Add this block:

{
  "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. If you installed the CLI globally, use "command": "routebase-mcp" with "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 with export ROUTEBASE_API_KEY=… in your shell profile so the ${ROUTEBASE_API_KEY} reference resolves, which keeps the key out of the committed file. See MCP Authentication for more on that. Cursor can also connect over HTTP directly, so drop command and 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, so there is no bridge and no Node install. Create .vscode/mcp.json. Three details are load-bearing and fail quietly if you get them wrong:

The top-level key is servers. A block under mcpServers parses fine and is never read.
type is required on every entry.
Only ${input:…} is expanded. A bare ${ROUTEBASE_API_KEY} reaches the server as that literal string.

{
  "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.

Codex

Codex reads its MCP servers from ~/.codex/config.toml, which is the same file for the CLI and the IDE extension. Both connection paths work, and the remote one needs nothing installed.

Remote HTTP. Add the hosted endpoint as a Streamable HTTP server:

[mcp_servers.routebase]
url = "https://mcp.routebase.dev"
env_http_headers = { "X-API-Key" = "ROUTEBASE_API_KEY" }

env_http_headers maps a header name to the name of an environment variable, not to a value. Export your key with export ROUTEBASE_API_KEY=… in your shell profile, and it never lands in the config file. Codex also offers bearer_token_env_var, which sends the value as Authorization: Bearer …. Routebase API keys are only accepted on the X-API-Key header, so use the form above.

US-region accounts use url = "https://mcp.routebase.dev/?region=us". Like VS Code, this path has no bridge to carry ROUTEBASE_REGION, so the region rides in the URL. See Regions.

stdio bridge. Use the same file with the command shape instead:

[mcp_servers.routebase]
command = "npx"
args = ["-y", "routebase-mcp@latest", "--stdio"]

[mcp_servers.routebase.env]
ROUTEBASE_API_KEY = "<your-api-key>"
ROUTEBASE_URL = "https://mcp.routebase.dev"

US accounts add ROUTEBASE_REGION = "us" to that env table. Or register the same thing from the command line:

codex mcp add routebase \
  --env ROUTEBASE_API_KEY=<your-api-key> \
  --env ROUTEBASE_URL=https://mcp.routebase.dev \
  -- npx -y routebase-mcp@latest --stdio

codex mcp list shows what is registered.

IDE extension. Open the gear menu → MCP servers → Add server and enter the name routebase. Choose STDIO or Streamable HTTP, then give it the command or the URL above. Finish with Save and Restart extension.

The routebase-mcp init wizard writes config for Claude Code, Cursor and VS Code only, so use the TOML above for Codex.

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 signal is the URL query, so US accounts add the connector as https://mcp.routebase.dev/?region=us. A hosted connector can send neither a cookie nor a custom header, which leaves the query string as its only signal.
IDE clients and the stdio bridge. The signal is the ROUTEBASE_REGION environment variable, which takes us or eu and defaults to 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 are in the MCP CLI Reference.
VS Code. The signal is the URL query, like the connector, because no stdio bridge sits in the way to carry an environment variable. US accounts use "url": "https://mcp.routebase.dev/?region=us".

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, so it connects successfully but shows no tools available.
An API key is rejected as if it were invalid, because keys are stored per region and the EU side does not know your US key.

EU accounts need no setting anywhere, because eu is the default.

Your first tool call

Routebase tools operate inside a working context, which is an organization and usually a project, so the agent establishes that first. A plain-English ask is enough, and 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), and 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, which has one page per toolset and is generated from the server itself. Tools are not the whole surface, so 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, which is the organization and project you set with set_context.
Which toolsets are enabled, as described in 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 explains the most common confusion with this server, which sounds like "the tools I enabled yesterday are gone" or "it says no project is selected, I definitely set one". Nothing was lost or revoked, because you are 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 rather than a lookup, because 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 and how many of them errored.
Aggregate duration and total response bytes.
A per-tool call count.
When the session started and when it was last used.

The report helps when an agent run feels slow or expensive, and it finds the one tool an agent called forty times.

The response states one caveat itself. totalResponseBytes is payload size, not LLM token usage. This server never invokes a model, so it cannot report tokens, and the number is only a proxy for how much text your agent had to read. The metrics live in memory and reset with the session.

Toolsets

The tools are grouped into 31 toolsets. Five of them are core and always visible, covering context, navigation, projects, API specs and endpoints. That is the starting point for a session that has not authenticated yet. A key without scopes sees everything immediately, and a scoped key or an OAuth sign-in sees everything it is entitled to immediately, as described under MCP Authentication.

Two tools manage the rest:

list_toolsets returns all 31 with their descriptions and whether they are currently enabled.
enable_toolset takes a comma-separated list of slugs, such as 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 stays 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.

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

Troubleshooting

The connector connects, but shows no tools. This is almost always the region. A US account added without ?region=us lands in the EU region, where the account does not exist, so the handshake succeeds and the toolbox stays 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. IDE clients hit the same root cause. 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" rather than "wrong region". Set the variable and restart the client. See Regions.
ROUTEBASE_API_KEY environment variable is required (exit 2). The key is not reaching the server. Check the env or 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, because 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, as described under Sessions. A scoped key or an OAuth sign-in avoids half of this, because those see their full tool surface on every connect and only the context has to be re-established.
A tool you expect is missing. There are two possible reasons. First, your key may have no scopes while its toolset is not enabled yet, because most toolsets start hidden in that case. Call list_toolsets to see them and enable_toolset to add them, and remember that hidden tools can still be called directly by name. If your client does not refresh its tool list mid-session, which many connectors do not, give the key explicit scopes instead, because scoped keys see every entitled tool from the start. Second, tools/list only advertises tools your key's scopes allow, so a read-only key shows no write tools. Widen the scopes, as described under 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, because the agent discovers them via list_organizations and list_projects.

MCP Authentication — API keys, all 30 scopes, OAuth, what an agent cannot do, rate limits
Resources & Prompts — the 12 read-only context URIs and the 13 guided workflows
MCP CLI Reference — the stdio bridge, its environment variables, and what npx routebase-mcp downloads
MCP Tool Reference — every tool, one page per toolset