Add a Managed MCP

Use this path for a stable public Streamable HTTP MCP provider that should appear automatically in organization Integrations.

1. Review the Provider

Confirm:

• the official HTTPS endpoint;
• authentication placement or advertised OAuth metadata;
• provider-owned documentation and icon URLs;
• tool discovery behavior;
• read-only annotations;
• which tools are safe to expose;
• startup and tool timeout needs;
• redirects and server-side job behavior; and
• which departments should receive the capability.

Choose explicit enabled tools when annotations are incomplete or future provider tools should not be enabled automatically.

2. Add the Catalog Entry

Edit packages/agent-packs/catalog/catalog.json with:

• unique kebab-case key;
• kind: "mcp";
• name and business-facing description;
• provider website, MCP documentation, and direct HTTPS icon;
• concise Markdown setup instructions;
• existing typed categories and department tags;
• explicit profile grants;
• authentication contract;
• reviewed runtime key; and
• explicit or annotation-based tool policy.

Catalog setup instructions are for people. Put deterministic agent operating workflow in a separate Git-authored skill.

3. Register the Trusted Runtime

Edit packages/types/src/index.ts:

1. Add the runtime key to EManagedIntegrationRuntimeKey.
2. Add the matching managedIntegrationRuntimes definition.
3. Use a fixed public HTTPS URL.
4. Define exact Bearer/header placement or the shared MCP OAuth provider.
5. Keep the credential value environment-backed.
6. Set stable server name and bounded startup/tool timeouts.
7. Mirror authentication and tool policy exactly with the catalog.

Do not use organization data to provide the executable endpoint for a managed provider.

Standards-Based MCP OAuth

Use the shared provider: "mcp" path when the hosted server advertises OAuth discovery metadata. The installed MCP SDK owns protected-resource and authorization-server discovery, dynamic client registration, PKCE, code exchange, and token refresh. The integration runtime supplies only the exact scopes for read-only and full access.

Persist one typed encrypted credential containing client information, tokens, and cached discovery state. Rotated tokens use a compare-and-swap credential update so a refresh cannot overwrite a human reconnect or disconnect, and token rotation must not invalidate otherwise active sessions. Human-driven connection changes continue through the normal authorization-invalidating update. Disconnect clears the local credential even when provider revocation is unavailable or fails.

Do not add provider classes, separate OAuth tables, agent-side tokens, or a second provider registry. Provider-specific code belongs only where the standard metadata or product presentation cannot express the requirement.

4. Add a Provider Skill When Needed

Add a skill when the provider requires a repeatable workflow, bounded pagination, continuation IDs, or non-obvious verification. Grant it only to profiles that own those operations.

5. Test

Cover:

• unique catalog/runtime keys;
• matching kind, authentication, and policy;
• profile-grant validity;
• exact credential header placement;
• exact scopes and OAuth callback behavior when applicable;
• credentials never appearing in URLs;
• tool allowlist and access-mode intersection;
• provider discovery failures;
• enable, disable, rotation, and cleanup; and
• cross-organization credential isolation; and
• token refresh compare-and-swap behavior and best-effort revocation for OAuth providers.

6. Publish and Verify

bun run --cwd apps/backend agent-packs:sync
bun test packages/agent-packs apps/backend apps/agents apps/frontend
bun run typecheck
bun run check

Restart the backend so catalog reconciliation runs before HTTP and jobs. Connect the provider in a test organization and verify setup rendering, icon fallback, links, discovery, tool narrowing, read-only behavior, full-access action policy, rotation, disabling, and run-local cleanup.

Documentation Impact

Add or update:

• the operator provider guide;
• setup prerequisites and credential instructions;
• this developer workflow if the contract changes;
• backend OpenAPI when endpoints or payloads change; and
• agent skill references when usage changes.