npm - @kadoa/mcp - Versions diffs - 0.6.6 → 0.7.0-rc.2 - Mend

@kadoa/mcp 0.6.6 → 0.7.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -2,87 +2,10 @@
 Use [Kadoa](https://kadoa.com) from ChatGPT, Claude.ai, Claude Code, Cursor, and other MCP clients.
-## Authentication
-Public API is the only OAuth authority. This server is an MCP resource server:
-it publishes protected-resource metadata, verifies RS256 resource tokens against
-Public API JWKS, enforces the exact issuer and resource audience, and exchanges
-each resource token for a request-local Public API token using a dedicated service secret.
-It does not mount authorization, registration, token, refresh, or revocation
-routes and does not store end-user credentials.
-This runtime targets the separate `mcp-server-beta` deployment. Production MCP
-at `https://mcp.kadoa.com/mcp` remains on legacy authentication until a separate
-approved migration.
-```sh
-MCP_AUTH_ISSUER=https://api.kadoa.com/v5/auth
-MCP_AUTH_JWKS_URL=https://api.kadoa.com/v5/auth/.well-known/jwks.json
-MCP_AUTH_AUDIENCE=https://beta.mcp.kadoa.com/mcp
-MCP_DOWNSTREAM_TOKEN_ENDPOINT=https://api.kadoa.com/v5/auth/mcp/downstream-token
-# Inject MCP_DOWNSTREAM_EXCHANGE_SECRET from a dedicated secret store.
-MCP_ALLOWED_ORIGIN_HOSTNAMES=beta.mcp.kadoa.com
-MCP_LEGACY_TRANSPORT_ENABLED=true
-```
-`MCP_LEGACY_TRANSPORT_ENABLED` controls protocol-version compatibility only.
-When `true`, supported 2025 protocol requests use the same central verifier and
-downstream exchange as modern requests. It never selects another authentication
-implementation. Missing central configuration fails startup.
-The exchange secret must contain at least 32 characters without whitespace.
-Generate at least 32 random bytes, encode as hex, and inject the same value into
-Public API as `KADOA_MCP_DOWNSTREAM_EXCHANGE_SECRET`. Never reuse the worker or
-legacy registry credentials. Secret rotation requires restarting both consumers.
-The service secret does not replace the user token or its authorization checks.
-No Google service account or metadata-server access is required.
-### Historical local central-mode fixture
-This fixture depends on the earlier backend local-issuer configuration, which
-is absent from the narrowed beta rollout candidate. The commands below are not
-a validated proof for that candidate. Do not restore browser OAuth or local-issuer
-support to run this rollout.
-The normal `dev` entrypoint authenticates downstream exchange with
-`MCP_DOWNSTREAM_EXCHANGE_SECRET`. The test-only launcher imports the backend
-exchange owner and uses a local-only fixture secret. It requires
-`KADOA_ENVIRONMENT=local`, binds to `127.0.0.1:3002`, and is not included in the
-published package build.
-Start the backend services without the regular MCP child. The shared environment
-pins the backend issuer, Assistant MCP URL, resource audience, and downstream
-Public API audience to literal loopback addresses. If the backend root `.env`
-defines `KADOA_MCP_TOKEN_ALLOWED_RESOURCES`, set it to
-`http://127.0.0.1:3002/mcp` as well. Backend package processes load that file and
-a conflicting value makes the Assistant exchange fail with `invalid_target`.
-The backend `turbo.json` dev task must propagate every variable exported by
-`local-central-env.sh`; the launcher checks this before it starts.
-```sh
-cd /home/gabrielziegler/kadoa/kadoa-backend
-direnv exec . bash -lc '
-  source /home/gabrielziegler/kadoa/kadoa-mcp/tests/integration/local-central-env.sh
-  ./start-kadoa.sh --quick --services=dashboard,api,shelly,events-gateway,operations
-'
-```
-In a second terminal, start the local central resource server with the backend's
-local environment:
-```sh
-direnv exec /home/gabrielziegler/kadoa/kadoa-backend bash -lc '
-  source /home/gabrielziegler/kadoa/kadoa-mcp/tests/integration/local-central-env.sh
-  cd /home/gabrielziegler/kadoa/kadoa-mcp
-  KADOA_BACKEND_ROOT=/home/gabrielziegler/kadoa/kadoa-backend bun run dev:central-local
-'
-```
-Open a new Dashboard Assistant session and request a workflow list. The proof
-covers the central resource server, backend-owned token exchange, live team
-membership checks, downstream Public API credentials, and real tool calls. It
-does not prove the current beta candidate, browser OAuth consent, or a deployed
-network boundary.
+This repo builds the Kadoa MCP server: an HTTP-only [MCP](https://modelcontextprotocol.io)
+resource server backed by Public API central authentication. There is no stdio
+transport and no CLI entry point — see [Deployment & auth](#deployment--auth)
+for what that means in practice.
 ## Remote Server (no install needed)
@@ -143,32 +66,108 @@ Point your client to `https://mcp.kadoa.com/mcp` with OAuth authentication.
 | Tool | Description |
 |------|-------------|
-| `scrape` | Immediately fetch one URL as markdown or raw HTML (shown only for enabled workspaces) |
-| `create_workflow` | Create an agentic navigation workflow from a prompt |
-| `create_realtime_monitor` | Create an asynchronous realtime monitoring workflow after persisting notification channels; returns workflow/session/thread/job IDs |
-| `list_workflows` | List workflows with status, Assistant session availability, template version drift, realtime health, and `awaitingUserInput`; filter with `statusFilters: ["group:attention"]` for everything waiting on you |
+| `scrape` | Immediately fetch one URL as markdown or raw HTML (shown only for scrape-enabled workspaces) |
+### Workflows
+| Tool | Description |
+|------|-------------|
+| `create_workflow` | Create a one-time or scheduled agentic-navigation extraction workflow, optionally from a template |
 | `get_workflow` | Get canonical intent, Assistant/session, template ownership, run health, schedule, location, monitoring, and validation details |
-| `request_workflow_update` | Ask the workflow Assistant to change extraction intent, navigation, sourcing, pagination, or generated behavior without changing the workflow ID |
+| `update_workflow` | Update deterministic configuration such as name, URLs, schema, schedule timezone, monitoring, and unlimited rows |
+| `run_workflow` | Run a workflow, including retrying a failed one-time or scheduled run |
+| `delete_workflow` | Delete a workflow permanently |
+| `approve_workflow` | Approve and activate a workflow that is in PREVIEW, PAUSED, or ERROR state |
+| `pause_workflow` | Pause an ACTIVE workflow's schedule |
+| `fetch_data` | Get a page of extracted data from a workflow (previews and small slices) |
+| `export_data` | Get the full extracted dataset via a signed download URL |
+| `list_workflows` | List workflows with status, Assistant session availability, template drift, realtime health, and `awaitingUserInput`; filter with `statusFilters: ["group:attention"]` for everything waiting on you |
+| `list_workflow_runs` | List a workflow's execution run history (status, start/finish, record count, errors) |
+| `get_workflow_history` | Get the workflow's configuration revision history (audit log) |
+### Realtime monitoring
+| Tool | Description |
+|------|-------------|
+| `create_realtime_monitor` | Create an asynchronous realtime monitoring workflow after persisting notification channels |
+| `list_changes` | List detected data changes across one or more realtime monitoring workflows |
+| `get_change` | Get detailed information about one detected change, including the data snapshot (cut to whole rows past ~80 KB) and diff |
+### Workflow Assistant
+| Tool | Description |
+|------|-------------|
 | `get_workflow_assistant` | Get the workflow Assistant's current activity and any pending clarification question |
-| `get_workflow_assistant_timeline` | Read paginated customer-visible Assistant messages and questions for one-time, scheduled, or realtime workflows |
+| `get_workflow_assistant_timeline` | Read paginated customer-visible Assistant messages and questions |
 | `answer_workflow_assistant_question` | Answer the workflow Assistant's current clarification question and resume it |
+| `request_workflow_update` | Ask the workflow Assistant to change extraction intent, navigation, sourcing, pagination, or generated behavior without changing the workflow ID |
 | `interrupt_workflow_assistant` | Safely interrupt active Assistant work without pausing the workflow schedule |
 | `resume_workflow_assistant` | Resume an idle/interrupted workflow Assistant with its persisted role and conversation |
 | `stop_workflow_assistant` | Stop active Assistant work without deleting or replacing the workflow |
 | `get_workflow_strategy` | Get the current customer-safe extraction/build strategy for an Assistant or custom-script workflow |
-| `get_workflow_history` | Get the workflow's configuration revision history (audit log) — who changed it, when, from which channel, and a `changedFields` summary per revision |
-| `list_activity` | List the team's Activity log (audit trail) across all workflows and resources: actor email, resource name, action, interface, timestamp, change summary; filter by time window, user, workflow, action, interface, resource type. Use `get_workflow_history` for one workflow's config diffs |
-| `list_workflow_runs` | List a workflow's execution run history (status, start/finish, record count, errors); filter by outcome and paginate |
+### Templates
+| Tool | Description |
+|------|-------------|
+| `list_templates` | List all templates in the current team |
+| `get_template` | Get a template by ID, including all published versions and schemas |
+| `create_template` | Create a new (unpublished) template |
+| `update_template` | Update a template's name and/or description only |
+| `delete_template` | Delete (archive) a template |
+| `create_template_version` | Publish a new immutable version of a template (prompt, schema, notifications) |
+| `apply_template_version` | Push a template version onto its linked workflows |
+| `save_workflow_as_template` | Create a template (or a new version of one) from an existing workflow's configuration |
+| `list_template_schemas` | List schemas associated with a template |
+| `list_template_workflows` | List the workflows linked to a template, flagging which are outdated |
+| `link_template_to_workflows` | Link existing workflows to a template so they inherit and stay in sync with it |
+| `unlink_template_from_workflows` | Unlink workflows from a template, keeping their current configuration |
+### Variables
+| Tool | Description |
+|------|-------------|
+| `create_variable` | Create a variable (key/value pair referenced in prompts as `@key`) |
+| `list_variables` | List all variables in the current team scope |
+| `get_variable` | Get a specific variable by its ID |
+| `update_variable` | Update an existing variable |
+| `delete_variable` | Delete a variable permanently |
+### Notifications
+| Tool | Description |
+|------|-------------|
+| `create_notification_channel` | Create a notification channel (email, webhook, Slack, or WebSocket), reusing an existing one for the same destination |
+| `list_notification_channels` | List notification channels configured for a workflow or across the workspace |
+| `delete_notification_channel` | Delete a notification channel by ID |
+| `configure_notifications` | Create channels and event-to-channel settings for a workflow or workspace in one step |
+| `list_notification_settings` | List notification settings (event-to-channel mappings) |
+| `delete_notification_setting` | Delete a notification setting (the event-to-channel mapping, not the channel) |
+### Observability & activity
+| Tool | Description |
+|------|-------------|
 | `get_observability` | Team-wide workflow health for a window of days: uptime, failed runs, MTTR, records delivered, health counts, and a ranked list of down or degraded workflows (the Observability page data) |
-| `run_workflow` | Execute a workflow |
-| `fetch_data` | Get extracted data from a workflow |
-| `delete_workflow` | Delete a workflow |
-| `approve_workflow` | Approve and activate a workflow |
-| `pause_workflow` | Pause an active workflow |
-| `update_workflow` | Update deterministic configuration, including location, schedule timezone, monitoring conditions, and unlimited rows |
+| `list_activity` | List the team's Activity log (audit trail) across all workflows and resources: actor email, resource name, action, interface, timestamp, change summary |
+### Support
+| Tool | Description |
+|------|-------------|
+| `create_support_ticket` | File a support ticket for one workflow so the Kadoa team investigates it |
+### Account & team
+| Tool | Description |
+|------|-------------|
 | `whoami` | Show current user details, auth method, and team memberships |
 | `team_list` | List all teams you belong to and see which is active |
-| `team_switch` | Switch the active team by name or ID |
+Team switching (a team_switch tool) exists in the code but is currently
+disabled and hidden from every client's tool list — a credential is fixed to
+one team for its lifetime under central auth; reconnect to choose a different
+team.
 ## Workflow controls and behavior
@@ -350,130 +349,189 @@ delete_workflow for each, confirming before proceeding.
 - Restart your MCP client
 - Re-authenticate via OAuth if prompted
-## Releases
-This repo ships two surfaces, and a "release" usually touches both:
-- **npm package `@kadoa/mcp`** — stdio CLI users install locally (`npx @kadoa/mcp`). Cut by [Release Please](https://github.com/googleapis/release-please) from Conventional Commits on `main`.
-- **Hosted server at `mcp.kadoa.com`** — Docker container on GKE, built and deployed from the [`kadoa-backend`](https://github.com/kadoa-org/kadoa-backend) monorepo, which pins a specific `@kadoa/mcp` version.
+## Deployment & auth
-Relevant files in `kadoa-backend`:
-- `infra/docker/mcp/Dockerfile.mcp-server` — image definition
-- `infra/docker/mcp/package.json` — pinned `@kadoa/mcp` version
-- `infra/cdk8s/mcp/charts/Server.ts` — k8s manifest source (prod chart only; the test deployment is provisioned ad hoc — see below)
+This server is an MCP **resource server**, not an OAuth authorization server:
+Public API is the only OAuth authority. This code publishes protected-resource
+metadata, verifies RS256 resource tokens against Public API's JWKS, enforces
+the exact issuer and resource audience, and exchanges each resource token for
+a request-local Public API token using a dedicated service secret
+(`src/kadoa-access-token.ts`, `src/downstream-token.ts`). It never mounts
+authorization, registration, token, refresh, or revocation routes and never
+stores end-user credentials. Old opaque MCP bearer credentials are rejected —
+this build supports **central auth only**.
-### Production release
+There is no stdio transport (`src/http.ts` is the only server entry point) and
+no `bin` in `package.json`, so `npx @kadoa/mcp` does not start a usable server.
-1. Merge PRs to `main` using Conventional Commits (`feat:`, `fix:`, etc.). Release Please opens/maintains a `chore(main): release mcp x.y.z` PR.
-2. Merge the release PR. The [`release-please.yml`](.github/workflows/release-please.yml) workflow tags, drafts a GitHub Release, and publishes to npm through GitHub Actions OIDC trusted publishing (`latest` dist-tag).
-3. After npm publication, `release-please.yml` opens or updates a deterministic PR in `kadoa-backend` that bumps `infra/docker/mcp/package.json` and refreshes `bun.lock`. The PR validates a frozen production install and Docker image build, and remains manually mergeable.
-4. Merge the backend PR to `main`. CI (`main-build-deploy.yml`) builds and pushes `europe-west3-docker.pkg.dev/oceanic-base-310208/kadoa-artifacts/mcp-server:<IMAGE_TAG>` (tag shown in the build summary).
-5. Trigger the **Deploy to Production** workflow ([`deploy-prod.yml`](https://github.com/kadoa-org/kadoa-backend/actions/workflows/deploy-prod.yml)) with:
-   - **Target cluster:** `gcp`
-   - **Deployment scope:** `mcp`
-   - **Image tag:** the tag from step 4
-   - **Method:** `kubectl`
+### Where this code runs
-The cross-repository bump requires the `BACKEND_REPO_TOKEN` secret in this repository. The selected authentication approach is a fine-grained PAT scoped only to `kadoa-org/kadoa-backend` with Contents read/write and Pull requests read/write permissions (Metadata read is automatic). If the secret is not provisioned, the release workflow skips the backend bump with a warning rather than failing npm releases; an administrator must provision it before relying on automatic hosted-server updates.
+Two deployments exist in `kadoa-backend` (see `infra/cdk8s/clusters/kadprod1.ts`
+and `infra/cdk8s/staging/services.ts`):
-### RC / test release
+- **`https://beta.mcp.kadoa.com/mcp`** — runs the image built from this repo,
+  with central auth (`auth.mode: "central"`). It has carried all production
+  Dashboard Assistant traffic since 2026-09-23.
+- **`https://mcp.kadoa.com/mcp`** (and staging) — still run a pinned legacy
+  image (`LEGACY_MCP_IMAGE_DIGEST` in `infra/cdk8s/mcp/images.ts`) built from
+  older code, with `auth.mode: "legacy"`. Promoting these to this repo's code
+  and central auth is a separate, approved migration.
-Use this when you want to validate a change end-to-end against real clients (Claude Desktop, Cursor, ChatGPT) before promoting to `latest` / prod. The flow mirrors the prod one, but every step targets `rc` channels.
+The `@kadoa/mcp` npm package (this repo's build output plus `README.md`, per
+`package.json` `files`) is not distributed as an end-user CLI — it is the
+server bundle the backend image installs (`infra/docker/mcp/package.json`
+pins the version).
-There are two ways to consume an RC:
+## Configuration
-- **Local stdio**: `npx @kadoa/mcp@rc` — installs from the `rc` dist-tag on npm. Good for quick sanity checks where the bug doesn't depend on the hosted OAuth flow.
-- **Hosted `mcp-server-test`**: a separate k8s deployment alongside prod in the same GKE cluster. Use it to validate protected-resource discovery, OAuth callbacks owned by Public API, and multi-tenant behavior.
+All auth and downstream-exchange settings below are required for the server
+to start (`bun run dev` fails immediately without them); there is no fallback
+auth mode.
-#### Publish an RC to npm
+| Variable | Description |
+|---|---|
+| `PORT` | HTTP port to listen on (default `3000`) |
+| `MCP_SERVER_URL` | This deployment's own base URL; used only to derive a default for `MCP_ALLOWED_ORIGIN_HOSTNAMES` when that variable is unset and the hostname is a loopback address (default `http://localhost:<PORT>`) |
+| `KADOA_PUBLIC_API_URI` | Public API base URL the server calls through `@kadoa/node-sdk` (default `https://api.kadoa.com`) |
+| `KADOA_DASHBOARD_URL` | Base URL used to build `dashboardUrl` links in tool responses (default `https://www.kadoa.com`) |
+| `MCP_AUTH_ISSUER` | Exact Public API OAuth issuer, e.g. `https://api.kadoa.com/v5/auth` |
+| `MCP_AUTH_JWKS_URL` | JWKS URL for the issuer |
+| `MCP_AUTH_AUDIENCE` | Exact MCP resource URL served by this deployment; must be HTTPS (loopback HTTP allowed) and its path must be `/mcp` |
+| `MCP_DOWNSTREAM_TOKEN_ENDPOINT` | Public API's service-authenticated downstream exchange endpoint |
+| `MCP_DOWNSTREAM_EXCHANGE_SECRET` | Dedicated service credential shared only with the downstream exchange; must be at least 32 characters with no whitespace, and must match Public API's `KADOA_MCP_DOWNSTREAM_EXCHANGE_SECRET` |
+| `MCP_ALLOWED_ORIGIN_HOSTNAMES` | Comma-separated hostnames admitted when an HTTP `Origin` header is present; required outside loopback |
+| `MCP_ALLOWED_HOSTNAMES` | Comma-separated `Host` header allow-list for DNS-rebinding protection (opt-in); loopback and this pod's own interface addresses are always added |
+| `MCP_LEGACY_TRANSPORT_ENABLED` | `true` (default) serves supported 2025 MCP protocol versions through the same central verifier and downstream exchange as modern requests; `false` rejects them. It never selects a different authentication implementation |
+| `LOG_LEVEL` | `debug`, `info` (default), `warn` or `error`; filters the structured JSON log lines written to stdout |
+| `MCP_METRICS_PORT` | Port for a separate Prometheus `GET /metrics` listener (unset disables it). The Kadoa deployment uses `35536`, the port its pod scrape annotations point at; it is not exposed through the Service or ingress |
+**Request logs and metrics.** Every `/mcp` request writes one JSON line to stdout
+(`event: "mcp.request"`) with `requestId`, `era` (`modern`, `legacy`, `unknown`),
+`httpMethod`, `method`, `toolName`, `clientInfo.name`, `protocolVersion`, `clientId`,
+`userId`, `teamId`, `status`, `latencyMs`, `isError`, `rpcErrorCode`, `authReason`,
+`traceId` and `aborted`. `isError` is true when the HTTP status is >= 400, the
+outgoing JSON-RPC message carries an `error` object, or a tool result sets
+`isError: true`; `rpcErrorCode` is the JSON-RPC error's `code` when the response
+was a JSON-RPC error. `authReason` mirrors the reason class of a bearer-auth
+rejection (see below) on that same request's line. `traceId` is the 32-hex-char
+trace id from an incoming W3C `traceparent` (header, or the SEP-414 `_meta` trace
+context if the request body carries one — that takes precedence), when present.
+`aborted` is `true` only when the connection closed before the response finished
+writing; it is omitted otherwise. Bearer-auth failures additionally write a
+separate `auth.rejected` line with a reason class only. Tokens, request bodies and
+tool arguments are never logged. The request id comes from a well-formed incoming
+`x-request-id` (otherwise it is generated) and is returned in the response
+header. `MCP_METRICS_PORT` exposes `mcp_http_requests_total{era,method,status}`
+and `mcp_auth_rejections_total{reason}`; it must be a different port from `PORT`,
+or the server refuses to start.
+**Turning off legacy transport.** Set `MCP_LEGACY_TRANSPORT_ENABLED=false` only when,
+over a trailing 14 days: the legacy share of successful requests,
+`sum(increase(mcp_http_requests_total{era="legacy",status=~"2.."}[14d])) / sum(increase(mcp_http_requests_total{status=~"2.."}[14d]))`,
+is below 1%; no first-party or top-10 client still appears in
+`jsonPayload.event="mcp.request" AND jsonPayload.era="legacy"` grouped by
+`jsonPayload.clientInfo.name` (legacy clients send it on `initialize`); and delegated
+Dashboard Assistant traffic (`clientId` `kadoa-delegated:shelly-worker`) is modern
+only. After switching, watch `sum(increase(mcp_http_requests_total{era="legacy"}[1d]))`
+overall for a week, not only `status="400"`: with legacy transport off, a legacy
+notification (no JSON-RPC response expected, e.g. `notifications/initialized`) is
+answered `202 Accepted` rather than rejected, so most straggling legacy traffic shows
+up as `era="legacy",status="202"`, and only a legacy request that expects a reply
+(e.g. `initialize`) gets a `4xx` rejection. Setting the flag back to `true` restores
+legacy serving.
+Secret rotation requires restarting both this server and Public API. The
+service secret does not replace the user's own token or its authorization
+checks. No Google service account or metadata-server access is required.
-Manual — Release Please only cuts stable versions today.
+## Development
 ```bash
-# from a branch on kadoa-mcp
-bun install && bun run build
-# bump version to a prerelease, e.g. 0.5.7-rc.1
-npm version 0.5.7-rc.1 --no-git-tag-version
-npm publish --tag rc --access public
+bun install
+bun run dev              # Run locally (requires all vars above to be set)
+bun run dev:central-local # Recommended local workflow (see below)
+bun run test              # Run every discovered test (BUN_TEST=1 bun test)
+bun run test:unit         # Run the curated unit suite used in CI
+bun run check-types       # tsc --noEmit
+bun run lint              # bunx biome check
+bun run build             # Bundle for distribution
+bun run smoke:dist        # Boots dist/index.js and checks /health (lands with KAD-24989)
 ```
-Verify: `npm view @kadoa/mcp dist-tags`. The `rc` tag should now point to your version. Existing tags today: `latest`, `rc`, `next`.
-Promote later with: `npm dist-tag add @kadoa/mcp@0.5.7 latest` (run **after** the matching stable version has been published the normal way).
+### Local development (`dev:central-local`)
-#### Deploy the RC to `mcp-server-test`
+`bun run dev` boots the same central-auth code path as production, so it
+requires every `MCP_AUTH_*` / `MCP_DOWNSTREAM_*` variable above to already be
+set and fails startup otherwise. `bun run dev:central-local`
+(`tests/integration/local-central-server.ts`) wires that configuration up for
+you against a **local** Kadoa backend instead of hand-setting each variable:
-1. In `kadoa-backend`, set `infra/docker/mcp/package.json` `@kadoa/mcp` to the RC version, `bun install`, push to a branch and merge to `main`. CI builds the `mcp-server:<IMAGE_TAG>` image as usual.
-2. Update the test deployment to the new image:
+1. Start the backend with `KADOA_ENVIRONMENT=local` so its local Public API
+   (`public-api`) listens on `http://127.0.0.1:12380`; source
+   `tests/integration/local-central-env.sh` in that shell first, and make sure
+   the backend's `turbo.json` `dev` task propagates the variables it sets.
+2. From this repo, with `KADOA_BACKEND_ROOT` pointing at that backend
+   checkout and `KADOA_ENVIRONMENT=local`:
    ```bash
-   gcloud container clusters get-credentials kadoa-prod \
-     --region=europe-west3 --project=oceanic-base-310208
-   kubectl set image deployment/mcp-server-test \
-     mcp-server=europe-west3-docker.pkg.dev/oceanic-base-310208/kadoa-artifacts/mcp-server:<IMAGE_TAG>
+   KADOA_BACKEND_ROOT=/path/to/kadoa-backend KADOA_ENVIRONMENT=local \
+     bun run dev:central-local
    ```
-3. Port-forward to reach it (the test deployment has **no public ingress** by design):
+3. The server listens on `http://127.0.0.1:3002/mcp`, using a local-only
+   exchange secret and the backend's own token-exchange and team-membership
+   code (imported directly from `KADOA_BACKEND_ROOT`). It refuses to start if
+   the backend checkout, its `turbo.json` env propagation, or the local Public
+   API at `12380` aren't in place.
+See `tests/integration/README.md` for the deeper integration proof this local
+flow builds on.
+### Build
+`bun run build` bundles `src/index.ts` to `dist/index.js` with all
+dependencies kept external (`--packages=external`), so `dist/` resolves
+packages from `node_modules` at run time instead of bundling them in. That is
+what lets the backend image's `overrides` in `infra/docker/mcp/package.json`
+(for example pinning `@kadoa/node-sdk`) take effect for the built server.
+That override must be kept in the SDK range this package depends on; the
+automated backend PR that bumps `@kadoa/mcp` after a release only bumps that
+dependency, not the `overrides` block, so a mismatch there has to be fixed by
+hand.
+`bun run smoke:dist` boots the built `dist/index.js` and checks `/health` as
+part of verifying a build.
-   ```bash
-   kubectl port-forward svc/mcp-server-test 3000:3000
-   ```
-4. Point your MCP client at `http://localhost:3000/mcp` and exercise the change.
-**Auth gotcha:** `auth.kadoa.com` enforces an `ALLOWED_CALLBACK_ORIGINS` allowlist (`app.kadoa.com`, `mcp.kadoa.com`, `kadoa.com`) plus a loopback bypass for `127.0.0.1` when `NODE_ENV !== production`. `localhost` is **not** treated the same as `127.0.0.1` by that check. The test pod is configured with `MCP_SERVER_URL=http://localhost:3000` so the port-forwarded session resolves correctly. If you change the local port, update the deployment env var too:
-```bash
-kubectl set env deployment/mcp-server-test MCP_SERVER_URL=http://localhost:<PORT>
-```
-#### Promotion checklist
-Before flipping `latest` / deploying to prod:
-- [ ] RC consumed locally (`npx @kadoa/mcp@rc`) — stdio tools work
-- [ ] RC consumed via `mcp-server-test` — OAuth login succeeds end-to-end
-- [ ] No new errors in the test pod's logs (`kubectl logs deployment/mcp-server-test -f`)
-- [ ] Release Please PR open with the stable version
-## Development
-```bash
-bun install
-bun run dev        # Run locally
-bun run test       # Run tests
-bun run build      # Build for distribution
-```
+## Releases
-### Connecting to local services
+This repo ships two surfaces, and a "release" usually touches both:
-To develop and test against a local Kadoa backend (instead of the production API), point the MCP at your local `public-api` service using the `KADOA_PUBLIC_API_URI` environment variable.
+- **npm package `@kadoa/mcp`** — the server bundle the hosted deployments
+  install. Cut by [Release Please](https://github.com/googleapis/release-please) from Conventional Commits on `main`.
+- **Hosted server at `beta.mcp.kadoa.com`** (production traffic) and
+  `mcp.kadoa.com` (legacy, separate migration) — Docker containers on GKE,
+  built and deployed from the [`kadoa-backend`](https://github.com/kadoa-org/kadoa-backend) monorepo, which pins a specific `@kadoa/mcp` version for the non-legacy deployment.
-**Prerequisites:** the `public-api` service must be running locally (default port `12380`).
+Relevant files in `kadoa-backend`:
+- `infra/docker/mcp/Dockerfile.mcp-server` — image definition
+- `infra/docker/mcp/package.json` — pinned `@kadoa/mcp` version and dependency `overrides`
+- `infra/cdk8s/clusters/kadprod1.ts` — k8s manifest source for `mcp-server` (legacy) and `mcp-server-beta` (this repo's code, central auth)
-**Run the MCP server locally:**
+### Production release
-```bash
-KADOA_PUBLIC_API_URI=http://localhost:12380 bun run dev
-```
+1. Merge PRs to `main` using Conventional Commits (`feat:`, `fix:`, etc.). Release Please opens/maintains a `chore(main): release mcp x.y.z` PR.
+2. Merge the release PR. The [`release-please.yml`](.github/workflows/release-please.yml) workflow tags, drafts a GitHub Release, and publishes to npm through GitHub Actions OIDC trusted publishing (`latest` dist-tag).
+3. After npm publication, the same workflow opens or updates a deterministic PR in `kadoa-backend` that bumps `infra/docker/mcp/package.json` and refreshes its lockfile, validating a production install and Docker image build. It remains manually mergeable, and is skipped with a warning (not a failure) if the `BACKEND_REPO_TOKEN` secret isn't provisioned.
+4. Merge the backend PR to `main`. CI builds and pushes the `mcp-server` image.
+5. Deploy the new image tag to the target deployment (`mcp-server-beta` for this repo's code) through the backend's deploy workflow.
-The server starts in HTTP mode. You authenticate via OAuth the same way as with the remote server.
+### RC / test release
-### HTTP server environment variables
+Use this to validate a change end-to-end before promoting to the `latest` npm dist-tag. Trigger the [`release-please.yml`](.github/workflows/release-please.yml) workflow manually (`workflow_dispatch`) with an `rc_version` like `0.6.0-rc.1`; it publishes that version under the npm `rc` dist-tag using the same trusted-publishing flow as a stable release.
-| Variable | Description |
-|---|---|
-| `MCP_AUTH_ISSUER` | Exact Public API OAuth issuer, such as `https://api.kadoa.com/v5/auth` |
-| `MCP_AUTH_JWKS_URL` | JWKS URL for the issuer |
-| `MCP_AUTH_AUDIENCE` | Exact MCP resource URL served by this deployment; its path must be `/mcp` |
-| `MCP_DOWNSTREAM_TOKEN_ENDPOINT` | Public API service-authenticated downstream exchange endpoint |
-| `MCP_DOWNSTREAM_EXCHANGE_SECRET` | Dedicated service credential shared only with the downstream exchange; must satisfy the same validation as Public API `KADOA_MCP_DOWNSTREAM_EXCHANGE_SECRET` |
-| `MCP_ALLOWED_ORIGIN_HOSTNAMES` | Comma-separated hostnames admitted when an HTTP Origin header is present; required outside loopback |
-| `MCP_LEGACY_TRANSPORT_ENABLED` | `true` serves supported 2025 protocol versions through central auth; `false` rejects them |
+Verify: `npm view @kadoa/mcp dist-tags`. The `rc` tag should now point to your version.
-All authentication and downstream-exchange settings are required. Old opaque
-MCP bearer credentials are rejected.
+Because there is no CLI entry point, consuming an RC means pointing a hosted
+test deployment at the new image tag, not `npx`ing the package locally.
 ## Contributing
@@ -487,7 +545,7 @@ A typical feature touches three repos — **`kadoa-backend` → `kadoa-sdks` →
 | SDK low-level | `kadoa-sdks/sdks/node/src/generated/api/*` | Auto-generated axios client. Raw HTTP, typed from the OpenAPI spec. **Do not hand-edit.** |
 | SDK domain (high-level) | `kadoa-sdks/sdks/node/src/domains/<thing>/<thing>.service.ts` | Thin domain wrapper over the generated client. `client.<thing>.<action>(...)`. This is what callers use. |
 | CLI | `kadoa-cli/src/commands/<thing>.ts` | Commander action: flag parsing, spinner, table/json output. Calls SDK domain. |
-| MCP (this repo) | `kadoa-mcp/src/tools.ts` | Zod input schema + tool description tuned for LLMs. Calls SDK domain. |
+| MCP (this repo) | `kadoa-mcp/src/tools/<domain>.ts` | Zod input schema + tool description tuned for LLMs. Calls SDK domain. |
 Mental model:
 - **SDK** = pure function over HTTP.
@@ -515,30 +573,36 @@ CLI and MCP both call **identical** SDK domain methods. A new feature added to t
 3. **MCP** (this repo)
    - Bump `@kadoa/node-sdk` in `package.json` to the new version, `bun install`.
-   - Add the tool in `src/tools.ts`:
-     - Zod input schema (use coercion helpers in `src/coercion.ts` where needed — LLM clients sometimes send strings for numbers/bools).
+   - Add the tool in the matching `src/tools/<domain>.ts` register function (keep `src/tools/index.ts` order in mind — it is the `tools/list` order):
+     - Zod input schema (coercion helpers for inputs LLM clients sometimes send as strings, e.g. numbers/bools, live in `src/tools/shared/coercion.ts`; shared shapes in `src/tools/shared/schemas.ts`).
      - Description string written **for the LLM**: when to call it, what inputs mean, what the response shape is.
      - Implementation calls `ctx.client.<thing>.<action>(...)` — never raw HTTP.
    - Add a unit test under `tests/unit/`.
+   - If the change intentionally alters a tool's name, title, description, schema, outputSchema or annotations, regenerate the snapshot: `UPDATE_TOOLS_SNAPSHOT=1 BUN_TEST=1 bun test tests/unit/tools-list-snapshot.test.ts`, then `./node_modules/.bin/biome format --write tests/unit/fixtures/tools-list.snapshot.json`.
    - Use a Conventional Commit message (`feat(mcp): ...`, `fix(mcp): ...`). Release Please will cut the next version on merge to `main`.
 4. **CLI** (`kadoa-cli`), if the feature is user-facing on the command line: mirror the MCP step in `src/commands/<thing>.ts`. Same SDK call, different UX.
 ### Anti-patterns
-- ❌ Raw `axios` calls or hand-rolled HTTP in `src/tools.ts`. Always go through `ctx.client.<thing>`.
+- ❌ Raw `axios` calls or hand-rolled HTTP in `src/tools/`. Always go through `ctx.client.<thing>`.
 - ❌ Putting tool-shaped logic (input validation, response shaping) in the MCP layer when the SDK should expose it. If two clients would need the same logic, it belongs in the SDK.
 - ❌ Editing files under `sdks/node/src/generated/` by hand. They get overwritten by `kadoa-codegen generate`.
 - ❌ Bundling a spec update and an SDK feature in the same commit — keep `specs/` PRs separate from domain-method PRs for clean review.
 ### Where to find things in this repo
-- `src/tools.ts` — every MCP tool. Single file by design; search for the tool name.
-- `src/kadoa-access-token.ts` — verifies Public API resource tokens.
+- `src/tools/` — MCP tools, one module per domain (`workflows`, `assistant`, `templates`, `notifications`, `variables`, `observability`, `team`, `scrape`, `support`); shared zod schemas, coercion, errors, results and dashboard URLs in `src/tools/shared/`. `src/tools/index.ts` fixes registration order.
+- `src/server.ts` — assembles the `McpServer` (tool registration, capability gating, instructions); `src/index.ts` is the CLI entry.
+- `src/http.ts` — Express resource server, MCP transport mounting, and graceful shutdown.
+- `src/kadoa-access-token.ts` — verifies Public API resource tokens (central auth config, JWT verification).
 - `src/downstream-token.ts` — exchanges resource tokens for request-local Public API credentials.
 - `src/client.ts` — wires `@kadoa/node-sdk` per request.
-- `src/http.ts` — Express resource server and transport adapter.
-- `tests/unit/` — bun tests; run with `bun run test`.
+- `src/principal.ts` — the `McpPrincipal` type carried through auth and tool context.
+- `src/notification-channels.ts` — channel identity/reuse logic shared by the notification tools.
+- `src/error-summary.ts` — redacts credentials from error messages before they're logged.
+- `tests/unit/` — bun tests; run with `bun run test:unit` (curated) or `bun run test` (everything discovered).
+- `tests/integration/` — local and CI-owned integration fixtures against a real backend; not part of `test:unit`.
 ## License