@zackbart/connecta 0.22.1 → 0.22.3

package/dist/providers/vercel.d.ts

@@ -1,25 +1,44 @@
 import type { Connector, ConnectorCallAdmissionPolicy } from "../types.js";
 /** Vercel's public REST origin. Override only for a proxy or test double. */
 export declare const VERCEL_API_BASE_URL = "https://api.vercel.com";
-export interface VercelOptions {
-    /** Human-readable display name; defaults to "Vercel". */
+/** Vercel's official hosted MCP endpoint. */
+export declare const VERCEL_MCP_ENDPOINT = "https://mcp.vercel.com";
+interface VercelCommonOptions {
+    /** Human-readable display name; defaults identify the selected surface. */
     title?: string;
     /** Downstream auth ownership. Defaults to one shared deployment grant. */
     authScope?: "shared" | "personal";
     /** Which Vercel account or team this connection operates, and for whom. */
     purpose: string;
-    /** Default team id for scoped calls. Omit to use the token's personal account. */
-    teamId?: string;
     /** Account-specific conventions appended to the maintained provider guide. */
     instructions?: string;
-    /** API base override for a proxy or test double. */
-    baseUrl?: string;
-    /** Default page size for list tools. Defaults to 20; Vercel's local cap is 100. */
-    defaultPageSize?: number;
     /** Optional per-runtime downstream call-admission policy. */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
 }
-/** A maintained Vercel connection over the public REST API. */
-export declare function vercel(id: string, options: VercelOptions): Connector;
+/** Connecta's maintained hand-written Vercel REST surface. */
+export interface VercelApiOptions extends VercelCommonOptions {
+    /** Omit for backward compatibility; the hand-written API surface is the default. */
+    surface?: "api";
+    /** Default team id for scoped calls. Omit to use the token's personal account. */
+    teamId?: string;
+    /** API base override for a proxy or test double. */
+    baseUrl?: string;
+    /** Default page size for list tools. Defaults to 20; Vercel's local cap is 100. */
+    defaultPageSize?: number;
+}
+/** Vercel's official hosted MCP surface, authenticated through OAuth. */
+export interface VercelMcpOptions extends VercelCommonOptions {
+    surface: "mcp";
+}
+/** Backward-compatible API options; existing consumers may extend this interface. */
+export interface VercelOptions extends VercelApiOptions {
+}
+/** Select one Vercel surface when deployment configuration constructs it. */
+export type VercelConnectionOptions = VercelOptions | VercelMcpOptions;
+/** Release-reviewed Vercel MCP inventory and safety verdicts. */
+export declare const VERCEL_MCP_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
+/** A maintained Vercel connection using the selected provider surface. */
+export declare function vercel(id: string, options: VercelConnectionOptions): Connector;
+export {};

package/dist/providers/vercel.js

@@ -1,10 +1,14 @@
 /** See documentation/vercel.md#no-sdk-on-purpose. */
-import { api } from "../connectors/api.js";
+import { api, defined } from "../connectors/api.js";
+import { remoteMcp } from "../connectors/remote-mcp.js";
+import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { guardedFetch, retryAfterMs, } from "../connectors/guarded-fetch.js";
 import { ConnectorCallError } from "../errors.js";
 import { withDeadline } from "../timeout.js";
 /** Vercel's public REST origin. Override only for a proxy or test double. */
 export const VERCEL_API_BASE_URL = "https://api.vercel.com";
+/** Vercel's official hosted MCP endpoint. */
+export const VERCEL_MCP_ENDPOINT = "https://mcp.vercel.com";
 const MAX_PAGE_SIZE = 100;
 const DEFAULT_PAGE_SIZE = 20;
 const VERCEL_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
@@ -755,7 +759,7 @@ function tools(send, defaultPageSize, defaultTeamId) {
                                 type: { type: "string" }, createdAt: { type: "number" },
                                 message: { type: "string" }, payload: { type: "object" },
                             },
-                            required: ["type", "createdAt"],
+                            required: ["type"],
                         },
                     },
                 },
@@ -776,7 +780,8 @@ function tools(send, defaultPageSize, defaultTeamId) {
                     const event = asRecord(value);
                     const eventPayload = asRecord(event["payload"]);
                     return compact({
-                        type: event["type"], createdAt: event["created"] ?? event["date"],
+                        type: event["type"] ?? "unknown",
+                        createdAt: event["created"] ?? event["date"],
                         message: eventPayload["text"] ?? eventPayload["message"],
                         payload: Object.keys(eventPayload).length === 0 ? undefined : eventPayload,
                     });
@@ -1029,7 +1034,7 @@ function tools(send, defaultPageSize, defaultTeamId) {
         },
     ];
 }
-function usageGuide(purpose, teamId, instructions) {
+function apiUsageGuide(purpose, teamId, instructions) {
     const accountInstructions = instructions?.trim();
     return `# Vercel usage
 
@@ -1079,12 +1084,104 @@ ${accountInstructions
         ? `\n## Account instructions\n\n${accountInstructions}\n`
         : ""}`;
 }
-/** A maintained Vercel connection over the public REST API. */
-export function vercel(id, options) {
-    const purpose = options.purpose.trim();
-    if (!purpose) {
-        throw new Error("vercel() requires a non-empty account purpose.");
-    }
+/** Reads reviewed against Vercel's official MCP tool reference. */
+const MCP_READ_ONLY_TOOLS = new Set([
+    "search_vercel_documentation",
+    "list_teams",
+    "list_projects",
+    "get_project",
+    "list_deployments",
+    "get_deployment",
+    "get_deployment_build_logs",
+    "get_runtime_logs",
+    "get_runtime_errors",
+    "get_web_analytics",
+    "list_agent_run_projects",
+    "list_agent_runs",
+    "get_agent_run",
+    "get_agent_run_trace",
+    "check_domain_availability_and_price",
+    "get_purchase_quote",
+    "get_domain_order",
+    "list_toolbar_threads",
+    "get_toolbar_thread",
+    // Returns CLI guidance. Any later CLI execution is outside this MCP call.
+    "use_vercel_cli",
+]);
+/** Writes reviewed against Vercel's official MCP tool reference. */
+const MCP_WRITE_TOOLS = new Map([
+    // These only append state.
+    ["reply_to_toolbar_thread", "additive"],
+    ["add_toolbar_reaction", "additive"],
+    // Deploying to production, billing, access grants, imports, and edits can
+    // all change existing state, even where the provider uses a create verb.
+    ["deploy_to_vercel", "destructive"],
+    ["buy_pro", "destructive"],
+    ["buy_credits", "destructive"],
+    ["buy_addon", "destructive"],
+    ["buy_domain", "destructive"],
+    ["get_access_to_vercel_url", "destructive"],
+    // A GET against application code is not guaranteed to be observational.
+    ["web_fetch_vercel_url", "destructive"],
+    ["import-claude-design-from-url", "destructive"],
+    ["change_toolbar_thread_resolve_status", "destructive"],
+    ["edit_toolbar_message", "destructive"],
+]);
+/** Release-reviewed Vercel MCP inventory and safety verdicts. */
+export const VERCEL_MCP_VETTED_CATALOG = vettedCatalog({
+    reads: MCP_READ_ONLY_TOOLS,
+    writes: MCP_WRITE_TOOLS,
+});
+function mcpUsageGuide(purpose, instructions) {
+    const accountInstructions = instructions?.trim();
+    return `# Vercel MCP usage
+
+Official MCP surface: tool names, descriptions, argument schemas, and result
+schemas come from Vercel's live server. Connecta preserves that catalog and
+only fills in release-reviewed safety annotations when Vercel leaves them out.
+
+Account purpose: ${purpose}
+
+- Discover the live catalog before assuming a tool exists. Vercel can change
+  the surface independently of a Connecta release, and account features may
+  affect what the authorization can reach.
+- Resolve team, project, deployment, run, thread, and order ids with the list
+  and get tools. Do not guess opaque ids.
+- Diagnose deployments with \`get_deployment\`, then build logs, runtime error
+  clusters, and runtime logs. Narrow time windows before raising result limits.
+- Purchase tools change billing. Read a quote first and carry its price,
+  idempotency key, and requested term into the confirmed purchase unchanged.
+- \`get_access_to_vercel_url\` creates a temporary access grant. Treat the URL
+  it returns as a credential and do not expose it outside the requested task.
+- \`deploy_to_vercel\` and \`import-claude-design-from-url\` can create or update
+  live projects. Read the target and deployment mode before approving them.
+- An \`auth_required\` failure means this connector's OAuth grant is missing or
+  expired. Run \`authorize_connector\` for this connector id, then retry.
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
+function vercelMcp(id, purpose, options) {
+    const connector = remoteMcp(id, {
+        url: VERCEL_MCP_ENDPOINT,
+        ...defined({
+            authScope: options.authScope,
+            callAdmission: options.callAdmission,
+            maxResultBytes: options.maxResultBytes,
+        }),
+        title: options.title ?? "Vercel (MCP)",
+        description: `Vercel's official hosted MCP surface: ${purpose}`,
+        auth: { type: "oauth" },
+        requireHttps: true,
+        usageGuide: {
+            content: mcpUsageGuide(purpose, options.instructions),
+            summary: "Official MCP. Live Vercel schemas, id resolution, deployment diagnosis, purchases, and access grants.",
+            required: true,
+        },
+    });
+    return withVettedCatalog(connector, VERCEL_MCP_VETTED_CATALOG);
+}
+function vercelApi(id, purpose, options) {
     const defaultPageSize = options.defaultPageSize ?? DEFAULT_PAGE_SIZE;
     if (!Number.isInteger(defaultPageSize) ||
         defaultPageSize < 1 ||
@@ -1117,7 +1214,7 @@ export function vercel(id, options) {
             }
         },
         usageGuide: {
-            content: usageGuide(purpose, teamId, options.instructions),
+            content: apiUsageGuide(purpose, teamId, options.instructions),
             summary: "Team scoping, deployment diagnosis, value-safe environment variables, REST hatches, and cursor pagination.",
             required: true,
         },
@@ -1130,3 +1227,13 @@ export function vercel(id, options) {
             : {}),
     });
 }
+/** A maintained Vercel connection using the selected provider surface. */
+export function vercel(id, options) {
+    const purpose = options.purpose.trim();
+    if (!purpose) {
+        throw new Error("vercel() requires a non-empty account purpose.");
+    }
+    return options.surface === "mcp"
+        ? vercelMcp(id, purpose, options)
+        : vercelApi(id, purpose, options);
+}

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.22.1";
+export declare const CONNECTA_VERSION = "0.22.3";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.22.1";
+export const CONNECTA_VERSION = "0.22.3";

package/documentation/cloudflare.md

@@ -1,20 +1,20 @@
 # Cloudflare prebuilt connection
 
 Import `cloudflare()` independently from
-`@zackbart/connecta/providers/cloudflare`. It is a deliberate, hand-written
-surface over Cloudflare's v4 REST API. Fifty-one tools combine ergonomic,
-fully described operations for common work with three guarded escape hatches
-for the rest of Cloudflare's fast-moving control plane. Reads, JSON mutations,
-and raw/multipart uploads remain separate so safety routing does not depend on
-an agent-supplied HTTP method. The connection keeps lean projections, typed
-failures, and a rate-limit budget matching the documented one. It adds no
-provider dependency, imports nothing outside Connecta, and is not reachable
-from Connecta's root entry.
+`@zackbart/connecta/providers/cloudflare`. The deployment chooses one of two
+interfaces. The default is a deliberate, hand-written surface over
+Cloudflare's v4 REST API. Its fifty-one tools combine ergonomic, fully
+described operations for common work with three guarded escape hatches for the
+rest of Cloudflare's fast-moving control plane. The other choice is
+Cloudflare's official whole-API hosted MCP, which exposes `search` and
+`execute` with live provider-owned schemas. Both are ordinary connectors and
+neither is reachable from Connecta's root entry.
 
 ```ts
 import { cloudflare } from "@zackbart/connecta/providers/cloudflare";
 
 const edge = cloudflare("cloudflare_prod", {
+  surface: "api", // optional; this is the backward-compatible default
   title: "Production edge",
   purpose: "DNS and cache administration for the production estate",
   zoneId: "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
@@ -23,6 +23,15 @@ const edge = cloudflare("cloudflare_prod", {
 });
 ```
 
+Use Cloudflare's hosted code-mode interface instead:
+
+```ts
+const wholeApi = cloudflare("cloudflare_mcp", {
+  surface: "mcp",
+  purpose: "Cloudflare administration outside the curated REST workflows",
+});
+```
+
 Use the legacy user-scoped Global API Key when an existing deployment needs it:
 
 ```ts
@@ -41,6 +50,29 @@ between a production and a staging instance needs to know which one answers the
 question. Account `instructions` are appended to the maintained guide and
 cannot change the connector's safety classification.
 
+## Choosing an interface
+
+Use the API interface when its projected named tools cover the work. Connecta
+owns those schemas, projections, typed errors, pagination, and the split
+between read-only and mutating escape hatches.
+
+Use `surface: "mcp"` when broad product coverage matters more than projected
+results. Cloudflare's official server covers more than 2,500 API endpoints
+through two code-mode tools. `search` reads the OpenAPI document and is
+read-only. `execute` can run a program containing any authorized HTTP method,
+so Connecta always routes it through approval. A program that happens to use
+only GET cannot be proven observational from the tool schema.
+
+The MCP catalog and schemas come from the live server. The release manifest
+classifies the two known names but does not replace their schemas. OAuth is the
+default. A headless deployment may instead pass `auth` with a scoped API token.
+The credential remains the provider-side permission boundary either way. The
+MCP interface accepts `callAdmission` when the deployment has a concurrency or
+call-rate requirement; it does not reuse the API interface's REST-wide budget.
+
+The remaining sections document the hand-written API interface. MCP tool
+arguments and results are intentionally read from the live server instead.
+
 ## No SDK, on purpose
 
 Cloudflare publishes an official `cloudflare` npm SDK, and this connection does
@@ -61,7 +93,7 @@ claim: the `cloudflare` package must not appear in `dependencies`,
 `peerDependencies`, or `devDependencies`, and every import in the provider
 must be relative.
 
-## Credentials
+## API credentials
 
 The default credential is a scoped Cloudflare API token, sent as
 `Authorization: Bearer <token>`. Create it under My Profile → API Tokens →
@@ -133,7 +165,7 @@ an empty `accountId` would fall back to the default again. A deployment that
 wants zones from one account passes `accountId` explicitly, and the property
 says so.
 
-## Tools
+## API tools
 
 The named surface covers workflows that benefit most from concise schemas and
 projections:
@@ -423,6 +455,14 @@ not by Connecta. `maxConcurrency` is the bound that actually protects a shared
 credential, because a single `execute_code` program can fan out far faster than
 the window notices.
 
+## Contract checks
+
+`npm run providers:check` compares the 49 fixed REST endpoints with
+Cloudflare's published OpenAPI document and the two MCP names, endpoint, and
+OAuth support with Cloudflare's official MCP page. It needs no Cloudflare
+credential. The MCP schemas are not vendored or reconstructed: the live
+`tools/list` response remains the contract agents receive.
+
 ## Conventions
 
 This connection is audited against

package/documentation/connectors.md

@@ -54,11 +54,29 @@ const analytics = mixpanel("product_analytics", {
 });
 ```
 
-The constructor may use `remoteMcp()` or `api()` internally. Callers should not
-need to care which transport gives the better agent-facing surface, and the
-choice does not grant the connection different runtime privileges. Two
-instances of the same provider are isolated in exactly the same way as two
-hand-written connectors with different ids.
+The constructor may use `remoteMcp()` or `api()` internally. When a provider's
+official MCP and HTTP API expose materially different capabilities or schema
+ownership, the constructor may offer an explicit deployment-time surface
+choice. It must document the difference, keep a backward-compatible default,
+and never let an agent switch surfaces during a run. The choice grants no
+different runtime privileges. Two instances of the same provider are isolated
+in exactly the same way as two hand-written connectors with different ids.
+
+That choice exists only when the two interfaces are genuinely different:
+
+| Provider | Maintained interfaces | Why |
+| --- | --- | --- |
+| Cloudflare | API and MCP | The API interface has 48 projected named tools plus three safety-split hatches. The official MCP compresses more than 2,500 endpoints into `search` and approval-gated `execute`. |
+| Notion | API and MCP | The API interface has stable lean projections. The official MCP adds Notion-owned live schemas, workspace search, files, views, agents, and sessions. |
+| Vercel | API and MCP | The API interface has projected deployment operations. The official MCP owns a broader, independently changing catalog. |
+| Linear | MCP | Vendoring its GraphQL API would create a second schema system rather than a distinct maintained interface. |
+| Mixpanel | MCP | Its hosted service already joins several Mixpanel APIs; flattening those APIs would recreate the catalog problem. |
+| RevenueCat | MCP | Its official server is generated from API v2, so a second wrapper would duplicate the same contract. |
+| Stripe | MCP | Its official server already exposes both named workflows and supported API methods. A second raw API interface would duplicate it. |
+
+This is not a requirement that every provider have two labels. A second choice
+must change capability, result shape, or schema ownership enough to justify a
+second contract. Otherwise it only gives agents two names for the same thing.
 
 A prebuilt connection's vetted annotations fill in downstream silence and
 otherwise preserve explicit annotations. This includes an explicit

package/documentation/linear.md

@@ -176,6 +176,15 @@ A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
 for a queue, and the admission controller then requires the rest of the queue
 settings at construction.
 
+## Public contract check
+
+`npm run drift:check -- --docs --provider linear` checks Linear's official MCP
+setup page for the read-write endpoint and OAuth support without using a
+credential. Linear does not publish an exact tool inventory there, so the
+command says `setup metadata only` and makes no claim about names or schemas.
+At runtime the live `tools/list` response remains the schema authority and is
+passed through without a vendored replacement.
+
 ## Conventions
 
 This connection is audited against

package/documentation/mixpanel.md

@@ -85,9 +85,11 @@ A read-only live audit on 2026-08-13 confirmed all three refusals against the
 US hosted endpoint. They are reported upstream as
 [`mixpanel/mixpanel-headless#202`](https://github.com/mixpanel/mixpanel-headless/issues/202).
 The vetted catalog records current schema digests for all 64 tools,
-so a later schema correction or regression appears by tool name in the
-maintainer drift check. The guide can then shrink when the downstream schema
-becomes complete; Connecta does not absorb the defect permanently.
+so a later schema correction or regression increments runtime drift when an
+ordinary catalog refresh observes it. The live definition is still served
+unchanged. The credential-free provider check does not depend on those digests.
+The guide can shrink when the downstream schema becomes complete; Connecta does
+not absorb the defect permanently.
 
 The wrapper classifies the documented observational tools as reads and the
 documented create, update, edit, merge, dismiss, duplicate, and delete tools as
@@ -142,6 +144,14 @@ for a queue, and the admission controller then requires the rest of the queue
 settings at construction. Discovery traffic is outside connector call admission
 either way and still needs restrained use.
 
+## Public contract check
+
+`npm run drift:check -- --docs --provider mixpanel` compares Mixpanel's
+official Available Tools table with the vetted manifest and checks all three
+regional endpoints plus OAuth support. The current table lists 63 tools. It
+omits `Fill-Event-Metadata`, which remains classified from the last
+authenticated review and is reported as `not documented`, not silently removed.
+
 ## Conventions
 
 This connection is audited against

package/documentation/notion.md

@@ -1,39 +1,60 @@
 # Notion prebuilt connection
 
 Import `notion()` independently from `@zackbart/connecta/providers/notion`. It
-is a hand-written `api()` surface over Notion's public REST API — fifteen
-deliberate tools, lean projections of Notion's famously bloated payloads, typed
-failures, a rate budget matched to the documented limit, and a required usage
-guide. It adds no provider dependency, imports no `node:` builtin, and is not
+offers two deployment-time interfaces. The default is a hand-written `api()`
+surface over Notion's public REST API: fifteen deliberate tools, lean
+projections of Notion's famously bloated payloads, typed failures, a rate
+budget matched to the documented limit, and a required usage guide. The other
+choice is Notion's official hosted MCP with live provider-owned schemas and a
+broader workspace, files, views, agents, and sessions catalog. Neither is
 reachable from Connecta's root entry.
 
 ```ts
 import { notion } from "@zackbart/connecta/providers/notion";
 
 const wiki = notion("engineering_wiki", {
+  surface: "api", // optional; this is the backward-compatible default
   title: "Engineering wiki",
   purpose: "Runbooks, specs, and on-call notes for the platform team",
   instructions: "Prefer the Runbooks database; specs live under Projects.",
 });
 ```
 
+Use Notion's hosted MCP instead:
+
+```ts
+const workspace = notion("notion_mcp", {
+  surface: "mcp",
+  purpose: "Workspace search, files, views, and asynchronous agent sessions",
+});
+```
+
 The `id` owns the ordinary connector namespaces; use a different id for every
 Notion workspace. `purpose` is required because an agent choosing between two
 instances needs to know which workspace answers the question. Workspace
 `instructions` are appended to the maintained guide and cannot change the
 connector's safety classification.
 
-## Why this one is `api()` and not `remoteMcp()`
+## Choosing an interface
 
-Notion publishes an MCP server, but the interesting problem here is not
-transport — it is shape. A single Notion page returns every property as a
+Use the API interface for its compact, stable projections. A single Notion
+page returns every property as a
 discriminated wrapper object, every string as an array of rich-text runs each
 carrying its own annotations block, and every user reference as a nested
 object. A twenty-five row database query is tens of kilobytes of structure
 around a few hundred bytes of meaning. Hand-writing the surface is what makes
 the projections possible, and the projections are the point.
 
-## Authentication
+Use `surface: "mcp"` for Notion's wider official capabilities, including
+connected-source search, attachments, saved views, Notion Skills, agents, and
+asynchronous sessions. Tool names and schemas come from the live server.
+Connecta preserves them and only fills in release-reviewed safety annotations
+when Notion is silent. OAuth is the hosted server's authentication contract.
+Do not apply the hand-written REST schemas to similarly named MCP tools. The
+MCP interface accepts `callAdmission` for an operator-supplied runtime policy;
+it does not assume the REST interface's endpoint budget describes MCP traffic.
+
+## API authentication
 
 One operator-managed credential: an internal integration token from
 [notion.so/profile/integrations](https://www.notion.so/profile/integrations).
@@ -52,6 +73,10 @@ Two Notion-specific facts decide whether a working token is enough:
 cheapest call that proves a token is live — and reports the workspace it
 authenticated into.
 
+The MCP interface uses Notion OAuth instead of the integration-token form. An
+`auth_required` failure means the grant is absent or expired and must be
+completed again through `authorize_connector`.
+
 ## The pinned API version
 
 The connection pins `Notion-Version: 2026-03-11` and offers no override. That
@@ -69,7 +94,10 @@ type's payload rather than switching exhaustively. A property type that ships
 after this release degrades to its raw value, and a block type that does keeps
 its payload under `raw`; neither vanishes.
 
-## Tools
+The remaining sections document the hand-written API interface. MCP tool
+arguments and results are intentionally read from the live server instead.
+
+## API tools
 
 Ten reads, all annotated `readOnlyHint: true`:
 
@@ -229,13 +257,14 @@ Cursors are opaque. Notion's own versioning page is explicit that they may
 change in length, format, and structure at any time and must be passed back
 verbatim — never parsed, validated, or constructed.
 
-## What this connection does not do
+## What the API interface does not do
 
 No file uploads, no database or data-source creation, no schema editing, no
 block updates or deletes, no page moves. Those are all real Notion endpoints
 and all deliberately absent: this is a deliberate tool surface, not a mirror of
-the API. Anything missing is reachable through a custom `api()` connector
-beside this one, which remains a first-class path.
+the API. Some are present on Notion's hosted MCP interface. Anything still
+missing is reachable through a custom `api()` connector beside this one, which
+remains a first-class path.
 
 The 2026-03-11 contract also offers more fields on create and update. They were
 reviewed after the 0.17.0 drift check and remain deliberately absent:
@@ -263,6 +292,14 @@ The usage guide says it too, because an agent that assumes a hatch exists
 spends a search proving it does not: absent from the tool list means absent
 from this connection, not hidden behind a generic call.
 
+## Contract checks
+
+`npm run providers:check` compares the 14 fixed REST endpoints with Notion's
+published OpenAPI document and the 34 MCP names, endpoint, and OAuth support
+with Notion's official pages. It needs no Notion credential. The MCP schemas
+are not vendored or reconstructed: the live `tools/list` response remains the
+contract agents receive.
+
 ## Conventions
 
 This connection is audited against

package/documentation/operations.md

@@ -194,10 +194,15 @@ Two more runners are deliberately outside `check`:
 - `npm run test:browser` — Playwright against a real headless Chromium
   (`npm run test:browser:install` once). It covers the embedded bundle without
   adding a browser download to the CI release check.
-- `npm run drift:check` — the maintainer-run provider drift check, with local
-  provider credentials exported. No credential goes near CI and nothing files
-  itself; findings are read by a human and become issues
+- `npm run drift:check` — the lower-level maintainer provider contract check.
+  It reads public MCP references and OpenAPI documents only. No provider
+  credential is read and nothing files itself; findings are read by a human
+  and become issues
   ([provider conventions](./provider-conventions.md#the-maintainer-run-drift-check)).
+- `npm run providers:check` — the normal provider check across every maintained
+  provider: official MCP documentation plus the OpenAPI contracts for
+  hand-written HTTP connections. It uses the network, so it stays outside the
+  deterministic `check` chain.
 - `npm run load:admission` — the opt-in capacity matrix and soak
   ([request admission](./request-admission.md#measuring-capacity)).
 
@@ -234,7 +239,7 @@ in.
 | `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
-| `cloudflare-provider.test.ts` | `cloudflare()` construction, tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
+| `cloudflare-provider.test.ts` | `cloudflare()` API and MCP construction, the code-mode safety manifest, API tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and `connecta.ui` findable before connector search |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
@@ -254,7 +259,7 @@ in.
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
 | `meta-tools.test.ts` | the remaining registry-backed meta-tools: the complete on-demand usage skill, connector-guide selection and summary bounds, stored-credential drift, catalog health, authorization, probe timeouts, and unavailable or unknown browse recovery |
 | `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide, destructive metadata fill, and complete 64-tool schema-digest manifest |
-| `notion-provider.test.ts` | Notion's deliberate tool surface, including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
+| `notion-provider.test.ts` | Notion's API and MCP construction, the hosted safety manifest and drift behavior, the deliberate REST surface including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
 | `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
@@ -274,7 +279,7 @@ in.
 | `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
 | `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus the URL safety gates |
 | `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
-| `vercel-provider.test.ts` | `vercel()` construction, team scoping, project and deployment projections, finite build and runtime logs, value-safe environment variables, domains, lifecycle writes, REST hatches, typed failures, and credential test |
+| `vercel-provider.test.ts` | `vercel()` API and MCP construction, MCP inventory classification, team scoping, project and deployment projections, finite build and runtime logs, value-safe environment variables, domains, lifecycle writes, REST hatches, typed failures, and credential test |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
 
@@ -286,7 +291,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, its agent instructions and setup guide pinning Claude and both ChatGPT Managed OAuth callback forms, one Node template that is also its own container, the same source running locally and in the container, the Node template's pinned esbuild install-script approval, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
 | `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
 | `doctor-cli.test.ts` | `connecta doctor`'s executor line and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
-| `drift-check.test.ts` | the maintainer drift checker — hosted-provider credential framing, recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |
+| `drift-check.test.ts` | the credential-free maintainer drift checker: recorded touched endpoints, heading, table, and inline MCP inventories, setup-only providers, live-schema ownership, a quiet revision bump, clear failures for unavailable inputs, `$ref` traversal, and one well-formed row per endpoint | spawns the checker against filesystem fixtures |
 | `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
 | `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor, including identical caught failure codes and inline describe recovery, its exact absent globals, and blocked runtime imports | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |