Add an OAuth or CLI Provider

OAuth and trusted CLI providers are cross-stack features. A catalog entry alone is insufficient. Google Workspace is the reference implementation.

For a hosted MCP server that advertises standard OAuth discovery, use the shared managed-MCP OAuth path in Add a Managed MCP. Keep this guide for providers that need service-specific consent behavior or a trusted CLI gateway.

First Decide Whether CLI Is Safe

Proceed only if the vendor CLI can:

• expose deterministic schema or dry-run information;
• distinguish reads from effects without executing the effect;
• run with a temporary isolated home;
• accept bounded files and output;
• avoid interactive persistent login state; and
• be pinned and verified in the image.

If classification is uncertain, fail closed. Prefer a managed MCP or defer the provider when these conditions cannot be met.

1. Extend Shared Contracts

In packages/types/src/index.ts:

• add the managed runtime key;
• extend the OAuth provider union if this is a new provider;
• add the smallest provider capability shape;
• define selected service/tool names as bounded values; and
• add the trusted runtime definition.

Update catalog validation so kind, authentication, and policy remain identical across the catalog and trusted registry.

2. Add Catalog Presentation and Grants

Add a strict kind: "cli" catalog entry with provider resources, setup instructions, OAuth authentication, service allowlist, categories, departments, and explicit profile grants. Do not put commands, paths, downloads, or secrets in the catalog.

3. Model Durable Connection State

Use the existing integration row when the provider fits its typed configuration and credential envelope. Add a migration only when new durable provider state is genuinely required.

Store:

• encrypted refresh credential or API secret;
• selected services;
• access mode;
• redacted account identity;
• readiness and status; and
• authorization epoch effects.

Never expose the plaintext credential in a response.

4. Implement OAuth

The backend owns:

1. authorization initiation;
2. organization- and integration-bound state;
3. PKCE where supported;
4. callback validation;
5. code exchange;
6. incremental service-to-scope mapping;
7. encrypted refresh credential storage;
8. redacted account metadata;
9. short-lived access-token refresh;
10. same-account reauthorization policy;
11. disconnect and revocation behavior; and
12. frontend return redirects.

Add connect, callback, status, and disconnect OpenAPI documentation. Test replay, expired state, state mismatch, provider errors, wrong account, missing scopes, disconnect, and redaction.

5. Pin the Vendor Binary

• Download a fixed version during the backend image build.
• Verify per-architecture checksums.
• Install below /opt/oblive/integrations/<provider>/<version>.
• Keep the vendor binary off the global shell PATH.
• Verify the binary in the built image.

Never download or install the vendor tool during an agent run.

6. Build the Backend Gateway

Add a narrow provider adapter that:

• validates the integration capability;
• rejects auth, setup, and configuration commands;
• bounds pagination, time, input, and output;
• classifies the operation before execution;
• routes reads directly;
• routes effects through integration-action.service.ts;
• materializes short-lived credentials in a mode-0600 temporary home;
• cleans up on success, error, cancellation, and stale recovery; and
• never returns provider credentials.

7. Add the Agent Launcher

Add a checked-in launcher under apps/agents/src/cli/<provider> and register only its integration-owned directory in apps/agents/src/cli/registry.ts.

Copy the launcher and any login-shell environment file into that image-owned directory with explicit modes. Do not symlink them back into /workspace/apps, because development bind mounts replace image-time source files and their executable modes. Verify the exact launcher path in the image and keep it off the global PATH.

The active run may receive:

• gateway URL;
• an environment-variable reference for its execution capability;
• enabled services; and
• the launcher directory prepended to its scoped login shell.

The vendor credential must not be inherited by the agent shell.

8. Add Provider-specific UI

Ordinary API-key integrations remain catalog-driven. OAuth providers need UI for service selection, access mode, connection initiation, callback results, redacted account state, reauthorization, and disconnect.

9. Add the Skill

Create a deterministic provider skill describing schema inspection, bounded reads, required idempotency and summary flags, file rules, approval/reconciliation exits, and provider-specific verification. The skill carries workflow—not credentials or executable configuration.

10. Verify Release

Test:

• ungranted shell cannot find the launcher;
• granted run can resolve only the launcher;
• read classification;
• write approval;
• stale authorization rejection;
• idempotency;
• unknown transport outcomes;
• file boundaries;
• credential cleanup;
• cross-organization isolation;
• image pin and checksum; and
• both backend and agent images after a launcher or binary change.