Source and self-hosting

The Toado MCP server is open source under the MIT licence at github.com/toado-dev/toado-mcp and published on npm as @toado/mcp. It can connect to the Toado API from your own MCP process. A published package, public checkout, and hosted server can be on different versions; inspect the tools exposed by the server you installed. The current reference records 34 tools from the reviewed 0.2.0 source.

The open-source release is the whole server, the HTTP transport the hosted endpoint runs included: one repo, one package, with no hosted-only code held back. The backend (API and web app) and the Chrome extension are not open source. A server you run from source still talks to a Toado backend: the hosted one by default, or a staging or self-hosted deployment you have access to.

What is in the repo

Path	What it is
src/tools.ts	Tool definitions: name, description, zod input schema, required scope, handler. The source of truth for the Tools reference.
src/server.ts	Builds a per-request MCP Server, runs the scope check, maps API errors to MCP errors.
src/index.ts	The HTTP entry point: Fastify, CORS, the per-IP rate limit, the RFC 9728 metadata endpoints, the /mcp route.
src/auth.ts	Bearer extraction and validation against /auth/token-info, with a 60-second scope cache.
src/scope.ts	Scope labels and the consent-screen presets (Read-only, Read + comment, Full access).
src/etagCache.ts	The bounded ETag cache behind get_ticket.
src/client.ts	The thin REST client, including conditional GET.
test/	Unit tests. pnpm test runs them with a stubbed API client; no services needed.
scripts/	The smoke test against a live API and the tools-reference generator.
Dockerfile	Image for the HTTP mode.

Build

git clone https://github.com/toado-dev/toado-mcp.git
cd toado-mcp
pnpm install
pnpm build
pnpm test

pnpm build compiles TypeScript to dist/. Node 20 or newer and pnpm 9 are required. pnpm dev watches and restarts on change.

Environment variables

Variable	Required	Default	Notes
VD_API_BASE_URL	yes	http://localhost:3001/api/v1	API base, including the version prefix. Point this at production, staging, or a self-hosted backend.
VD_API_PUBLIC_URL	no	origin of VD_API_BASE_URL	Externally reachable API origin, advertised to clients as the authorization server. Set it when the API base is an internal hostname such as a Docker service name.
PORT	no	3002	Listen port.
TRUST_PROXY	production		1 behind a proxy, 0 without. The server refuses to start in production without it, so the rate limit keys on the real client IP rather than the proxy’s.
MCP_CORS_ORIGINS	no	local dev origins	Comma-separated browser origins allowed to call /mcp directly. Native clients such as Claude Code and Claude Desktop do not need CORS.
LOG_LEVEL	no	info	All logs go to stderr.

These names are settled

These are the names the server reads, in the repo and in the published @toado/mcp package. There is no TOADO_ prefix. The repo’s README ships with the code and matches this table.

How it runs

The server is HTTP only, and stateless. There is no stdio mode; it was removed when the server moved to per-request authentication.

One process listens on /mcp. Every inbound request carries its own Authorization: Bearer header, which the server validates against the API’s /auth/token-info endpoint to resolve the token’s scopes, then builds a per-request MCP server with that context baked into the tool handlers. Nothing is held between requests, so you can run several instances behind a load balancer without sticky routing, and no API token is ever stored in the server’s environment.

To run it yourself:

VD_API_BASE_URL=https://app.toado.dev/api/v1 \
VD_API_PUBLIC_URL=https://app.toado.dev \
TRUST_PROXY=1 PORT=3002 \
node dist/index.js

Then register https://your-host/mcp in your client exactly as you would the hosted endpoint. You get the same OAuth discovery, the same /.well-known/oauth-protected-resource metadata, the same per-IP rate limit, and the /health and /ready probes.

Pointing at staging or a self-hosted API

Change VD_API_BASE_URL. The path must include /api/v1:

VD_API_BASE_URL=https://toado.staging.example.com/api/v1

The authorization server your client discovers belongs to whichever backend the MCP server points at, so the consent screen and the tokens both come from there. A production token is not valid against staging.

Also set VD_API_PUBLIC_URL when the API base is only reachable inside your network. That value is what clients are told to use as the authorization server, so it has to resolve from their side, not the server’s.

How the tools reference is generated

The current reference is exported from the reviewed Toado application checkout’s apps/mcp/src/tools.ts. From this knowledgebase checkout, run:

node scripts/sync-mcp-tools.mjs ../visual-debugger

The script records the source revision, exports input schemas and required scopes, preserves transport notes, and combines those definitions with curated return summaries. The docs render src/data/mcp-tools.json directly on the Tools reference. Review generated changes against the source before publishing. The public MCP repository also has its own generator; its output describes that checkout’s version.

Release cadence

Check the installed package version and the tools exposed by your connected server when comparing them with this reference. A public checkout, npm release, and hosted endpoint may differ. If you run from source, review the changelog and the repository’s release notes before updating.

Where to next

• Contributing for issues, PRs and adding a tool.
• Installation for the per-client steps, including the Run from source tab.
• Tokens & scopes for what each scope grants a caller.
• Security for what is public and what stays closed.