@zackbart/connecta 0.34.0 → 0.35.0

package/documentation/integrating.md

@@ -3,6 +3,21 @@
 Use this guide to change connectors in deployment configuration.
 [All agent routes](./README.md) are in the index.
 
+## Make one connection read-only
+
+Every connector accepts optional `readOnly?: boolean`, defaulting to `false`:
+`remoteMcp("notes", { url: "https://notes.example.com/mcp", auth: { type: "headers", headers: {} }, readOnly: true })`,
+`api("tickets", { readOnly: true, tools: [] })`, and maintained providers such as
+`stripe("billing", { purpose: "Revenue reports", auth: { type: "oauth" }, readOnly: true })`.
+A custom `Connector` sets `readOnly: true` on its connector object.
+
+Only tools classified read appear in search and describe, and every write or
+unclassified tool call is refused before dispatch on every endpoint, including
+maintainers' plain `/mcp`, programs, `call_tool`, and `call_destructive_tool`.
+Effective read-only is endpoint `readOnly` OR connector `readOnly`; connector
+`false` never widens an endpoint. Existing pool/deployment inheritance is unchanged.
+Guides may still name unavailable tools. The operator UI shows a Read-only badge.
+
 ## Add or remove a connector
 
 Connectors are code-owned. Edit the deployment's `src/connecta.config.ts`;
@@ -78,22 +93,9 @@ the deployment constructs its registry.
 
 ## Maintained integrations
 
-Import a provider individually. For example, Linear requires an explicit
-choice of its downstream endpoint:
-
-```ts
-import { linear } from "@zackbart/connecta/providers/linear";
-
-const tracker = linear("tracker", {
-  purpose: "Engineering issues in our workspace",
-  access: "read-only",
-});
-// Add tracker to the deployment's connectors array.
-```
-
-Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from a Connecta `readOnly` endpoint. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
-workspace instructions, and admission choices.
+Import a provider individually from its published subpath. For removed presets
+or a provider's former hosted mode, use the
+[hosted MCP migration guide](./hosted-mcp-migration.md).
 
 The [human README](../README.md#what-you-can-connect) lists available
 integrations. In the installed package, `dist/providers/<name>/index.d.ts`
@@ -105,85 +107,37 @@ providers require administrator-managed domain-wide delegation and a deployment
 mapping from admitted identity to the downstream account; an agent acts as its
 pool's `owner` instead ([auth guide](auth.md#pool-owners-for-google-workspace)).
 A request must not choose its own account. Gmail never sends mail, and Drive never permanently
-deletes files.
-
-Wispr Flow uses OAuth only through `wisprFlow()` from
-`@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
-Notetaker content, with personal and work accounts holding separate data.
-Its runtime guide, available through `connecta.skill("connector:<id>")` in `execute_code`, describes account access,
-search limits, transcript permissions and paging. The
-reviewed classification includes task writes listed in Claude's directory even
-though Wispr's public help describes read-only access; discover the account's
-actual tools before assuming those writes exist.
-
-Stripe requires `auth`: `{ type: "oauth" }` reaches Stripe's hosted MCP
-server, and `{ type: "apiKey" }` with `mode` reaches Connecta's REST connector
-with an operator-managed key. Notion requires `auth` the same way:
-`{ type: "oauth" }` acts as the signed-in user over Notion's hosted MCP, and
-`{ type: "token" }` acts as an internal integration over Connecta's REST
-connector. Cloudflare requires `auth` too: `{ type: "oauth" }` reaches its
-hosted MCP server, and `{ type: "apiToken" }` or `{ type: "globalApiKey" }`
-reaches Connecta's REST connector, with an optional `pin` of accounts and zones
-(required for a Global API Key unless `unpinned: true`). Vercel requires `auth`
-as well: `{ type: "oauth" }` reaches Vercel's hosted MCP server, and
-`{ type: "token" }` with an optional `teamId` reaches Connecta's REST connector
-with an operator-managed access token. Vercel admits only reviewed and approved
-MCP clients to its hosted server, an operational gate outside Connecta. See the
-[provider auth migration](./provider-auth-migration.md).
-To use both implementations of one provider, configure two connector ids with
-independent credentials.
-
-Both Notion auth variants accept optional `callAdmission`. For a token
-connector it replaces the whole per-runtime default of 180 calls per minute
-and 3 concurrent. Notion's [request limits](https://developers.notion.com/reference/request-limits)
-allow 600 requests per minute per connection on Business and Enterprise and
-180 on other plans. A separate workspace-wide limit is shared by all
-connections. Size an override for other runtime traffic and tools that make
-multiple HTTP requests. Only an omitted or `undefined` policy selects the
-default; malformed policies, including `false`, `null`, `0`, and `""`, throw
-at construction on both auth variants.
-
-Planning Center's `excludeApps` removes whole products from a connection, for
-example `planningCenter("pco", { purpose, excludeApps: ["giving"] })` for a
-deployment that keeps agents away from donor and financial data. Excluded
-products lose their named tools, guide text, and version pins, and the
-`pco_api_get` and `pco_api_mutate` hatches refuse their paths before sending.
-The check reads the exact URL the transport would fetch, and while any product
-is excluded a hatch path must be literal: dot segments, empty segments,
-backslashes, whitespace, and percent-encoded `/`, `\`, `?`, `#`, or `%` are
-refused rather than normalized.
-
-Exclusion also closes the routes through which the excluded product's data is
-reachable through another product. While any product is excluded the connection removes
-`list_lists`, `list_list_people`, and `run_list` and refuses every People list,
-list result, rule, and condition, by path or `include`, because a list's
-conditions can draw on any product, such as a donor list built from Giving
-donations, and lists can depend on other lists. Planning Center publishes a
-list's conditions, but a reliable check would have to follow every nested list,
-so the connection does not attempt one. It refuses webhook event and delivery
-payloads, since a payload can carry any product's records, and every change to
-an existing webhook subscription by id, since the id does not name its product.
-A new subscription must name a reachable product's event. People cannot be
-excluded.
-
-What exclusion guarantees is that agents reach none of the excluded product's
-endpoints, no live cross-product query such as a People list, and no webhook
-payload or change to an existing subscription. It does not hide records that the church's own
-automations or staff have copied into a reachable product. A
-[Giving automation](https://help.planningcenter.com/en/144355-automations-in-giving.html)
-can add first-time donors to a People workflow, and those workflow cards stay
-readable, as do donor details recorded in notes, custom fields, or form
-answers. Those are People data once written, so the connection does not refuse
-them by guessing at their origin.
-
-For a hard boundary, give the connection a personal access token belonging to a
-Planning Center user with No Access in the excluded product. Planning Center
-sets permissions per product for each user, does not grant Giving to
-organization administrators automatically, and lets People workflows be shared
-per workflow; a token carries its user's permissions, so Planning Center itself
-refuses what that user cannot see. `excludeApps` is defense in depth on top of
-that boundary: it narrows what Connecta exposes, not what the token can do
-elsewhere.
+deletes files. Google Docs setup and hatch limits are in
+[Google Docs setup](./providers.md#google-docs). Slides setup is in
+[Google Slides setup](./providers.md#google-slides).
+
+Stripe, Vercel, and Cloudflare vendor only their APIs. Cloudflare setup is in
+[Maintained provider setup](./providers.md#cloudflare).
+Keep their existing API auth choices. For token setup, team routing, bounded logs
+and upload limits, see [Vercel setup](./providers.md#vercel).
+GitHub provides scoped App-authenticated repository reads, release writes and guarded merges; see [GitHub setup](./providers.md#github). Hosted servers use distinct
+`remoteMcp()` entries, separate from maintained API providers.
+
+For Stripe API-key setup, see [Stripe setup](./providers.md#stripe).
+Prefer a restricted `rk_` key with only read permissions for read-only access;
+Stripe enforces it too.
+
+For Planning Center construction, token permissions, product exclusions,
+per-product versions and rate/admission limits, see
+[Planning Center setup](./providers.md#planning-center). Its `pco_api_search`
+and `pco_api_details` discover reviewed operations; `pco_api_read` reads them,
+and `pco_api_write` sends approved writes.
+
+Church Community Builder's `sensitiveFields` option controls the documented
+sensitive response fields. Advanced search can still filter on dropped sensitive
+fields, so matching rows can reveal their values by inference. Where that
+matters, omit `read:advanced_searches` from the exact configured OAuth scopes.
+See [Church Community Builder](./providers.md#church-community-builder)
+for OAuth setup, scope boundaries, permanent withholding, paging and limits.
+Tithe.ly's option works the same way; see [Tithe.ly](./providers.md#tithely).
+
+For delegated Google Forms setup, scopes, response privacy and refused publish/watch
+operations, see [Google Forms setup](./providers.md#google-forms).
 
 ## Another remote MCP server
 
@@ -211,15 +165,69 @@ also supports OAuth, static headers, and request-local token resolution. Use
 for those cases. Secrets belong in deployment secret storage or the vault,
 not source literals.
 
-Remote catalogs evolve. Discovery, direct calls, and program calls all enforce
-classification against the current catalog. Missing or contradictory read hints
-fail closed as writes. `classify` can supply a reviewed per-tool verdict;
-schema changes can invalidate a reviewed read. Exact deployment classification
-overrides take precedence. See
-[reviewed classification](./architecture.md#providers-and-reviewed-classification)
-for precedence, schema digests, and `unlisted: "hide"`. Review the behavior
-before declaring a read, and do not use classification to bypass provider target
-scopes or caller grants.
+Use optional top-level `headers` for non-secret resource context:
+`remoteMcp("crm", { url: "https://crm.example/mcp", headers: {
+"X-MCP-Toolsets": "tickets,notes" }, readOnly: true })`. These headers apply to
+MCP handshake, catalog and call requests at the exact resource URL path, never OAuth
+metadata, token or registration requests. Values are included in cache and
+negotiation identities; values of at least eight characters are redacted if echoed. Configuration descriptions
+show only names. Never put credentials here. Use `auth` for secrets. Extra
+headers cannot be combined with `auth.type: "headers"`, collide with an
+auth-owned name, or set HTTP transport/session headers
+(`Accept`, `Cookie`, `Host`, `Content-*`, hop-by-hop headers, `Last-Event-ID`,
+`Mcp-*`), OAuth client-auth headers, or credential-named headers such as
+`X-Api-Key`. Names are case-insensitive.
+
+Runtime-discovered tools default to read exactly when `readOnlyHint === true &&
+destructiveHint !== true`; otherwise they are writes. Override individual tools
+only in deployment code through the existing `classification` map:
+
+```ts
+classification: {
+  crm: { list_tickets: "read", update_ticket: "write", internal_export: "hidden" },
+},
+```
+
+`"write"` requires the host's approval path. `"hidden"` omits a tool from search
+and describe and refuses guessed-name calls, including programs. An absent
+runtime tool leaves its override dormant with an operator warning once per catalog change; the override
+applies if that exact name returns. Unknown static tool names fail construction.
+No argument can change these rules. A write-to-read override changes exposure
+and approval. Replay and failure decisions treat a call as a write when either its
+effective class or its source class is write. The source class is the verified
+server annotations;
+deployment overrides never change it. A write gets one wire attempt across
+OAuth renewal, reconnect, transport and authorization recovery, including program re-runs. After possible dispatch, its
+failure also reports an unknown outcome with no retry or wait advice; a proven
+unsent failure retains its own recovery advice. Connector `readOnly` remains
+optional and composes with endpoint policy.
+
+On Node, serve with `listen` from `@zackbart/connecta/node`: it installs the
+owned transport that prevents native fetch or a host-configured dispatcher
+from silently resending a remote MCP write. Without that transport, Node
+refuses remote writes before dispatch. Downstream OAuth token, registration and
+revocation POSTs also require the owned sender. Read calls and OAuth discovery
+GETs keep native fetch. Workers
+use their native fetch with manual redirects; transport failures after
+dispatch remain unknown and non-retryable.
+
+The owned sender connects directly by default. For HTTP(S) CONNECT proxy egress,
+configure `listen(connecta, { port: 3000, proxy: "http://proxy.example.com:8080" })`.
+This controls maintained-provider requests, remote MCP writes and OAuth
+credential POSTs; it ignores `NODE_USE_ENV_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`
+and host proxy dispatchers. Remote MCP reads and OAuth discovery GETs retain
+native fetch and need their own host proxy policy. An uncertain refresh requires
+fresh authorization rather than replaying the spent token. See
+[Node startup](./deploying.md#start-on-node) for the proxy URL, credentials and
+TLS trust rules.
+
+Remote catalogs evolve. Discovery, direct calls, and programs enforce the
+current annotations and `ConnectaConfig.classification` overrides. A leftover
+`classify` option throws at construction and names that map. Provider reviews,
+schema pins, `optional`, and `unlisted: "hide"` are removed. Missing or
+contradictory hints make the source class write, even when an override makes
+the effective class read. Review behavior before setting a read override;
+classification does not replace downstream scopes or caller grants.
 
 ## A hand-written HTTP capability
 
@@ -262,6 +270,27 @@ writes use `call_destructive_tool` or a program, within the caller's grants; a
 tool definition. Use declared output
 schemas when known; runtime observations cannot replace them.
 
+A write leaves once. Once a write-classified tool's handler has run, any
+failure it ends with is non-retryable with `writeOutcome: "unknown"`, whatever
+its code: a handler can reach the network in ways `api()` cannot observe, so
+nothing it reports proves its write was not sent. A raw network error or an
+`unavailable` becomes `connector_call_failed`; any other `ConnectorCallError`
+keeps its code. Failures before
+the handler runs stay ordinary refusals: argument validation against
+`inputSchema` and missing authorization. Declare input constraints in
+`inputSchema` so a malformed write is refused before the handler starts. In-process
+calls treat undefined properties of plain objects as absent during validation,
+including records nested in arrays. Other objects, such as dates, byte arrays
+and class instances, retain their identity. For example, `{ title: "Minutes", cursor: undefined }` validates
+like `{ title: "Minutes" }`. Validation leaves the caller's arguments intact;
+handlers receive the normalized input. One input evaluation failure cannot
+disable validation for later calls. A
+read's failure keeps its own advice, so a network error stays a retryable
+`unavailable`. `ctx.oauth.fetch` never resends a write the API answered with
+HTTP 401 (see [Downstream OAuth on api()](./auth.md#downstream-oauth-on-api)).
+When the handler settles, the call ends: a `ctx.fetch` or `ctx.oauth.fetch`
+request it starts afterwards fails without being sent.
+
 ## Separate ownership from visibility
 
 `authScope: "shared"` uses deployment-owned downstream auth; `"personal"` uses
@@ -292,5 +321,15 @@ and [provider construction](https://github.com/zackbart/connecta/blob/main/src/p
 [Remote tests](https://github.com/zackbart/connecta/blob/main/test/remote-mcp.test.ts),
 [API tests](https://github.com/zackbart/connecta/blob/main/test/api-connector.test.ts),
 [provider contracts](https://github.com/zackbart/connecta/blob/main/test/provider-contracts.test.ts),
-and [classification tests](https://github.com/zackbart/connecta/blob/main/test/classified-decorators.test.ts)
+and the [write-once tests](https://github.com/zackbart/connecta/blob/main/test/remote-mcp-write-once.test.ts)
 check shared behavior. Provider-specific tests remain beside each provider.
+
+## Connect an Eve agent
+
+Use [`@zackbart/connecta-eve`](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
+in the Eve app for an app-owned connection and endpoint instructions refreshed
+at turn start. It requires Node 24 and Eve 0.83.x, and installs separately from
+Connecta. Follow its README for the two agent files, token environment variables,
+optional write approval and Vercel OIDC token source. Configure the server's
+[agent and pool membership](./auth.md#issue-rotate-or-revoke-an-agent-token)
+before connecting.