Dashboard MCP Server and CLI

Model Context Protocol (MCP) server and human-first CLI for the CallTelemetry Dashboard CRM API. Both surfaces derive from the same OpenAPI contract, auth flow, and request runtime.

Features

• Auto-generated tools — MCP tools from the validated dashboard OpenAPI 3.0 spec (the exact count follows the live contract)
• Human-first CLI — dashboard-cli provides readable CRM commands plus generic operation fallback
• Strong typing — TypeScript interfaces generated by openapi-typescript
• API-key auth — Scoped ctk_... bearer key (DASHBOARD_API_KEY); no email/password
• Live spec refresh — Fetches latest API spec on startup, falls back to bundled
• Safe by default — Excludes DELETE, email sending, imports, and other destructive operations
• Custom workflows — Submission download preview/apply, guarded license renewal/extension, atomic contact reconciliation, and authorized internal demo issuance

Installation

Global (all Claude Code projects)

claude mcp add --scope user --transport stdio dashboard \
  --env DASHBOARD_URL=https://dash.calltelemetry.com \
  --env DASHBOARD_API_KEY="$DASHBOARD_API_KEY" \
  -- npx -y @calltelemetry/dashboard-mcp@latest

Project-level

Add to your project's mcp.json:

{
  "mcpServers": {
    "dashboard": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/dashboard-mcp@latest"],
      "env": {
        "DASHBOARD_URL": "https://dash.calltelemetry.com",
        "DASHBOARD_API_KEY": "${DASHBOARD_API_KEY}",
        "DASHBOARD_ALLOW_DESTRUCTIVE": "false"
      }
    }
  }
}

Setup

git clone [email protected]:calltelemetry/dashboard-mcp.git
cd dashboard-mcp
yarn install
yarn build    # Fetches spec → generates types → compiles

CLI Usage

Use dashboard-cli when you want readable terminal output. Use dashboard-mcp when an agent needs MCP tools.

# Default npx bin is the MCP server. Pass `--` to run the CLI.
doppler run --project ai-workspace --config prd -- \
  npx -y -p @calltelemetry/dashboard-mcp@latest -- dashboard-cli contacts list
dashboard-cli contacts show 43
dashboard-cli contact-reconcile preview --primary-contact-id 100 --duplicate-contact-id 101
dashboard-cli companies create --json '{"name":"SPIE","domain":"spie.com"}'
dashboard-cli licenses create --json '{"subscription_type":"demo","duration_days":45}'

# Authorized internal organization/contact/demo-license workflow; never sends email
dashboard-cli demo-license issue \
  --email [email protected] \
  --org-name "Internal testing" \
  --days 45 --internal --audit-note "Approved internal test"

# Generic fallback commands
dashboard-cli ops list --search license
dashboard-cli ops schema dash_api_web_crm_license_controller_create
dashboard-cli ops call dash_api_web_crm_contact_controller_index --arg search=sofiane

# Machine-readable output
dashboard-cli contacts list --json
dashboard-cli ops call dash_api_web_crm_contact_controller_index --json-output

Default output is pretty text on a TTY. Pass --json or --json-output, or pipe stdout, to switch to JSON.

Held download approvals

Agents discover the three workflow tools through the deployed ct-mcp gateway: dashboard_download_queue, dashboard_download_dossier, and dashboard_download_approve. Queue accepts submission_id, exact email, cursor, and limit (1–100). Dossier takes submission_id. Approve takes submission_id, reason, optional mode (preview default), and confirmation_digest (required for apply).

The CLI calls the same workflow, API, auth, and redaction boundary:

dashboard-cli downloads list --email [email protected] --limit 20 --json-output
dashboard-cli downloads dossier 23 --json-output
dashboard-cli downloads approve preview 23 --reason "Operator reviewed" --json-output
dashboard-cli downloads approve apply 23 --reason "Operator reviewed" --confirm <preview_digest> --json-output

IDs above are submission IDs. The old numeric downloads approve <run_id> and download_approve tool retain their run-addressed compatibility behavior. Preview declares normal link email delivery and returns a digest without changing state. Download approval does not issue or renew a demo license. Prospect demo-key approval stays a separate human CRM action.

Apply returns status: verified only after independent dossier and exact filtered queue reads agree. status: applied_unverified retains the committed receipt and returns MCP isError: true / CLI exit 1. Recover with read-only dossier/queue calls using the receipt IDs; do not blindly reapply. Notification queued does not mean sent or delivered. Replays preserve expired/revoked access. If current access state, expiry or quota has changed since apply, the original receipt and current dossier are retained with verification.access_drift_fields; the old receipt cannot certify current access.

License validity

customer-renewal preview includes the license validityStartsAt in its confirmation digest. It uses a past linked contract start date when available; otherwise it uses midnight UTC one calendar year before the current UTC date, clamping leap days to the last valid day of February. Apply sends this starts_at together with the requested expires_at. The contract start date is left intact.

license-extend uses the unique usable past start among contracts linked to that license, or the same calendar-year fallback when no unique start exists. If the database expiration already matches but the stored key has missing, malformed, or stale nbf / business-expiration claims, preview identifies a validity-key repair and apply re-signs the same expiration. Customer notifications remain off unless explicitly requested.

Internal demo-license issue uses the same backdated start while sending an explicit future business expiration based on the requested duration. Reused active demo licenses are checked and re-signed at their existing expiration when their key validity claims are stale.

Successful key results include the decoded UTC nbf and business expiration. They include JWT exp separately when it differs from the business expiration. Apply verifies the returned key claims against the requested start and expiration plus the independent license read-back; it does not sign keys locally.

HTTP 409/422, transport/domain failures, missing spec, and unknown operations are real typed MCP errors. Text JSON and structuredContent share redaction of tokens, signed URLs, license/API keys and email bodies. The new workflow refuses a contract without the required operation IDs, fields and scope declarations.

Environment Variables

Do not set DASHBOARD_EMAIL or DASHBOARD_PASSWORD. Catalog launchers unset them.

export DASHBOARD_API_KEY="$(doppler secrets get DASHBOARD_API_KEY --project ai-workspace --config prd --plain)"

How It Works

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  Claude Code │────▶│  dashboard-mcp  │────▶│  Dashboard API   │
│  (agent)     │◀────│  (MCP server)   │◀────│  (Phoenix/Pow)   │
└──────────────┘     └─────────────────┘     └──────────────────┘
     stdio              OpenAPI → MCP           API key (`ctk_`)
                        generated tools         REST JSON API

1. Sends Authorization: Bearer $DASHBOARD_API_KEY on CRM/platform routes
2. Loads and validates the OpenAPI spec from the live API (falls back to the validated bundled spec)
3. Converts each allowed API operation to an MCP tool with Zod input validation
4. Proxies tool calls to the dashboard API through the same request runtime used by the CLI
5. API-key 401s remain fail-closed (no password login fallback)

Build Commands

MCP Tool Examples

Once connected, agents can call tools like:

mcp__dashboard__dash_api_web_crm_contact_controller_index    # List contacts
mcp__dashboard__dash_api_web_crm_company_controller_show     # Get company by ID
mcp__dashboard__dash_api_web_crm_deal_controller_create      # Create a deal
mcp__dashboard__leads_today                                   # Today's new leads
mcp__dashboard__pipeline_summary                              # Deal pipeline overview
mcp__dashboard__license_overview                              # All licenses
mcp__dashboard__dash_api_web_crm_license_controller_extend    # Extend a CRM license

Architecture

Built on the same OpenAPI-to-MCP bridge pattern as jtapi-mcp:

• Spec parsing — Reads OpenAPI 3.0 paths and schemas
• Zod conversion — Converts OpenAPI schemas to Zod validators for MCP tool inputs
• Tool naming — Converts operationId to snake_case tool names
• Shared request runtime — Handles path params, query params, JSON bodies, auth, and re-auth for MCP and CLI

Spec Cleaning

The scripts/clean-spec.mjs script validates every HTTP operation and operation ID. Malformed entries fail the build instead of being silently stripped, so missing Dashboard controller declarations cannot disappear from the generated client.

Release flow

One workflow, .github/workflows/publish.yml, owns versioning. main is protected, so it never commits a bump; package.json stays a placeholder and the real version lives in the git tag.

1. Trigger: a push to main that touches src/, scripts/, package.json, yarn.lock, or tsconfig*.json, or a manual dispatch. Dashboard dispatches first sync and test the new contract in CI; their committed spec push triggers publication. A failed fetch fails the sync.
2. Version: next patch above the highest of the npm registry version and the highest vX.Y.Z git tag.
3. yarn build:nospec + tests, then npm publish.
4. Push git tag vX.Y.Z on the published commit.
5. Chained docker.yml builds and pushes ghcr.io/calltelemetry/dashboard-mcp as vX.Y.Z, latest, and the short sha. Semver tags are never re-pushed.
6. Flux ImageAutomation (ct-infrastructure) follows the new semver tag.

docker.yml does not build release images on a plain main push. Publication remains serialized without cancelling a release already in flight. Builds stamp package/source identity; connection_status and SSE/Worker health report runtime.package_version, runtime.build_sha, and spec.fingerprint. runtime.package_version_source is release for published package/image builds and source_manifest for development or main-branch Worker builds; the latter manifest placeholder is not an npm release receipt. OpenAPI spec.version and MCP protocol describe separate contracts and do not stand in for a package release receipt.

License

Private — CallTelemetry internal use only.

Cloudflare Worker (ADR 0781)

src/worker.ts serves the same tools as a stateless streamable-HTTP MCP (spec 2026-07-28) at https://mcp.calltelemetry.com/dashboard/mcp. Every request must carry a valid Cloudflare Access JWT (ACCESS_TEAM_DOMAIN, ACCESS_AUD): 503 until configured, 401 for a missing or invalid assertion. Tool registration is shared with the Node entrypoints; the OpenAPI spec is bundled at build time (no live fetch), and destructive operations stay disabled regardless of vars (src/worker-env.ts). Wrangler stamps build identity before every bundle, so preview uploads and deploys work from fresh independent checkouts even after installs skip scripts. DASHBOARD_API_KEY is synced from Doppler mcp-workers/prd by CI. The in-cluster SSE service is unchanged.

Production binds DASHBOARD_SERVICE to dash-edge-router. Dashboard health and API requests use this binding because same-zone Worker fetch cannot invoke a Worker Route backed by a discard DNS origin. The binding, Dashboard URL, and API key are scoped to the current request; API-key validation still happens in Dashboard. Only the configured Dashboard origin uses the binding, and an authenticated request to a different origin is rejected. Node clients and development without a service binding retain normal HTTP transport.