scalepad-mcp

MCP server for the ScalePad platform — Core, Lifecycle Manager, ControlMap, Backup Radar, and Quoter — built natively on the MCP SDK v2 (2026-07-28 spec) with dual-era serving: the same endpoint answers both legacy 2025-era initialize-handshake clients and modern envelope clients.

Architecture

Flat tool surface: every tool is exposed upfront in tools/list for universal client compatibility. Navigation tools are discovery aids, not gates.

Tool	Purpose
`scalepad_navigate`	Describe a product domain's tools (`core`, `lifecycle-manager`, `controlmap`, `backup-radar`, `quoter`) — a help/discovery aid, not a prerequisite
`scalepad_status`	Show credential status and available domains

Product domains

Domain	Tool prefix	Coverage
`core`	`scalepad_core_`	Unified platform data (read-only, US-only): clients, contacts, members, sites, opportunities, hardware/SaaS assets, product catalog, service contracts, tickets, integrations
`lifecycle-manager`	`scalepad_lm_`	Engagement/roadmap workflows: initiatives, goals, meetings, action items, assessments, deliverables, budgets, contracts, workspace
`controlmap`	`scalepad_cm_`	Compliance per client: risks, controls, evidence, policies, frameworks, assessments, action items (regions: us, eu, ca, au)
`backup-radar`	`scalepad_br_`	Read-only backup health and backup device inventory (regions: us, eu)
`quoter`	`scalepad_quoter_`	Quotes, catalog, contacts, suppliers, and standalone-OAuth helpers (defaults to the ScalePad-hosted Quoter API)

All tools are callable at any time; scalepad_navigate simply summarizes a domain's tools.

Credentials

One ScalePad API key (generated in the ScalePad app by an Administrator) covers every product; endpoints for products without an active subscription return 402.

Environment variables (`AUTH_MODE=env`, default for stdio/local)

Variable	Required	Notes
`SCALEPAD_API_KEY`	yes	Forwarded to `api.scalepad.com` as `x-api-key`
`SCALEPAD_REGION`	no	`us` (default), `eu`, `ca`, or `au` — selects the regional base URL for ControlMap (us/eu/ca/au) and Backup Radar (us/eu); Core and Lifecycle Manager are US-only
`QUOTER_CLIENT_ID`	no	Only for the standalone `api.quoter.com` OAuth path (Quoter Account > API Keys, Account Owner only)
`QUOTER_CLIENT_SECRET`	no	Paired with `QUOTER_CLIENT_ID`

Gateway headers (`AUTH_MODE=gateway`, hosted deployment)

Header	Required
`X-ScalePad-Api-Key`	yes
`X-ScalePad-Region`	no
`X-Quoter-Client-Id`	no
`X-Quoter-Client-Secret`	no

In gateway mode credentials are bound per request from these headers; requests to /mcp without X-ScalePad-Api-Key are rejected with a 401 JSON-RPC error before any MCP handling (they never fall through to env credentials). /health stays unauthenticated.

Transports

stdio (default): node dist/index.js — for Claude Desktop / CLI.
HTTP: MCP_TRANSPORT=http node dist/index.js — serves /mcp (dual-era, legacy: 'stateless') plus /health. Configure with MCP_HTTP_PORT (default 8080) and MCP_HTTP_HOST (default 0.0.0.0).

Development

server.ts

export NODE_AUTH_TOKEN=$(gh auth token)   # GitHub Packages read access
npm ci
npm run build       # tsup (transpile-only; domains stay lazily importable)
npm test            # vitest (HTTP layer: health, 401 gate, dual-era tools/list)
npm run smoke       # dual-era smoke against dist/index.js
npm run typecheck

Domain handlers live in src/domains/<slug>.ts, each exporting export const handler: DomainHandler (see src/utils/types.ts), and are lazily loaded via src/domains/index.ts.

Docker

Terminal

docker build --build-arg NODE_AUTH_TOKEN=$(gh auth token) -t scalepad-mcp .
docker run -p 8080:8080 -e AUTH_MODE=env -e SCALEPAD_API_KEY=... scalepad-mcp

The image defaults to AUTH_MODE=gateway for hosted deployment behind the WYRE MCP gateway.

License

Apache-2.0 — see LICENSE.