MCP Server

MCP Server v0.0.1-beta.15

Explicit Account-Wide Access

Eligible users can explicitly authorize Entire account, including future
projects during Convert OAuth consent. That grant enables account-wide tools,
including project creation, while the backend continues to enforce live roles,
permissions, plan limits, and the role approved at consent time.

Selecting all existing projects is still a selected-project grant, not permission
over future projects. Existing customers retain their current access without a
forced reconnect or automatic privilege expansion. Reconnect only to deliberately
approve a broader grant. Local API-key/HMAC access keeps its existing permission
model.

Approval Governance

The MCP preserves Convert's backend approval requirements and returns actionable
request information instead of treating an approval requirement as an ordinary
failed write. Request IDs survive the dedicated safe projection so agents can
inspect an existing pending request rather than submit duplicates.

Approval actions require explicit, target-bound confirmation. The MCP never
automatically approves or retries an approved action. Account-wide approval
settings additionally require explicit account-wide consent on hosted connections.

Approval-request writes are enabled in authorized write profiles, with the
backend's live permissions and independent-review requirements still enforced.

Safer Project Management

Project creation is advertised only for eligible hosted grants and independently
checked against the exact target account at execution. New projects are
discoverable with an existing explicit entire-account grant.

The existing backend project-delete endpoint is now represented in the generated
contract and curated MCP namespace. Deletion still requires an explicit user
request followed by a second confirmation naming the exact numeric resource.
Read-only profiles do not expose deletion; generated operation IDs cannot bypass
the namespace guardrails.

Reliability And Knowledge

• Grant-aware catalogs recover after transient scope-resolution failures and
  notify compatible clients when the authoritative catalog changes.
• Refreshed knowledge corpus with 9,738 chunks and compatibility mappings for
  previously issued document IDs. Local semantic search and hosted hybrid search
  retain their respective vector-backed implementations.
• Standalone validators cover all 127 generated API operations, including the
  newly exported project lifecycle operation.
• Improved reusable MCP Inspector certification distinguishes successful feature
  access, expected plan restrictions, deliberately disabled features, and actual
  errors. Output schemas are checked alongside response status.
• Staging-only dual authentication supports the protected backend staging service;
  production authentication and existing OAuth storage remain unchanged.

Notifications Deferred

Notification settings/history support is implemented but disabled by default
in this release while the backend notification feature finishes rollout.
Disabled notification tools are absent from the catalog and cannot be invoked
through stale calls. The implementation is retained for a later controlled
activation, with plan/role/scope checks and webhook credential redaction.

This release does not change notification settings or delivery in the Convert UI.
Local npm and hosted clients keep working without configuring this future feature.

Release Verification

Publication is gated on the final committed tree: deterministic CI, generated
drift and validators, namespace/authorization tests, package binary startup,
semantic artifacts, hosted builds, and staging acceptance. The local npm package
remains stdio; remote-only UI/Worker code is not shipped as the npm entrypoint.

See the repository's dated QA certification for actual test outcomes and residual
limitations. Release preparation or a GitHub merge is not proof of deployment.

MCP Server v0.0.1-beta.14

Beta.14 is the largest Convert MCP upgrade since the shared local/remote runtime shipped: 59 commits across 203 files since beta.13. It prepares the hosted connector for Anthropic and ChatGPT directory submission while preserving the existing local npm experience and customer authentication model.

The release has one capability model with two presentations:

• Local npm/stdio remains a compact 16-tool server authenticated with the existing Convert API key and HMAC flow.
• Hosted MCP remains OAuth-authenticated and now exposes 45 tools: 40 semantically separated read/write/delete tools plus five read-only MCP Apps render tools.

The hosted split improves host safety classification and approval behavior while preserving every capability that the current project-scoped OAuth grant can authorize. It intentionally omits account-level operations that beta.13 advertised but hosted OAuth could never authorize: project creation, billing portal access, account-wide live data/history, and collaborator listing. Their local API-key actions remain available subject to Convert permissions, and project-scoped alternatives remain available remotely. API-key listing is omitted from both runtimes because the backend intentionally returns no key records to API-authenticated callers; stale calls fail explicitly instead of yielding a misleading empty success. The production OAuth client, callback, grants, selected account/project scope, and endpoint remain unchanged. Staging grants created while the staging Worker targeted the staging Management API required one fresh authorization when that Worker moved back to the production Management API; current post-migration staging grants are expected to survive this catalog/code upgrade.

Highlights

Claude And ChatGPT Directory Readiness

• Adds a directory-friendly hosted catalog with reads on base namespace tools, mutations on _write, and destructive actions on _delete.
• Keeps POST-backed reports and filtered reads classified by semantic behavior rather than HTTP method.
• Returns WrongToolForAction with a corrected call when a client sends an action to the wrong safety tool.
• Stops advertising remote account-level actions that the selected-project OAuth model cannot authorize. Stale hosted calls fail before transport with stable capability guidance; local project-create permission denials become ProjectCreationPermissionRequired while plan/feature 403s retain their original meaning.
• Publishes complete MCP annotations, OAuth security schemes, draft 2020-12 input/output schemas, and precompiled validators for every advertised tool.
• Serves Claude, ChatGPT, Codex, and generic MCP clients from the same Worker. Negotiated clientInfo changes only optional MCP Apps sandbox metadata, never tools, authorization, grants, schemas, results, or telemetry.
• Includes updated Anthropic and ChatGPT submission packets, branding assets, manifests, favicon discovery, and connector metadata. Directory submission and approval remain post-production steps, not claims made by this release.

Current hosted protocol surface:

• 45 tools: 40 semantically split data/action tools plus five read-only render tools.
• 20 curated prompts.
• Six listed resources: five MCP Apps plus convert://playbooks/implementation-investigation/v1.
• Canonical OpenAI-compatible documentation tools: search and fetch; search_knowledge_base is not advertised.

Convert Investigation Intelligence

Adds a coherent, read-only investigation path instead of making models assemble diagnostics through trial and error:

• operator.investigate produces a deterministic convert.investigation.v1 evidence packet.
• projects.debug_logs exposes authorized, bounded raw tracking diagnostics for explicit drill-down.
• experiences.report_integrity compares equal recent and baseline windows for meaningful stream drops.
• implementation_integrity_debugger and convert://playbooks/implementation-investigation/v1 share one canonical browser/source investigation methodology.
• render_investigation_report provides an optional, compact visual digest after the model has analyzed the normal investigation packet.

The normal investigation packet is privacy-reduced: it keeps source status, freshness, confirmed facts, expected behavior, anomalies, hypotheses, limitations, missing evidence, and safe next checks while excluding visitor IDs, full URLs/referrers, user-agent strings, segment snapshots, raw debug rows, and raw upstream diagnostics. This means data-minimized, not anonymous. Authorized raw evidence remains available only through the explicit drill-down action.

Prompt Intelligence

• Preserves all 19 public prompt names while upgrading every workflow to beta.14 terminology, wrappers, pagination, lifecycle, targeting, write-safety, and stats-lens semantics.
• Adds High-Impact Experience Opportunities, a read-only, scenario-driven workflow that grounds recommendations in project configuration, current and historical experiences, goals, hypotheses, audiences, locations, results, alerts, and measurement readiness before adding Convert documentation inspiration.
• Ranks opportunities by expected-impact potential, evidence confidence, implementation effort, measurement readiness, and risk. It can focus on ecommerce, SaaS acquisition/activation, agency portfolios, retests, segments, readiness, quick wins, or strategic opportunities without adding tools.
• Requires source-data reasoning before optional UI rendering. Hosts without MCP Apps receive the same substantive workflow.
• Keeps Bayesian, fixed-sample Frequentist, and sequential evidence vocabularies separate; treats MDE as prospective planning state and MAB allocation as behavior, not proof.
• Never promises impact or creates, activates, pauses, or deletes resources during opportunity discovery.

Investigation is fail-closed:

• Unavailable or unknown evidence is never converted into an empty or positive state.
• An empty debug-log result is inconclusive unless source availability and corroborating evidence support a stronger conclusion.
• Report integrity is usable only when the experience spans the complete baseline and recent comparison window.
• Project and experience live-data feeds retain their different goal scopes and are not incorrectly reconciled.
• Browser and source checks remain client-side capabilities. Convert MCP does not embed a browser and does not connect to AWS, Convert Assistant, Intercom, Asana, or private support infrastructure.

Correct Experience And Statistics Semantics

• Uses Convert's product term experience across hosted tools, UI labels, prompts, and guidance.
• Treats deploy experiences as rollout containers that are not visitor/conversion-tracked by design. Zero visitors, zero conversions, empty live data, and tracking alerts do not by themselves mean a deploy is broken.
• Makes Bayesian and Frequentist evidence mutually exclusive. Bayesian responses do not use confidence or statistical-significance language; Frequentist responses do not use chance-to-win, posterior-risk, or expected-loss language.
• Interprets done within the configured engine: fixed-horizon sample completion, sequential boundary crossing, or Bayesian decision/risk criteria.
• Treats SRM as a verdict blocker, not a lifecycle change.
• Treats MAB as traffic allocation policy, never as statistical evidence, significance, convergence, or a winner signal.
• Enforces Convert's MAB compatibility contract before experience writes: MAB is limited to standard A/B, fullstack A/B, and MVT experiences, and Frequentist MAB requires Sequential. Create/update preflight resolves effective settings before dispatch; historical incompatible states remain visible as anomalies and are never silently rewritten.
• Preserves a positive fixed_mde under dynamic_mde as Convert's persisted automatic-MDE lock; zero or omitted remains unlocked.
• Hardens dynamic-MDE experience updates against legacy raw mode none, which the Management API normalizes to dynamic_mde on reads. On experiences.update, explicit dynamic mode plus a positive lock now fails before dispatch; an already-dynamic experience gets a mode-omitted retry, while a real mode transition gets the guarded zero-then-lock flow. Creation continues to accept the generated API's valid dynamic-lock shape.
• Prefers user-discussed fixed_mde for MCP-authored experience planning, using available analytics to choose a meaningful effect threshold without confusing MDE with expected or observed lift.
• Makes stats authoring self-describing: validation errors enumerate allowed values, stats_type and test_type wire enums are explicit, sequential is identified as a Frequentist test type, the one_tail/two_tails asymmetry is documented, explicit mixed-methodology payloads fail before dispatch, and MAB exploration rates preserve the API's discrete tenths. Current fixed_mde values are identified as relative-percent planning input; updates now read the target experience first and reject positive pre-v11 or unknown-scale values instead of risking a silent legacy-scale conversion. Agents are directed to preflight plan-gated Bayesian, sequential, and MAB changes through accounts.get instead of probing a live experience with writes. Large malformed union payloads now return bounded structured issues instead of multi-megabyte client responses while preserving concise corrective text and the total issue count.
• Normalizes pre-v11 configured-MDE storage carefully, preserves dynamic solver locks in their backend-effective scale, and exposes the same planning state to the model and optional UI.
• Removes deprecated report compatibility blocks and inactive-engine fields from model evidence instead of encouraging contradictory interpretations.
• Forbids models from hand-calculating hypothetical inactive-engine outputs from current counts. Chance-to-win and significance must come from fresh Convert reports under their respective configured lenses.
• Resolves canonical goal definitions through goals.list when embedded experience expansions drift, while resolving scalar primary_goal IDs through the same experience's expanded goals. Incomplete goal-source coverage is reported as unknown evidence instead of a false configuration defect.
• Makes operator evidence internally coherent: project audit and draft QA share one review contract and unambiguous count names; bounded attention-ID samples disclose truncation; no audience is labeled all_visitors; URL-only targeting is a warning rather than a false failure; split URL drafts accept their canonical one-variation shape; unused archived resources remain visible; and deprecated duplicate experiments aliases are removed.
• Rejects unknown namespace wrapper fields before dispatch, so misplaced filters such as query.only cannot be silently ignored. Client-controlled field names and issue counts are bounded, while action-specific recovery guidance identifies the correct wrapper.
• Makes POST-backed history pagination explicit (body.page, never query.page) and rejects a misplaced page before dispatch.
• Follows experience pagination for computed portfolio/audit workflows, returns explicit coverage, and never reports the first 50 rows as a complete project total.
• Compacts every verified operator write workflow to authoritative resource snapshots plus a small status receipt with explicit source provenance. Payload persistence verification stays separate from goal_configuration, which reports archived or unresolved attached goals without encouraging duplicate creates.
• Adds precise guidance for account plans and quotas: use accounts.get with stats after account discovery; detailed billing products remain permission-sensitive.

See Experience Results Semantics for the release contract.

Five Optional MCP Apps

Hosted clients that support MCP Apps can render:

• render_project_portfolio for a minimal attention-first experience scan.
• render_experience_detail for targeting, allocation, variations, measurement, and setup checks.
• render_draft_review for read-only readiness review before any write.
• render_experience_results for a primary-goal-first, engine-aware results digest.
• render_investigation_report for anomalies, evidence gaps, and ordered safe checks.

MCP Apps are presentation, never an evidence path. The model must call and reason from the relevant namespace/operator data action first. Every renderer mirrors its complete sanitized digest into ordinary text content, so hosts without UI support receive the same substantive answer. Render tools cannot create, update, activate, pause, archive, or delete Convert resources.

Beta.14 is the first production candidate for the renamed experience-* MCP App resources. Their current URIs are content-addressed from exact widget HTML and the pinned MCP Apps bridge version. The committed resource history stores each canonical HTML template and host metadata, while a digest-pinned bridge inventory retains every referenced SDK bundle. Future versions therefore advertise new identities while continuing to serve prior content-addressed URIs, retired widget families, and their exact runtime bridge deterministically for each deployment origin. Three fixed *-v2 aliases used by the pre-production Claude/ChatGPT certification remain exact-target compatibility aliases and are locked by tests; other staging-only numbered prototypes are not production contracts.

Staff-Only Browse Impersonation

• Adds request-scoped as_user input only for backend-attested, eligible Convert staff OAuth sessions.
• Requires the exact human-supplied user UUID, a positive account scope, explicit confirmation, and a concrete support reason.
• Remains remote-only, browse-only, audited, and non-persistent.
• Rejects every create, update, activation, pause, archive, and delete path before transport when impersonation is present.
• Does not alter ordinary customer OAuth schemas, grants, permissions, or local API-key behavior.

Runtime, Schema, And API Reliability

• Fixes OpenAPI nullable/composed-schema generation at the source, eliminating null-only and unsatisfiable schemas across audiences, goals, experiences, features, and other operations.
• Refreshes the Management API contract and generates 117 complete standalone Ajv validators. Any compile failure remains a release blocker locally and remotely.
• Fails closed when account scope is ambiguous instead of signing against an arbitrary tenant.
• Makes loose-JSON repair string-literal-aware so embedded JavaScript, CSS, and selectors are not corrupted.
• Reports honest operator status/envelopes and verifies persisted fields before returning verified: true.
• Recognizes only Convert's observed one-way removal of leading/trailing code whitespace across verified custom-code A/B creation, canonical split-URL creation, and scoped variation-code updates; discloses that normalization only after every readback succeeds; and rejects added whitespace, interior changes, or substantive differences. This prevents agents from retrying a successful write while preserving strict code verification.
• Uses bounded polynomial one-to-one matching for variation-change readback, with a 100-change-per-variation operator cap before dispatch. Large API payloads remain available through the direct namespace without risking a post-create Worker CPU failure.
• Makes operator.safe_update_variation_code select the exact persisted custom-code change from the variation, re-read that ID through authoritative experiences.get_change for current code/page/concurrency state, then perform a scoped optimistic-concurrency update. It preserves omitted JS/CSS (including null) except for the disclosed Convert edge-whitespace canonicalization, preserves multipage page binding and sibling content, and requires both an authoritative post-write change readback plus an independent expanded-variation/sibling readback before reporting verified. Ambiguous, incomplete, mismatched, or stale readbacks fail closed without retrying a conflicting write.
• Keeps convert.investigation.v1 backward-compatible for project-scoped and older packets: target.experience remains explicit null, and a missing experience-configuration source state projects to fail-closed unknown rather than breaking strict output-schema validation.
• Suppresses inferential intervals as well as confidence, significance, chance-to-win, and power evidence whenever SRM blocks a result verdict.
• Withholds Bayesian and sequential-Frequentist done under SRM while retaining explicitly labeled Frequentist sample-planning progress as non-verdict context.
• Extends the live matrix to replay a stale pre-update concurrency key against the real API, require a 409, and prove the target and sibling changes remain byte-for-byte unchanged before rollback.
• Re-signs HMAC requests on bounded retries and blocks user overrides of authentication/signing headers.
• Retries only safe/idempotent 429/503 requests by default; unsafe writes are never retried unless explicitly enabled.
• Uses Worker-compatible manual redirect handling and rejects every upstream 3xx without forwarding credentials or replaying OAuth codes.
• Keeps generated delegates inaccessible as direct MCP tools so namespace safety, activation, and destructive confirmation checks cannot be bypassed.

Hosted OAuth, Security, And Observability

• Supports Dynamic Client Registration and HTTPS Client ID Metadata Documents with PKCE.
• Clamps MCP refresh-token lifetime to the upstream Convert token and handles expired upstream sessions explicitly.
• Keeps decrypted Convert bearer credentials only in the OAuth provider's encrypted records and per-request memory. Session Durable Objects persist a strict non-secret subject/capability projection; beta.14 uses reviewed v3 create/rebind and v4 delete deployments to move to a fresh session class and purge the legacy namespace so dormant plaintext prop copies cannot survive.
• Replaces non-atomic hosted rate limiting with a Durable Object limiter while retaining a bounded compatibility fallback.
• Rejects wildcard hosted origin allowlists and centralizes protected edge-header handling.
• Redacts token/session/secret variants, sensitive label-value assignments, request/trace IDs, UUIDs, and unsafe upstream text from model-visible UI payloads and operator warnings.
• Emits privacy-minimized Worker telemetry with bounded event names, status, duration, release, and stable error classes. Tool arguments, results, URLs, headers, OAuth material, account/resource/user IDs, and impersonation targets are excluded.
• Keeps enhanced diagnostics staging-only and limited to validated generated delegate names plus numeric status.
• Hardens the OIDC npm publication workflow against expression injection and uses a single deterministic release build.

Catalog Refresh Without OAuth Rotation

• Advertises listChanged: true for tools, prompts, and resources.
• Fingerprints each hosted catalog and emits request-associated change notifications when it changes.
• Keeps signaling failures advisory so telemetry or notification delivery cannot fail a Convert request.
• Never rotates OAuth clients, grants, KV state, or Durable Object state for a catalog-only deployment.

Beta.14 itself includes one security migration outside that ordinary catalog rule: the legacy MCP transport-session Durable Object class is deleted and replaced. Existing OAuth grants and tokens remain valid, but active transport sessions must initialize once against the new class.

Notifications are advisory because MCP has no acknowledgement for list-change delivery. Claude or ChatGPT may still require an explicit tool/app refresh, administrator review, a new conversation, or app republishing depending on host policy. Those metadata operations should not require Convert OAuth reauthorization.

Knowledge And Developer Experience

• Refreshes the canonical Convert knowledge base to 9,523 chunks across 1,145 URLs: support guidance first, developer contracts second, and public website context third.
• Rebuilds and packages the native vector index; local hybrid semantic/keyword search opens it read-only, while hosted search uses Workers AI plus a corpus-hash-isolated Vectorize index.
• Returns one result per canonical article and preserves every beta.13 documentation ID through an exact-content alias or an explicit stale-document response; changed content never resolves through a fuzzy alias.
• Adds 15 lexical-suitable and 19 native-hybrid source-aware retrieval probes spanning realistic Support, Management API/SDK, pricing, and compliance questions.
• Blocks hosted deployment unless every current chunk is verified in the exact Vectorize namespace, the feedback D1 migration is present, and a live Workers AI embedding passes the environment-specific preflight.
• Adds operator.prepare_feedback plus consent-bound operator.submit_feedback: arbitrary structured context is recursively sanitized, prepared without storage, bound to an exact user-approved digest, and stored only in the environment's isolated feedback database. Preparation exposes the sanitized summary, bounded context outline, byte count, digest, and an explicit review contract; context values are intentionally not re-echoed into the conversation. Browse-only staff impersonation may prepare a sanitized preview but cannot submit or attribute feedback as the customer. Local feedback never forwards Convert credentials.
• Adds a pinned official MCP Inspector wrapper for local and hosted catalog, OAuth, prompt, resource, and tool-call inspection.
• Adds a sanitized registry of 199 historical QA intents so known regressions remain represented without copying customer payloads, identifiers, URLs, outcomes, or secrets.
• Disables hosted SSE response replay so tool results, including newly created credential values, are never persisted in Durable Object event storage. Interrupted streams restart instead of resuming from Last-Event-ID.
• Expands the deterministic gate with generator tests, generated drift, typecheck, validators, unit/fixture tests, registry/schema-risk audits, QA intents, vectors, stdio smoke, protocol conformance, installed-package proof, hosted config checks, and both Worker dry-runs.

Compatibility And Upgrade Behavior

The npm tarball grows from the beta.13 baseline because the refreshed 9,523-chunk semantic vector store is intentionally included. Canonical npm pack proof confirms that the vector files and optional semantic runtimes install normally, while remote Worker, OAuth bridge, Durable Object, and MCP Apps implementation files remain excluded. The package also retains its deliberate keyword fallback when a downstream installer explicitly omits optional dependencies.

Verification Evidence

Completed on the final pre-deployment candidate tree:

• Full server suite: 929 tests across 48 suites passed under the release gate.
• Hosted remote subset: 314 tests across 15 suites passed.
• Generator suite: 11 tests passed.
• 117 standalone tool validators generated and verified complete.
• All generated registry/schema-risk checks passed.
• All 199 historical QA intents accounted for exactly once.
• MCP 2025-11-25 conformance passed with compiling input/output schemas, all 20 prompts retrieved successfully, canonical search/fetch, and the readable investigation playbook.
• Native vector proof opened all 9,523 chunks read-only.
• Canonical npm tarball proof passed for 96 files, approximately 72.7 MiB unpacked, including installed-binary launches with and without optional dependencies. A normal optional-enabled install loaded both semantic runtimes, opened the packaged 9,523-chunk vector store read-only, and returned vector results.
• The installed consumer audit is clean when optional semantic dependencies are omitted. The optional text-embedding runtime currently inherits two reviewed upstream advisories: a sharp image-decoding advisory and an adm-zip archive advisory used only by ONNX's vendor-binary install script. Neither path accepts MCP request data. The package gate fails on every new advisory/package/severity or unreviewed version drift while allowing reviewed findings to disappear when upstream publishes a compatible fix.
• Local real API smoke passed through both the repository build and a freshly installed npm tarball for account/project/experience reads, docs search/fetch, prompts/resources, and a read-only operator action.
• Official Inspector live evidence confirmed that collection reads without variations.changes expansion return scalar change IDs, and the operator counts those persisted changes correctly without loading their full code bodies.
• The deterministic release gate, staging and production Worker dry-runs, generated two-phase bridge dry-runs, and package boundary checks passed.
• The Worker dry-run packaged 26 static assets and an approximately 2.01 MiB gzipped upload for both hosted environments without changing their bindings or OAuth configuration.
• The broad live matrix classified all 117 generated/operator actions with zero policy mismatches, exercised 63 reads, safely skipped 54 mutations outside dedicated scenarios, and passed every non-destructive protocol, schema, guardrail, authoring, persistence, concurrency, rollback, and operator assertion. Permanent deletion certification remained intentionally incomplete because the non-interactive run cannot manufacture the required exact second confirmations; all temporary experiences were archived instead.
• The public staging favicon responds correctly; third-party hostname favicon caches may update asynchronously.
• Staging exercised the real Cloudflare migration sequence: bridge version 8d11d191-99b5-4a29-b40b-c252c4cef5ba applied v3, canonical version 9e94ed70-3fcf-4efa-b809-b828445e6bf6 completed v4, and the stored OAuth grant continued to authorize the 45-tool catalog afterward. Production deployment history remains on the pre-beta.14 Worker (f3f52de6-9092-45d4-bd03-113328608386, deployed 2026-06-23), so production has not recorded v3.

Historical Claude and ChatGPT certification exercised the earlier 43-tool intermediate candidate across reads, writes with independent readback/rollback, delete guards, OAuth continuity, resources, and renderers. The final 45-tool candidate adds the engine-aware results and investigation views plus subsequent evidence hardening.

Final Promotion Gate

Before production deployment or npm publication:

1. Deploy beta.13 to staging and connect an authenticated Claude/ChatGPT client.
2. Upgrade the same staging Worker and session to this exact beta.14 candidate.
3. Verify OAuth continuity, catalog refresh behavior, 45 tools, six resources, all five renderers, one normal read, docs search/fetch, and no unexplained enhanced-diagnostic errors.
4. Record production beta.13 health/version before promotion.
5. Confirm production is still on beta.13 with no applied v3 migration, then deploy only through yarn deploy:remote:production, without changing OAuth clients, callbacks, KV grants, or selected scopes. The reviewed deploy wrapper applies v3 create/rebind and then v4 legacy-namespace deletion when Cloudflare requires the two-phase bridge. Once the bridge deployment applies v3, beta.13 is no longer a valid rollback target; the remainder of that window is fix-forward and the canonical deploy must complete v4.
6. Run production synthetic checks plus one authenticated read-only proof.
7. Publish the GitHub release/npm package only through the existing release workflow, then verify npm dist-tags and an installed @latest binary.

Production deployment, npm publication, and directory submission are intentionally outside this prepared release note until their evidence exists.

Release Commands

yarn install --immutable
yarn test:release
yarn test:real
yarn test:remote:synthetic --base-url https://convert-mcp.stellary.io --profile hosted --environment staging --edge-auth false

The mutating live scenario matrix remains restricted to an approved test project and retains the exact-resource, explicit-request, second-confirmation delete contract.

Production Promotion Evidence

Production was promoted from beta.13 to this exact commit, 2fecf713cbdf7b193b1bba387a8b64e539df7686, only after the deterministic release gate and production storage preflights passed.

• Production Worker: f239b1d7-4cd4-4d39-8d99-4728c6ede23f at https://mcp.ai.app.convert.com/mcp.
• Cloudflare's required two-phase Durable Object migration completed through reviewed bridge version d91ecbbd-a44f-4716-920d-4df822e753d2, then the canonical deployment completed legacy namespace deletion.
• The production Vectorize namespace contains all 9,523 current knowledge chunks for corpus 6a65be5c9997a6e0048faf3472130129bd9c871ab3c75b573eb63728634ba8ea; the production feedback D1 migration and live 384-dimension Workers AI embedding preflight passed.
• Production synthetic checks passed for health, OAuth protection, Client ID Metadata Documents, and MCP App asset compatibility.
• Official MCP Inspector authenticated against production and confirmed 45 tools, 20 prompts, six resources, canonical documentation search/fetch, grant-aware account/project reads, experience reads with goals, project audit, and convert.investigation.v1.
• Live fail-closed checks rejected a read sent to a write tool, blocked an unconfirmed destructive delete before transport, and rejected an unknown namespace wrapper field without calling Convert.
• Feedback preparation stored nothing, did not echo structured context values, and removed credential-shaped and UUID test values. No feedback was submitted.
• The existing Claude production connector completed new account, project, search, and fetch calls after deployment without OAuth reauthorization. The OAuth client, callback, grant KV, and selected account/project scope were unchanged.
• Production root metadata, favicon, 512-pixel icon, OAuth resource metadata, and health endpoint all return successfully with restrictive CSP and no-store protection where appropriate.
• GitHub Release Gate run 31544634451 passed for the release commit.

The GitHub release publication starts the repository's OIDC npm workflow. Publication is considered complete only after the workflow succeeds, npm latest resolves to 0.0.1-beta.14, and a fresh installed @latest stdio binary passes its local 16-tool proof.

npm Publication Evidence

• The OIDC publication workflow 31547591006 completed successfully after rerunning the deterministic release gate from the immutable tag.
• npm now resolves @convertcom/mcp-server@latest to 0.0.1-beta.14.
• A clean consumer project installed @latest from the public registry through the package-manager shim, confirmed the packaged vector store, loaded semantic retrieval over all 9,523 chunks, passed the real Convert API smoke, and advertised exactly the unchanged 16-tool local stdio catalog.

MCP Server v0.0.1-beta.13

Release target: production-ready local stdio package after the remote MCP parity hardening work. The npm package remains the customer-facing local MCP server, while the same private repo can also deploy the hosted Cloudflare Worker remote MCP.

Highlights

• Preserves the beta.12 npm startup fix and package proof for npx -y @convertcom/mcp-server@latest, node_modules/.bin/convert-mcp, and Windows package shims.
• Keeps the public npm package local-stdio only: private Worker runtime files remain excluded from the packed package.
• Adds public README guidance for the hosted remote MCP URL while keeping internal Cloudflare/OAuth deployment details out of npm-facing docs.
• Ships the shared local/remote MCP runtime with strict parity: same namespace schemas, prompts, operator workflows, output envelopes, guardrails, and OpenAI-compatible search / fetch.
• Keeps generated OpenAPI validators precompiled so Cloudflare Workers do not rely on runtime Ajv code generation.
• Keeps delete actions behind explicit destructive metadata and runtime enforcement: exact user request plus second confirmation with resource summary is required before any namespace delete can dispatch.
• Keeps the production remote landing page, brand assets, favicon routes, OAuth metadata, human /mcp redirect handling, and staging noindex behavior in the shared codebase.
• Keeps Claude-compatible remote OAuth refresh behavior: initial authorization-code exchange may set refresh-token TTL; refresh-token exchanges do not return refreshTokenTTL.

Release Readiness Evidence

Completed locally on 2026-06-23 before tagging:

• yarn install --immutable: passed with existing peer warnings only.
• yarn test:release: passed.
  • Generated tools in sync.
  • 113 standalone Ajv validators generated.
  • Jest: 14 suites, 242 tests passed.
  • Registry drift: 113 generated operations, 97 curated mappings, 16 intentionally unexposed, no unmapped operations.
  • Schema-risk gate: 23 classified findings, no unknowns, no missing runtime overrides/fixtures/guardrails.
  • Vector store: 5,797 chunks, read-only Zvec probe succeeded.
  • Conformance: MCP 2025-11-25, 14 namespace tools, all input/output schemas draft 2020-12 and compiling, 19 prompts, canonical search / fetch, no search_knowledge_base.
  • Package proof: 87 files, 35.3 MiB unpacked; install-from-tarball binary smoke passed for convertcom-mcp-server-0.0.1-beta.13.tgz.
• yarn test:remote: passed.
  • Staging and production Worker dry-runs passed with expected bindings.
  • Remote Worker tests: 2 suites, 13 tests passed.
• yarn test:real: passed against production Convert API.
• CONVERT_BASE_URL=https://api.app-staging.convert.com/api/v2 yarn test:real: passed against staging Convert API.
• Manual local stdio JSON-RPC smoke: passed for initialize, tools/list, prompts/list, docs search / fetch, accounts.list, projects.list, and destructive delete guardrail.
• MCP_MATRIX_BROAD_SWEEP=1 node scripts/mcp-live-scenario-matrix.mjs: passed against Karim's dev project.
  • Iqbal custom-code and split-URL regex flows passed with readback and cleanup.
  • Operator create/update workflows passed with readback and cleanup.
  • Audience/location rules, goal variants, MDE locks, visual-editor/outlier field shapes, and delete checks passed.
  • Broad namespace sweep completed with only expected permission, missing-path, validation, and plan-gated MAB responses.

Run before tagging:

yarn install --immutable
yarn test:release
yarn test:remote
yarn test:real
CONVERT_BASE_URL=https://api.app-staging.convert.com/api/v2 yarn test:real
MCP_MATRIX_BROAD_SWEEP=1 node scripts/mcp-live-scenario-matrix.mjs

Manual MCP client evidence required before publish:

• Local stdio JSON-RPC smoke: initialize, tools/list, search, fetch, accounts.list, projects.list, and delete guardrail.
• Remote staging client smoke against https://convert-mcp.stellary.io/mcp: search, fetch, accounts, projects, experiences.list, and read-only operator actions.

Release Plan

1. Confirm npm latest is still 0.0.1-beta.12.
2. Commit beta.13 version metadata and release notes to main.
3. Wait for the GitHub Release Gate push workflow to pass on main.
4. Create and push the annotated tag:
   Bash

   git tag -a v0.0.1-beta.13 -m "v0.0.1-beta.13"
   git push origin v0.0.1-beta.13

5. Create a normal GitHub Release for v0.0.1-beta.13 using these notes. Do not mark it as draft or prerelease.
6. The Publish Package to npmjs workflow will run on release publication, validate the tag/version match, run yarn test:release, and publish @convertcom/[email protected] to npm with the latest tag.
7. Verify after publish:
   Bash

   npm view @convertcom/mcp-server dist-tags versions --json

8. Only after npm is verified, deploy the production remote Worker:
   Bash

   yarn deploy:remote:production

MCP Server v0.0.1-beta.12

Release target: replacement for withdrawn 0.0.1-beta.11, with the npm/npx binary startup fix, refreshed knowledge/vector package, and the internal staging/dev auth foundations from beta.11.

Why beta.12

0.0.1-beta.11 was published and then withdrawn after Claude failed to start the server through the npm package binary path (npx -y @convertcom/mcp-server@latest). npm package versions are immutable after publish/unpublish, so the replacement release must use a new version: 0.0.1-beta.12.

Highlights

• Fixed npm package binary startup by resolving real paths before deciding whether src/index.ts is the main entrypoint.
• Extended package smoke to launch the installed package binary (node_modules/.bin/convert-mcp, or convert-mcp.cmd on Windows), matching the npx/Claude failure mode instead of only testing node build/index.js.
• Added durable operator notes for npm immutability, rollback/dist-tag handling, and binary-shim startup testing.
• Refreshed packages/server/data/convert-kb.json from the canonical assistant HubSpot export.
• Rebuilt the semantic vector store for 5,797 knowledge chunks.
• Preserved required empty Zvec segment directories with tracked .gitkeep files so git/npm packaging keeps the vector store openable.
• Tightened yarn test:vectors and package smoke so missing packaged vector segment directories fail release validation instead of shipping a broken search index.
• Retains beta.11's internal CONVERT_BASE_URL support, typed auth-context plumbing, private remote runtime scaffolding, and public npm package boundary.

Release Readiness Evidence

Run before tagging:

yarn install --immutable
yarn build
yarn workspace @convertcom/mcp-server test --runInBand
yarn test:smoke
yarn test:conformance
yarn test:package
yarn test:vectors
CONVERT_DISABLE_SEMANTIC_KB=1 yarn test:release
yarn test:real
CONVERT_BASE_URL=https://api.app-staging.convert.com/api/v2 yarn test:real

Manual pre-release check must use the npm-style binary path that failed in beta.11:

1. Pack and install the local tarball into a temporary project.
2. Launch node_modules/.bin/convert-mcp or Windows convert-mcp.cmd.
3. Verify MCP initialize, tools/list, docs search / fetch, and accounts.list with Convert credentials.

Release Plan

1. Keep npm latest on 0.0.1-beta.10 until all validation and manual package-bin testing pass.
2. Commit beta.12 version metadata, release docs, binary fix, and refreshed knowledge/vector artifacts to main.
3. Wait for the GitHub Release Gate push workflow to pass on main.
4. Create and push the annotated tag:
   Bash

   git tag -a v0.0.1-beta.12 -m "v0.0.1-beta.12"
   git push origin v0.0.1-beta.12

5. Create a normal GitHub Release for v0.0.1-beta.12 using these notes. Do not mark it as draft or prerelease.
6. The Publish Package to npmjs workflow will run on release publication, validate the tag/version match, run yarn test:release, and publish @convertcom/[email protected] to npm with the latest tag.
7. Verify after publish:
   Bash

   npm view @convertcom/mcp-server dist-tags versions --json

MCP Server v0.0.1-beta.10

Release target: Convert MCP server beta hardening for fast-changing Convert API schemas, OpenAI-compatible MCP clients, prompt-first workflow intelligence, and the manual regression blockers found before release.

Highlights

• Regenerated convert-OA3.yaml from the latest backend MCP OpenAPI build and regenerated packages/server/src/tools.ts.
• Added curated namespace mappings for latest backend operations: account billing portal and experience heatmap background/overlay.
• Replaced legacy docs search with OpenAI-compatible search and fetch tools; search_knowledge_base is no longer advertised.
• Refreshed the packaged Convert support knowledge base from the latest assistant HubSpot export: 5,776 chunks across 500 article URLs.
• Committed the rebuilt semantic vector index so packaged search starts hybrid, not keyword-only.
• Added MCP prompt support with 19 curated prompts for Convert experimentation workflows, implementation debugging, and experiment building.
• Added one compact operator namespace with reporting/audit actions plus verified write workflows.
• Added cached project defaults inference for goals, audiences, locations, URL patterns, traffic splits, and naming patterns.
• Kept documentation search hybrid by opening the packaged Zvec index through a temporary runtime copy, avoiding package mutation and keyword-only fallback.
• Moved the auto-placeholder experience-change schema fix into the generator so generated tools.ts carries discriminated defaultRedirect and richStructure schemas.
• Fixed runtime schema normalization for audiences.create / audiences.update so non-null nested rules payloads validate and dispatch.
• Fixed runtime schema normalization for locations.create / locations.update so URL/page targeting rules validate and dispatch.
• Fixed runtime schema normalization for goals.create / goals.update around real Convert goal types: clicks_element, code_trigger, dom_interaction, scroll_percentage, advanced, ga_import, plus triggering_rule.
• Fixed runtime schema normalization for features.create / features.update so typed variable defaults such as boolean false and numeric values validate instead of colliding with generated null-only base branches.
• Added UnsupportedInlineSiteArea guardrail for experiences.create / experiences.update when body.site_area is present, because the API can return success while persisting site_area: null.
• Added ClicksLinkHrefMustBeString guardrail for clicks_link goals when settings.href is a match object. Convert currently accepts string href values only; agents should use triggering_rule for page scoping or create multiple link goals.
• Fixed multipart screenshot uploads by preserving multipart/form-data schemas, building real FormData, signing pass-through bodies as Convert expects, and verifying readback when the API reports a post-persistence 500.
• Added CONVERT_HTTP_HEADER_* passthrough with auth/signing header override protection.
• Added bounded retry/backoff for 429/503 responses while avoiding unsafe write retries by default.
• Added flow fixtures for Iqbal custom-code A/B creation, split URL regex settings, variation updates, goals, audiences, locations, project audit, and guardrail payloads.
• Added registry drift enforcement so new backend operations must be curated or intentionally allowlisted.
• Added a schema-risk release gate that fails on newly introduced unclassified null-only request-body properties, missing runtime overrides, missing fixtures, or missing guardrails.
• Extended the mutating live scenario matrix with exact Iqbal custom-code, split URL regex, BeNeLux audience/location, broad namespace, write/readback/rollback, and cleanup flows.
• Added npm package proof and install-from-tarball smoke to the release gate.
• Hardened GitHub release automation so the release gate uses the canonical yarn test:release command and the publish workflow checks out the exact release tag before publishing.

Release Readiness Evidence

• Local yarn test:release: passed.
• Local CI=true CONVERT_DISABLE_SEMANTIC_KB=1 yarn test:release: passed, matching GitHub runner semantics.
• Local yarn test:vectors: passed with native read-only Zvec open.
• Local yarn test:conformance: passed with semantic KB ready, 5,776 chunks loaded.
• GitHub Release Gate: passing on main before release creation.
• Unit/fixture suite: 196/196 tests passed.
• Package proof: 61 files, 19.2 MiB unpacked, install-from-tarball MCP smoke passed.

Required Preflight

cp ../assistant/scripts/kb/hubspot_kb_output/hubspot_kb_part_1.json packages/server/data/convert-kb.json
yarn workspace @convertcom/mcp-server build:vectors
yarn test:vectors
yarn test:release
yarn test:schema-risk
yarn test:real
node scripts/mcp-live-scenario-matrix.mjs
MCP_MATRIX_BROAD_SWEEP=1 node scripts/mcp-live-scenario-matrix.mjs

yarn test:release runs generated-tools drift, build, lint, unit/fixture tests, registry drift, schema-risk, vector-store structure checks, stdio smoke, protocol conformance, npm tarball proof, and install-from-tarball smoke. Local yarn test:vectors also opens the committed semantic vector index natively; CI verifies package structure and skips native Zvec open because the optional native runtime is runner-sensitive. yarn test:real and scripts/mcp-live-scenario-matrix.mjs prefer process env / local .env credentials and honor CONVERT_ACCOUNT_ID / CONVERT_PROJECT_ID target IDs. The matrix creates temporary draft experiences and archives them after verification. Set MCP_MATRIX_BROAD_SWEEP=1 only when intentionally running the broad namespace sweep.

MCP Server v0.0.1-beta.9

Highlights

• Fix namespace tool argument normalization for Claude Code and other MCP clients that flatten or stringify path/body fields.
• Harden npm publish to install immutably from the committed yarn.lock.
• Pin axios to 1.13.5 to avoid dependency drift during release builds.
• Sync release and workspace docs with the actual publish flow.

MCP Server v0.0.1-beta.8

Beta 8 release for Convert MCP server.

Changes:

• MCP robustness and cross-client compatibility improvements
• Better validation and actionable error responses for LLM self-correction
• Safety guardrails and improved tool schemas for all namespaces

Validation:

• yarn workspace @convertcom/mcp-server test
• yarn test:smoke
• yarn test:real
• yarn test:conformance

MCP Server v0.0.1-beta.7

What's New

AI Agent Usability Overhaul

• Auto-extracted body schema hints — agents now see valid enums and required fields for every write endpoint, extracted automatically from the OpenAPI spec
• Hand-curated ACTION_NOTES — working examples, gotcha warnings, and required field hints for the trickiest endpoints (experiences, locations, audiences, hypotheses, etc.)
• Error response hints — when an action fails, the error now includes contextual guidance so agents self-correct on retry

Tool Discoverability Fix

• Rewrote SERVER_INSTRUCTIONS so MCP clients (Claude Desktop, ChatGPT, etc.) correctly reach for the 13 namespace API tools instead of only using search_knowledge_base
• All namespace descriptions now clearly indicate direct API access to the user's Convert.com account

Embedded Knowledge Base (Hybrid Search)

• MiniSearch (BM25 keyword) + Zvec (semantic vector store) with Reciprocal Rank Fusion
• The server can now answer Convert platform questions and guide users through concepts without external docs

Shutdown Crash Fix

• Fixed SIGABRT on shutdown when semantic search init partially loads native modules but falls back to keyword-only mode
• Smoke tests now validate clean shutdown (catch abnormal exits)

Other

• Dynamic account ID discovery in real API smoke test (no more hardcoded IDs)
• MCP spec-compliant tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
• Updated OpenAPI spec and dependency refresh

Test Evidence

• 123 unit tests passing (action-notes, annotations, RRF fusion)
• Stdio smoke test passing (14 tools, clean shutdown)
• Live API smoke test passing (accounts → projects → experiences chain)

MCP Server v0.0.1-beta.6

What's Changed

• 🔒 Removed repository links from package.json (private repository)
• npm page will no longer show GitHub repository/homepage links

This is a metadata-only update. All features from v0.0.1-beta.5 remain unchanged.

Installation

Configure in your MCP client:

{
  "mcpServers": {
    "convert": {
      "command": "npx",
      "args": ["-y", "@convertcom/mcp-server@latest"],
      "env": {
        "CONVERT_API_KEY": "your_application_id",
        "CONVERT_API_SECRET": "your_secret_key",
        "TOOLS_FOR_CLIENT": "reporting"
      }
    }
  }
}

MCP Server v0.0.1-beta.5

What's Changed

• 📝 Simplified README - Removed installation options section (users only interact via MCP clients)
• 🎨 Removed logo - Logos don't display on npm, cleaner presentation
• 📚 Streamlined documentation - Focus on client integration and usage

This is a documentation-only update. All features from v0.0.1-beta.4 remain unchanged.

Installation

Configure in your MCP client:

{
  "mcpServers": {
    "convert": {
      "command": "npx",
      "args": ["-y", "@convertcom/mcp-server@latest"],
      "env": {
        "CONVERT_API_KEY": "your_application_id",
        "CONVERT_API_SECRET": "your_secret_key",
        "TOOLS_FOR_CLIENT": "reporting"
      }
    }
  }
}

See the README for full documentation.

MCP Server v0.0.1-beta.4

What's New

• ✨ Beautiful new README with logos, badges, and professional formatting
• 📚 Enhanced documentation with model recommendations (Claude Sonnet 4.5, GPT-5)
• 🔍 Built-in knowledge base with 5,279+ indexed chunks from Convert support docs
• 🛡️ Improved security best practices and clear access level guidance
• 🎯 Updated example prompts showing real-world use cases organized by category
• 🔧 GitHub Actions workflow for automated npm publishing
• 📖 Comprehensive API coverage section highlighting all capabilities
• 🚀 Release process documentation for maintainers

Installation

npx -y @convertcom/mcp-server@latest

Documentation

See the README for full documentation, including:

• Quick start guide
• Client integration (Claude Desktop, Cursor, and more)
• Detailed namespace documentation with all available actions
• Example prompts for common tasks
• Troubleshooting tips

Note: This replaces the outdated 0.0.1-beta.3 documentation with a completely redesigned README.

MCP Server v0.0.1-beta.3

What's New

• ✨ Beautiful new README with logos and badges
• 📚 Enhanced documentation with model recommendations (Claude Sonnet 4.5, GPT-5)
• 🔍 Built-in knowledge base with 5,279+ indexed chunks from Convert support docs
• 🛡️ Improved security best practices
• 🎯 Updated example prompts showing real-world use cases
• 🔧 GitHub Actions workflow for automated npm publishing
• 🐛 Fixed GitHub Actions workflow authentication and build process

Installation

npx -y @convertcom/mcp-server@latest

See the README for full documentation.

MCP Server v0.0.1-beta.2

What's New

• ✨ Beautiful new README with logos and badges
• 📚 Enhanced documentation with model recommendations (Claude Sonnet 4.5, GPT-5)
• 🔍 Built-in knowledge base with 5,279+ indexed chunks from Convert support docs
• 🛡️ Improved security best practices
• 🎯 Updated example prompts showing real-world use cases
• 🔧 GitHub Actions workflow for automated npm publishing

Installation

npx -y @convertcom/mcp-server@latest

See the README for full documentation.