Extend Integrations
Choose the narrowest provider contract that keeps executable configuration trusted and credentials backend-side.
Decision Guide
| Provider Need | Extension |
|---|---|
| Public hosted MCP with reviewable tools | Managed hosted MCP |
| Stable vendor API needing a smaller fixed surface | Direct backend API provider |
| Organization-operated public HTTPS MCP | Custom remote MCP |
| Pinned server shipped in the agent image | Trusted local STDIO MCP |
| Vendor command with deterministic read/write classification | Trusted CLI integration |
| User consent and incremental scopes | OAuth-backed managed integration |
| GitHub repository transport for Engineering | Native Git gateway |
Do not force a provider into a CLI integration when schema or dry-run output cannot reliably classify effects, or when the provider requires a shared persistent login home. Prefer a managed MCP with trustworthy annotations or defer the integration.
Three Ownership Layers
Git catalog → immutable published catalog → organization installation → run-local capability- Git owns built-in display, setup, grants, auth contract, runtime key, and tool policy.
- PostgreSQL owns organization connection state, encrypted credentials, non-secret resource settings, selected tools, exact permission mode, and retirement state.
- Shared types own the small trusted runtime registry.
- The backend owns credential resolution and provider gateways.
- The agent receives only execution-scoped gateway configuration.
Non-negotiable Rules
- Never accept a command, package, path, or arbitrary environment from the database.
- Never place credentials in URLs, manifests, prompts, workspaces, or logs.
- Missing read-only annotations fail closed.
- Treat selected tools as a materialized authorization snapshot. Future discovery never expands it.
- A mode-only change deliberately selects every tool currently eligible for the target mode; an explicit tool list wins when both are supplied.
- Consequential chat actions are blocked.
- Consequential task actions use the durable action lifecycle.
- An uncertain provider result is reconciled, not retried.
Permission modes are read_only, ask_user_on_write, and autonomous. The legacy derived access
mode remains only for provider tool eligibility: read-only maps to read_only; both write-capable
modes map to full. ask_user_on_write stages every consequential effect for approval, while
autonomous may execute it immediately under the same task, profile, resource, authorization,
idempotency, budget, and reconciliation fences.
Semantic integration configuration is not a database metadata bag. Store it in Context V3
preferences.toml under the immutable generated connector key. Use the same key for scoped
department meaning and workflow references; never derive connection state from the TOML record.
Native Git is the reviewed GitHub-specific repository transport. It keeps the PAT backend-side, uses ordinary GitHub HTTPS remotes inside the workspace, and routes branch pushes through typed actions. See Native Git Gateway.
Lemon Squeezy, Upstash, MongoDB, and Google Analytics are the direct-provider references. They keep the public MCP gateway shape while replacing an open-ended provider client with fixed backend-owned tools. See Direct Data Providers.
Trusted pinned stdio remains valid only for static agent-image capabilities such as structured questions. Organization credentials stay behind hosted MCP or backend API providers. See Add a Trusted STDIO MCP.