# routebase-mcp

**Let your AI agent work on your APIs in Routebase.** This is the connector for [Routebase](https://routebase.dev), an API lifecycle platform where documentation, mock servers, contract tests and monitoring are all derived from one OpenAPI spec. Agents work on that same spec, so they design endpoints and schemas, run contract and security test suites, manage mocks, publish docs and read monitors under the same role-based permissions as the human team. Billing and organization access stay read-only.

There are two ways to connect. Pick the hosted endpoint unless your client only speaks stdio.

## Hosted endpoint (recommended)

```
https://mcp.routebase.dev
```

Streamable HTTP, with OAuth 2.1 and dynamic client registration — you sign in with your Routebase account, nothing to install and no key to rotate. Clients that prefer a static credential can send an `X-API-Key` header instead.

**US-region accounts** use `https://mcp.routebase.dev/?region=us`. Getting this wrong shows up as a connector with no tools, not as an error.

## stdio bridge

For clients that only launch local processes:

```bash
ROUTEBASE_API_KEY=rb_… npx routebase-mcp
```

Generate an API key in Routebase under **Settings → API Keys**. The interactive setup writes the right config for you:

```bash
npx routebase-mcp init
```

Or add it by hand. Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`) take the same block:

```json
{
  "mcpServers": {
    "routebase": {
      "command": "npx",
      "args": ["-y", "routebase-mcp", "--stdio"],
      "env": {
        "ROUTEBASE_API_KEY": "rb_…"
      }
    }
  }
}
```

**Codex** reads `~/.codex/config.toml`, the same file for the CLI and the IDE extension:

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

[mcp_servers.routebase.env]
ROUTEBASE_API_KEY = "rb_…"
```

**VS Code** does not need the bridge, because it speaks Streamable HTTP itself. Its `.vscode/mcp.json` reads the top-level key `servers` rather than `mcpServers`, requires `type` on every entry, and expands only `${input:…}`, so the key stays out of the committed file. See the [MCP quickstart](https://docs.routebase.dev/mcp-quickstart/) for the full block.

| Environment variable | Required | Description |
| --- | --- | --- |
| `ROUTEBASE_API_KEY` | ✅ | API key for authentication. Create one under **Settings → API Keys**. |
| `ROUTEBASE_REGION` | US accounts | Home region of your account: `us` or `eu` (default: `eu`). Without it, a US key fails as if it were invalid. |
| `ROUTEBASE_LOG_LEVEL` | – | `verbose` · `debug` · `info` · `warning` · `error` · `fatal` (default: `warning`). Logs go to stderr — stdout is reserved for the MCP protocol. |

## How the stdio bridge works

The npm package is a small shim. On first run it downloads the self-contained CLI binary for your platform from `releases.routebase.dev`, **verifies it against a SHA-256 checksum baked into the package at publish time** (it refuses to run on mismatch — fail-closed), and caches it under `~/.routebase/bin/<version>/`.

**Supported platforms:** macOS (arm64, x64), Windows (x64), Linux (x64). Requires Node.js ≥ 18.

## What's in this repository

| File | Purpose |
| --- | --- |
| `bin/routebase-mcp.js` | The stdio shim published as the [`routebase-mcp`](https://www.npmjs.com/package/routebase-mcp) npm package |
| `server.json` | Manifest for the [MCP Registry](https://registry.modelcontextprotocol.io) (`dev.routebase/routebase`) |
| `plugin.json`, `mcp.json` | [Agent Plugins 1.0](https://github.com/agentplugins/agent-plugins-spec) manifests |
| `package.json`, `checksums.json` | The published package metadata and the SHA-256 checksums of the binaries this version is pinned to |

> This repository **mirrors** the connector as published, and every file in it is written by the release pipeline in Routebase's own repository. Each release pushes the exact contents of the npm package here and tags it, so changes made here won't reach npm — please open an issue instead of a pull request.

## Links

- Product: <https://routebase.dev/mcp-server/>
- MCP quickstart for every client: <https://docs.routebase.dev/mcp-quickstart/>
- API keys and scopes: <https://docs.routebase.dev/mcp-authentication/>
- CLI reference: <https://docs.routebase.dev/mcp-cli-reference/>
- npm: <https://www.npmjs.com/package/routebase-mcp>

## License

The shim in this repository is [MIT](LICENSE). The downloaded Routebase CLI binary is governed by the [Routebase Terms](https://routebase.dev/terms).