Add a Managed MCP

Use this path for a reviewed MCP provider that should appear automatically in organization Integrations through a stable public Streamable HTTP endpoint. When Oblive owns the integration and the vendor has a stable API, use a fixed Direct Backend API Provider. Do not treat stdio as a subprocess sandbox for organization credentials.

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.

The provider-neutral gateway accepts at most 64 KiB of description text, 150 KiB per input schema, 150 KiB for the complete serialized tool definition, and 1 MiB for the aggregate inventory. These ceilings apply to every hosted and backend-owned provider. Do not add a provider exception; narrow the upstream inventory or build a fixed direct API provider when a vendor cannot stay within the shared contract.

The shared connection contract owns default selection behavior. A first connection defaults to read_only and materializes all tools currently eligible for that mode. A mode-only update materializes all current tools for the target mode. An explicit enabledTools list takes precedence, while a same-mode reconnect preserves an existing non-empty narrowing. Empty discovery is persisted as needs_tools rather than discarding a valid credential. Never implement these transitions inside an individual provider.

An exact readOnlyUrl in the trusted runtime is a separate code-owned guarantee. When the current access mode resolves to that provider-enforced endpoint, Oblive classifies every returned tool as read-only because the endpoint has already removed write tools. The ordinary endpoint used by Ask before writes and Autonomous still uses provider or reviewed annotations and fails closed when they are incomplete. GitHub’s official /readonly endpoint is the reference pattern.

For an exact official hosted MCP origin, readOnlyHint: true is sufficient; the MCP specification defines destructiveHint only for non-read-only tools. Custom remote MCP annotations are not a trust boundary: Oblive treats every custom tool as consequential, exposes it only when Ask before writes or Autonomous derives full tool eligibility, and routes it through durable actions.

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:

Add the runtime key to EManagedIntegrationRuntimeKey.
Add the matching managedIntegrationRuntimes definition.
Select streamable_http with a fixed public HTTPS URL. The catalog and organization row may never supply a command, package, path, argument, or environment variable.
Define exact Bearer/header placement or the shared MCP OAuth provider.
Keep organization credentials in the existing encrypted credential store and accept them only through the write-only connection flow; deployment-owned OAuth clients remain environment-backed.
Set stable server name and bounded startup/tool timeouts.
Mirror authentication and tool policy exactly with the catalog.

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

Hosted Providers Without Tool Annotations

Crisp is the reference pattern for a hosted server whose discovery response does not provide enough safety annotations. Its runtime pins https://api.crisp.chat/mcp/, Bearer authentication, a 20-second startup timeout, and a 120-second tool timeout. The catalog and trusted runtime freeze the same 26-tool allowlist:

reviewed reads: get_website, get_website_availability_status, list_website_operators, list_website_operators_active, get_website_operator, get_website_settings, get_website_visitors_count, list_website_visitors, list_website_conversations, get_website_conversation, list_website_conversation_messages, list_website_people_profiles, get_website_people_profile, list_website_people_conversations, get_website_helpdesk, list_website_helpdesk_locales, list_website_helpdesk_articles, get_website_helpdesk_article, list_website_helpdesk_categories, get_website_helpdesk_category, and get_website_helpdesk_settings;
consequential and destructive mutations: update_website_conversation_meta, change_website_conversation_state, update_website_people_profile, update_website_helpdesk_article, and update_website_helpdesk_category.

Overlay the reviewed annotations after discovery, before organization selection and gateway policy are evaluated. Read-only exposes the 21 reads; Ask before writes and Autonomous can expose all 26 tools. Chat’s global read-only policy still removes the five mutations. Any discovered name outside the frozen allowlist is denied.

Do not add a direct API fallback for a capability the hosted server does not advertise. Crisp has no send or reply tool in the reviewed inventory, so conversation replies remain unavailable until the provider advertises one and its schema and safety annotations receive a separate review.

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 the two write-capable permission modes.

Resolve the callback by runtime: a provider-specific deployment callback takes precedence, while other runtimes retain the generic MCP callback. Persist the selected callback in the one-use state and reuse it for code exchange so a configuration change cannot split one authorization attempt across two redirect URIs.

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;
first-connect, same-mode reconnect, mode-change, explicit-list, and zero-tool selection behavior;
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.

On this page