External app connections
External app connections let Paperclip agents use outside services through a controlled path. The system discovers supported apps, routes requests to direct or external providers, collects credentials or OAuth approval, assigns identity and agent reach, checks action access, and returns only verified connections to runtime work. This page complements Extensibility platform, Plugin platform, and CLI and MCP interfaces.
Connection model
Provider catalog
The provider catalog is the shared description of services that Paperclip can connect. Each entry describes the service, its supported connection methods, its access shape, and whether the method serves tools, AI authentication, or a channel. A catalog match means that Paperclip knows a route. It does not mean that the app is authorized.
The catalog can also describe external connection services. These entries show that an app may be available through a managed provider such as Composio, Arcade, or Zapier. The provider must still be selected and the target app must still be authorized before an agent can use it.
Some catalog entries are gated by instance settings. A gated app is absent from discovery and setup until its feature is enabled, so a hidden connector is not an unavailable connection that the agent should try to bypass.
Plugin connectors use the same catalog and connection model as built-in connectors. A plugin can expose an implicit connector for older manifest tools, but new plugin access follows the normal installed-connection rules.
References: packages/…/app-definitions.ts• L6-40 packages/…/app-definitions.ts• L42-73 packages/…/connection-routing.ts• L23-37 server/…/plugin-connector-legacy-access.ts• L1-15
Connection identity
A connection joins a provider account to an identity and a set of permitted actions. The identity can be a person, the company, or a dedicated agent. Agent installs then decide which runtimes can receive that connection.
Credentials remain separate from connection display data. Each credential reference must belong to the selected connection and grant, and personal grants must resolve a user-owned secret while shared grants must resolve a company secret. The same ownership checks apply during setup, testing, and execution. Re-entry rotates a matching active secret for its owner; a mismatched or legacy secret is not adopted by another identity. This lets the system reconnect, change grants, and share a provider account without exposing secret values to the UI or to an agent.
References: server/…/connection-credential-bindings.ts• L6-12 server/…/connection-credential-bindings.ts• L24-55 server/…/connection-credential-bindings.ts• L77-111 server/…/connection-credentials.ts• L37-120 server/…/connection-credentials.ts• L134-179
Discovery and routing
Connection discovery
Discovery answers both which services are known and which service is ready for the current agent. Search uses the catalog and indexed tool descriptions. It includes configured connections only when the current task, company, user, and agent can access those descriptions.
External provider matches need evidence from a public provider catalog or from an authorized connection's indexed tools. A broad search or a provider's generic execute capability is not enough to claim support for a target app. Search reports whether a route is ready, needs user action, or is unavailable so the agent can choose the right next step.
Provider inventory adds account resources such as Slack channels or GitHub repositories. These resources help later setup and runtime work. They are not credentials and do not grant access by themselves.
Discovery applies instance feature gates before it exposes a catalog route. It reads indexed catalogs without contacting providers or starting workers. This keeps search side-effect free and keeps experimental or locally disabled connectors out of both agent search and human setup instead of presenting a route that cannot complete.
On Paperclip Cloud, a native connector yields new setup to an external provider when all of its setup methods require a customer-created OAuth app. The discovery result then presents verified aggregator routes instead of offering a native path that the instance cannot complete. This decision is local to the request and does not contact the Cloud broker.
References: server/…/connection-intents.ts• L429-492 server/…/connection-intents.ts• L495-583 server/…/connection-intents.ts• L600-749 server/…/connection-native-yield.ts• L1-13 server/…/paperclip-cloud-connector.ts• L748-805
Connection-intent routing
A connection intent is a task-bound request for the responsible user to connect a service. The runtime first checks whether the agent already has a usable connection. If not, it creates one pending request and waits for the user-facing setup flow.
External providers add a consent step. Paperclip verifies provider support from its catalog or authorized tool index. It asks the responsible user to choose a provider when more than one route is available. A saved provider choice is required before setup can start, and provider setup does not prove that the target app is authorized. An explicit human request for a named provider can select that route without another provider-choice question, but the app still needs later authorization.
When the user completes the request, Paperclip checks the task, membership, connection health, identity grant, agent install, and action permissions in one resolution path. It also supports a narrower access request for an existing connection. That request names exact indexed tools and requires connection-management authority. A decline is recorded and prevents the same continuation from asking again.
After resolution, a durable delivery record wakes the waiting agent through an idempotent task wake. The delivery worker rechecks the task owner, task state, addressed user's write access, and connection readiness before it wakes the run. AI setup uses the agent lifecycle recheck path instead of creating a second provider turn, while an AI repair can reopen only the exact blocked run and active recovery that produced the request.
This diagram shows how an agent request becomes a usable connection or an explicit alternative path.
flowchart TD
A[Agent searches for a service] --> B{Usable connection?}
B -->|Yes| C[Use ready tools or AI authentication]
B -->|No| D{External provider route?}
D -->|Yes| E[Ask responsible user to choose provider]
D -->|No| F[Create connection intent]
E --> G[Validate saved provider choice]
G --> F
F --> H[User opens setup card]
H --> I[Review stated identity and agent reach]
I --> J[Save credentials or complete OAuth]
J --> K[Review action access and install]
K --> L[Resolve intent and wake fresh task run]
Completion rechecks the task owner, task state, membership, selected connection, identity grant, install, and permitted actions while it resolves the intent. This prevents a setup choice from outliving a closed task or a changed access decision.
An already authorized connection can satisfy a pending intent without new setup. The reconciliation path still checks the task state, addressee, agent, connection health, and effective tool access before it retires the request.
References: server/…/connection-intents.ts• L622-671 server/…/connection-intents.ts• L826-988 server/…/connection-intents.ts• L1151-1376 server/…/connection-intent-delivery.ts• L124-255 server/…/satisfied-connection-intents.ts• L18-95 server/…/satisfied-connection-intents.ts• L123-193
Setup and authorization
Setup methods
The setup flow is shared by the Apps store and task-hosted connection intents. It keeps app choice, setup method, access defaults, credential entry, OAuth, action selection, and completion under the same rules. A task card therefore does not create a special connection type.
The flow states the default identity and agent reach above the main setup action. An operator can change those defaults in the inline Change disclosure or later from the Permissions view. The same disclosure can hold alternate connection methods and provider settings, so the normal path stays short without hiding needed choices. The flow applies the same choices to credential and OAuth paths, while a task request keeps the requesting agent as the access target.
For apps with more than one supported method, the flow selects a recommended method first and keeps the alternatives available through the advanced controls. For an unknown remote MCP server, the simple path probes the endpoint before it asks for a key. Explicit choices for no sign-in, a bearer key, custom headers, or browser sign-in remain available when the server needs them.
The setup flow also checks connector availability before it loads a gated app or retained connection. The UI shows a clear unavailable state when the instance does not allow that connector, rather than allowing a partial setup that cannot be used.
The main connection shapes are:
- API key or bearer credential.
- Paperclip-managed OAuth.
- OAuth through a customer-owned client.
- Provider-owned OAuth or direct authorization.
- No-auth or configured remote MCP endpoint.
- AI authentication with a separate AI connection purpose.
The flow can reuse an eligible connection or reconnect a retained one. It does not read saved secrets back into the browser. A retained setup preserves the connection's identity and non-secret provider settings while asking for a replacement secret when needed.
Retained setup is bound to the saved application. A reconnect link cannot switch a connection to another curated provider, and a generic MCP reconnect must name the exact saved application. If the saved provider no longer has a supported setup method, the flow stops with an unavailable state instead of silently starting a different setup.
The setup header keeps the selected app identity visible through the flow. For an unknown remote MCP server, it shows the server host as unverified so the operator can distinguish a custom endpoint from a reviewed app.
References: ui/…/ConnectionSetupFlow.tsx• L437-461 ui/…/ConnectionSetupFlow.tsx• L578-629 ui/…/ConnectionSetupFlow.tsx• L1038-1068 ui/…/ConnectionSetupFlow.tsx• L2071-2115 ui/…/ConnectionSetupFlow.tsx• L3501-3757
Credential and OAuth setup
Credential setup sends values through the server connection pipeline. The browser treats the server's saved connection as the source of truth. It does not treat a provider page, a redirect, or a callback message as proof of success.
The server stores credentials through the connection's selected identity. A personal connection uses a secret owned by the grant's user. A shared connection uses a company secret. Re-entry rotates a valid matching secret, while a missing or mismatched secret creates a new value or requires the correct owner rather than adopting another identity's credential. Setup, testing, and runtime resolution all reject a credential whose owner or connection does not match.
Paperclip Cloud provides a managed OAuth route for supported profiles. Requests are signed for the instance and company, and returned credentials are sealed for that instance. Paperclip accepts only known provider profiles, expected return and provider URLs, matching identity, company, environment, and allowed scopes. Broker errors are reduced to safe fixed reasons, so provider response text and secret values do not enter the application error surface.
OAuth can use a popup or a top-level tab. The setup keeps the task interaction ID through the authorization handoff so the callback can return to the waiting task. Browser messages are accepted only from the application origin and for that exact interaction. A cancelled or failed attempt leaves the saved connection unchanged and gives the user a retry path. A successful callback is accepted only after the server has finalized and verified durable connection state.
The flow can resume an OAuth draft after a lost response or a failed callback. It reloads the saved connection before retrying so a retry does not create a duplicate account. It also keeps the original identity and agent reach when a retained connection is resumed.
Slack app setup is a managed registration path for chat connections. It requires the instance's chat connector feature and a valid public HTTPS origin. The setup records provider registration state, keeps registration secrets in the connection credential store, checks that the callback and webhook addresses still match the configured origins, and limits changes to connection managers. A stale or uncertain provider registration remains a repair state instead of being treated as a ready connection.
Slack test messages are a separate verification step. The operator must use an active Slack connection with direct messages enabled, and the selected account must be a real member of the connected workspace. Paperclip either uses an existing linked identity or sends a private linking invitation before delivery. It records the action before sending, applies the normal write policy, rate-limits repeated tests, and marks an uncertain delivery so a user does not unknowingly send a duplicate.
Slack search uses a separate user-level OAuth grant for search access. The user must first have a linked Slack identity on the selected workspace and active membership in the company. The server accepts only the declared search scopes, checks that the returned Slack user and workspace match the linked account, and refreshes short-lived tokens under the connection lock. Disconnecting revokes that user grant and removes pending authorization state without changing other connection accounts.
The flow also supports a generic remote MCP endpoint. It can probe the endpoint, then guide the operator to use no auth, a bearer value, custom headers, or an operator-owned OAuth client. A known endpoint can switch to a branded app path, but the generic path remains available.
References: server/…/connection-intents.ts• L182-223 server/…/connection-credentials.ts• L37-120 server/…/connection-credentials.ts• L134-179 server/…/paperclip-cloud-connector.ts• L306-375 server/…/paperclip-cloud-connector.ts• L377-413 server/…/paperclip-cloud-connector.ts• L532-604 server/…/paperclip-cloud-connector-revoke.test.ts• L26-79 server/…/registration.ts• L47-137 server/…/test-message.ts• L20-165 server/…/slack-search-oauth.ts• L29-40 server/…/slack-search-oauth.ts• L182-218 server/…/slack-search-oauth.ts• L223-376 server/…/slack-search-oauth.ts• L468-701 ui/…/ConnectionSetupFlow.tsx• L785-922 ui/…/ConnectionSetupFlow.tsx• L1295-1334 ui/…/ConnectionSetupFlow.tsx• L1444-1477 ui/…/ConnectionSetupFlow.tsx• L2712-2861 ui/…/ConnectionSetupFlow.tsx• L3177-3473 ui/…/ConnectionSetupFlow.tsx• L3989-4082
AWS MCP connection
The AWS MCP connection gives an agent access to AWS's hosted MCP service without passing long-lived AWS credentials to the agent. The control plane validates the saved AWS endpoint and method, obtains short-lived AWS session credentials, and exchanges them for a short-lived MCP bearer token.
AWS supports two setup methods:
- The role method uses a Paperclip-signed workload identity token. AWS trusts the token only for the connection's configured role and the
sts.amazonaws.comaudience. - The access-key method reads the connection's stored key. It can use the key directly, exchange it for a read-only federation session, or assume a configured role.
Read-only access applies AWS read-only and MCP sign-in policies. Full access uses the access policy selected during setup. The setup flow generates a CloudFormation template and trust policy so the customer can create an identity provider and a role that trusts only the selected connection. The customer then returns the created role ARN to finish the connection.
At call time, the service accepts only an AWS endpoint for the saved region and a valid role ARN. It caches a token per company, connection, and grant. A connection edit, credential change, expiry, forced refresh, or connection eviction causes a new token to be minted. Concurrent callers share one mint and stalled AWS requests stop within a short deadline.
AWS failures become stable Paperclip errors with safe messages. The system does not return AWS text that could expose account IDs or role names. An instance address change invalidates the recorded issuer for role connections and requires the customer to update AWS trust before reconnecting.
References: server/…/mcp-credentials.ts• L11-40 server/…/mcp-credentials.ts• L96-132 server/…/mcp-credentials.ts• L293-397 server/…/setup.ts• L4-10 server/…/setup.ts• L42-145 server/…/mcp-credentials.test.ts• L48-70 server/…/setup.test.ts• L13-39
Google Workspace service consent
Google Workspace setup lets the operator choose the Google services and access level that the OAuth request should cover. Gmail, Drive, and Calendar are selected independently, with read-only or read-and-write access for each selected service.
New connections default to all three services with read-and-write access. When an existing connection is resumed, the dialog reads only the current user's saved grant and restores the requested service scopes. It does not use an organization grant or another user's broader grant as the current user's choice. The operator must select at least one service, and a failure to load saved grant data blocks continuation without changing the connection.
The selected service set stays in the setup flow until Paperclip starts OAuth or creates the connection. This keeps service consent aligned with the same identity, agent reach, and retry rules as the rest of the connection.
References: ui/…/GoogleWorkspaceServices.tsx• L11-35 ui/…/GoogleWorkspaceServices.tsx• L45-75 ui/…/GoogleWorkspaceServices.test.tsx• L46-85 ui/…/ConnectionSetupFlow.tsx• L1318-1369 ui/…/ConnectionSetupFlow.tsx• L1387-1478 ui/…/ConnectionSetupFlow.tsx• L2220-2231
Managed connector setup
Managed remote MCP connectors provide a hosted provider path for apps that do not use a locally entered credential. The user enrolls the Paperclip instance when needed, chooses the connection identity and agent reach, and then returns to the same app setup flow.
Enrollment is only a prerequisite. The flow saves the selected access scope for the handoff, reloads the provider catalog after enrollment, and restores the task interaction and access choices. If managed sign-in is unavailable, the flow explains that state or offers a supported customer-owned OAuth path when the app provides one.
Paperclip Cloud also acts as a broker for selected Google, GitHub, Asana, Slack, and Tailscale profiles. The instance checks active enrollment and capabilities before showing those methods. OAuth results are bound to the requesting instance, company, subject, profile, and scope set. Removing a managed Google grant reports whether provider access ended, remains through another connection, or could not be confirmed; it does not treat local row removal alone as proof of provider revocation.
References: ui/…/ConnectionSetupFlow.tsx• L1053-1129 ui/…/ConnectionSetupFlow.tsx• L2163-2173 ui/…/ConnectionSetupFlow.tsx• L2439-2523 server/…/paperclip-cloud-connector.ts• L494-604 server/…/google-access-removal.ts• L44-109 server/…/google-access-removal.ts• L191-265
AI connection setup
AI connections use the same company, identity, and agent-reach model as tool connections but have a separate purpose. The server exposes connection pools for managed routing and checks which account or pool a user or agent may select. Pool changes and shared access require connection-management authority, while a personal account can be reconnected only by its owner.
API-key setup verifies credentials against fixed provider endpoints. Custom destinations are exercised in the selected execution environment rather than fetched by the control plane. Local or provider sign-in flows support subscription accounts when the hosting environment permits them. A local machine account can be connected only by the local operator, while an agent request inherits the responsible user's identity rather than the agent's own identity.
AI connections support concurrent runs and account checks. A pending cleanup or another account test does not hold an account-wide execution gate. Credential replacement still uses freshness checks and durable authorization checks before it changes the saved value.
Subscription credentials can refresh during runtime when a provider token expires. The refresh is limited to the selected connection and grant, writes the replacement only after the provider exchange succeeds, and keeps a recovery record when the process loses the database result. A later authentication failure cannot mark a newer credential as invalid. A matching replacement can be verified and saved on a later attempt without creating a second account or changing its access.
Only the account owner can reconnect a personal AI account. Company-shared AI access and installation for all agents require connection-management authority. An agent request can also recover from an AI authentication failure by asking the responsible user to repair the account tied to that run. The UI can show active runs that use an AI connection so operators can understand its current impact.
When a repairable AI authentication failure blocks a task, the accepted setup card restores the task only when it still matches the latest failed run, assignee, and active recovery record. A stale card, reassignment, manual hold, or restricted external-chat retry does not reopen the task.
References: server/…/ai-connections.ts• L37-136 server/…/ai-connections.ts• L147-246 server/…/ai-connections.ts• L248-359 server/…/ai-connections.ts• L221-260 server/…/ai-connections.ts• L262-415 server/…/ai-connections.ts• L554-621 server/…/ai-connections.ts• L1012-1137 server/…/ai-connections.ts• L1138-1255 server/…/connection-intents.ts• L1401-1461 server/…/connection-intent-delivery.ts• L78-121 server/…/connection-intent-delivery.ts• L167-195 server/…/connection-intent-delivery.ts• L227-255
Access and runtime use
Access review
Access review decides who may act through a connection and which actions are enabled. Identity grants describe the acting identity. Installs give selected agents the connection. Action profiles decide which provider actions are allowed or require approval.
Connection management evaluates the actor, responsible user, task or project context, target agents, and saved profile or gateway bindings as one authorization decision. Agent-led changes keep the originating run and task authority, then reauthorize after a human completes setup. This prevents a delegated agent from continuing with an old identity or task state.
For delegated work, the decision also captures the run identity and checks the agent key, task ownership, task mode, and target-agent edit authority. Profile and gateway changes expand to every affected connection and target before the operation is allowed. A continuation after human setup must pass the same checks again. Capability checks can describe allowed installation actions, but a real mutation or human continuation starts a fresh authorization pass.
Task setup is narrow by default. It gives the requesting agent the access needed for that task. Reusing a personal identity creates an explicit delegation to that agent. Company-wide access needs connection-management authority. Reconnecting replaces credentials without changing existing agent reach. An existing connection can also produce an inline access request that shows the exact tools and their default permission level before a manager grants it. The server repeats these checks at intent completion instead of trusting the UI's earlier choices.
Organization grant audiences are replaceable lists of active company members. An empty audience retains the system's company-wide meaning, while an inactive retained member blocks an accidental widening until an operator repairs the audience. Personal grants belong to their owners and use explicit delegation when an agent needs them.
Access completion also confirms that the selected connection is the one the agent can execute. If identity resolution finds conflicting or inactive higher-priority grants, the request fails closed rather than choosing an arbitrary account.
References: server/…/connection-management.ts• L39-100 server/…/connection-management.ts• L159-209 server/…/connection-management.ts• L272-335 server/…/connection-management.ts• L389-481 server/…/connection-intents.ts• L294-365 server/…/connection-intents.ts• L735-760 server/…/connection-intents.ts• L990-1137 server/…/grants.ts• L117-283 server/…/grants.ts• L285-386 ui/…/ConnectionIntentInteractionBody.tsx• L331-355 ui/…/ConnectionSetupFlow.tsx• L2071-2115 ui/…/ConnectionSetupFlow.tsx• L4350-4421
Managed connector runtime
The managed connector runtime turns current assignments into tools and resource data for an agent run. It resolves assignments at run time and checks access again when a tool call arrives. A credential or an agent-authored setting is not enough to prove access.
The same governed path supports reviewed native REST connectors, managed remote MCP connectors, and plugin-served connectors. Native connectors supply provider-specific actions while the shared gateway keeps identity, grants, action policy, and audit under the connection model. Plugin workers only receive a call after the gateway has made those decisions; a stopped worker produces a retryable unavailable result rather than bypassing the gateway.
Plugin catalogs can be static or supplied by a running plugin worker. Saved static entries remain usable only when they still match the plugin's present tool declaration and risk. A plugin upgrade that removes or changes an action therefore makes the old entry unavailable until the catalog is refreshed. Dynamic catalogs are read from the active worker and are bounded to valid tool names and risk levels.
The current native catalog covers 1Password vault and item actions, Supabase project configuration and Edge Functions, and Vercel projects, deployments, environment values, and domains. These connectors supply provider-specific actions while the shared gateway keeps identity, grants, action policy, and audit under the connection model.
Slack chat operations add a live task authority check to this model. The authority comes from the active chat service rather than from model arguments, saved task data, or a credential. It binds the operation to the company, assigned agent, bound task, accepted requester, and any approved invocation. Slack endpoint candidates are limited to the assigned agent's active or verifying endpoints.
Slack authority also follows immutable controller provenance to the latest human message. An approved operation must still match the active identity context and the task's approval record. This keeps a board-authored or stale run from inheriting another Slack user's authority.
This runtime check makes revocation take effect on the next resolution or call. It also keeps connector-provided guidance separate from the agent's durable manually managed skills.
References: server/…/connector-runtime.ts• L41-62 server/…/connector-runtime.ts• L104-208 server/…/plugin-connector-runtime.ts• L1-18 server/…/plugin-connector-runtime.ts• L47-119 server/…/plugin-connector-runtime.ts• L137-208 server/…/connection-intents.ts• L289-301 server/…/connection-intents.ts• L342-365 server/…/rest-registry.ts• L26-46 server/…/catalog.ts• L23-40 server/…/index.ts• L45-69 server/…/catalog.ts• L26-60 server/…/slack-authority.ts• L16-181
AI usage review
AI connection usage review reports provider limits and overage state for supported sign-in methods. The service reads only fixed provider endpoints, applies a response size limit, rejects redirects, and returns a small normalized result instead of raw provider data.
Usage is best effort. A provider can report a limit, a spend or credit balance, or an unavailable state when the credential lacks permission. Unsupported methods and provider errors become clear status codes for the connection UI rather than blocking AI setup or execution.
References: server/…/ai-connection-usage.ts• L66-99 server/…/ai-connection-usage.ts• L329-347 server/…/ai-connections.ts• L236-246
Review and observability
Action review
After setup, Paperclip builds an action catalog for the connection. Operators can enable actions, require approval for sensitive actions, and review new or quarantined actions. This limits agent behavior even when the provider credential permits more.
The same control surface supports health checks, reconnect, identity and permission changes, and removal. Removal archives the connection and removes its saved credentials without affecting separate accounts for the same provider. It also closes local access paths before provider cleanup, so a failed provider call leaves a closed and resumable local state.
Removing a connection can request content deletion for stored tool results and run output. The deletion job clears eligible invocation, approval, event, audit, app-view, delivered-result, and settled-run content in bounded steps. It leaves unsettled work intact until that work is safe to change.
References: ui/…/AppDetail.tsx• L525-685 ui/…/tools.ts• L406-425 server/…/removal.ts• L218-233 server/…/removal.ts• L359-687 server/…/content-deletion.ts• L47-123 server/…/content-deletion.ts• L182-235 server/…/tool-connection-content-deletion-work.ts• L9-39
Connector risk policy
Reviewed connectors add a provider-level risk policy to the action catalog. The policy classifies actions as read, write, or destructive and places new or changed actions into review before agents can rely on them. Provider metadata alone does not override this review.
Native REST catalogs make this contract explicit for each provider. 1Password separates secret reads from item changes and deletion. Supabase separates project and configuration reads from configuration changes, function deployment, secret updates, and deletion. Vercel separates inspection from project, deployment, environment, and domain changes. Catalog and schema changes invalidate old entries so the runtime does not treat an outdated action as reviewed.
The policy covers native REST connectors, managed MCP connectors, and plugin-declared connector tools. A plugin worker's declared risk travels with its catalog entry, and a changed static declaration makes the saved entry stale. Braintrust actions that can change data or spend model credits are not treated as reads, and Enterpret graph queries are treated as writes until their read boundary is proven. Unikraft actions come from a reviewed provider contract and are limited to the provider's published regional endpoints.
References: server/…/tool-policy.ts• L7-89 server/…/plugin-connector-runtime.ts• L91-105 server/…/plugin-connector-runtime.ts• L121-175 server/…/rest-registry.ts• L8-18 server/…/catalog.ts• L23-49 server/…/index.ts• L45-76 server/…/catalog.ts• L26-67 server/…/risk.ts• L3-45 server/…/risk.ts• L3-9 server/…/client.ts• L1-23 server/…/operations.generated.json• L1-20
Connection telemetry
Connection telemetry records the connection lifecycle and completed invocation attempts without sending secret data or provider-controlled names. Known catalog slugs identify reviewed first-party connectors. Unknown, plugin, or custom connections use the fixed custom key.
Lifecycle events cover tool-purpose connection creation and changes to enabled or archived state. Invocation telemetry records only terminal outcomes, origin, and optional duration. Setup tests are separated from agent use by durable invocation fields. Telemetry is best effort, so a telemetry failure does not block setup or tool execution. A completed invocation is emitted after success bookkeeping or immediately after a terminal failure save, which avoids reporting a success before later bookkeeping changes it to a failure.
References: server/…/connector-telemetry.ts• L25-77 server/…/connector-telemetry.ts• L79-151 server/…/connector-telemetry.ts• L153-229 packages/…/events.ts• L156-223
User interface flows
Connector store
The Apps landing page is the main catalog and account-management surface. It combines reviewed app definitions, custom applications, and saved connections. Provider rows stay separate from connection accounts so one account can be removed or reconnected without changing another.
The same entry points support new setup, reuse, reconnect, and removal. A task request can open the shared setup flow with the responsible agent and interaction already bound to it.
The store hides connectors that are disabled for the instance. This keeps the catalog, direct app links, and task-hosted setup flow aligned about which integrations can be configured.
References: ui/…/Browse.tsx• L270-315 ui/…/Browse.tsx• L380-430 ui/…/Browse.tsx• L723-751 ui/…/ConnectionSetupFlow.tsx• L1038-1068 ui/…/ConnectionSetupFlow.tsx• L2333-2411
Task connection card
The task card is the human entry point for a connection intent. Only the addressed user can choose an identity, reuse an eligible connection, authorize a provider, complete setup, or decline the request. Other users see a waiting state and do not load setup data or credential controls.
When the request only needs access to an existing connection, the card shows the requesting agent, the connection, and the exact tool permissions without opening the full setup flow. A connection manager must grant that access. AI requests can also repair or select an account inside the card. Channel requests such as AgentMail use an inline credential and inbox setup path. The card keeps setup errors and retry states visible and restores focus after completion or decline.
The card reports requested, authorizing, and retry states to the server. OAuth completion refreshes durable state and resolves the task only after the server confirms the connection. Completion or decline updates the task view and wakes the requesting task through a durable, retry-safe delivery path. AI setup resumes through lifecycle readiness rather than a duplicate provider wake. A cancelled or replaced setup cannot let a late credential result accept the request or change the current account choice. Terminal requests show their final result without loading new setup controls.
References: server/…/connection-intents.ts• L826-1150 server/…/connection-intent-delivery.ts• L16-75 server/…/connection-intent-delivery.ts• L124-255 ui/…/ConnectionIntentInteractionBody.tsx• L118-239 ui/…/ConnectionIntentInteractionBody.tsx• L241-355 ui/…/ConnectionIntentInteractionBody.tsx• L360-577 ui/…/ConnectionIntentInteractionBody.test.tsx• L239-358 ui/…/ConnectionIntentInteractionBody.test.tsx• L659-822
Connection instructions
Connection instructions are optional guidance that travels with an installed connection. An operator can keep the default text, edit it, turn it off, or restore the provider template from the connection settings.
Agents receive enabled instructions only when the connection is active and available to the task. The UI warns when instructions are disabled or when the connection still lacks the configuration needed to provide its instruction context. These instructions guide tool use; they do not grant access or replace action permissions.
References: ui/…/ConnectionInstructions.tsx• L21-98 ui/…/ConnectionSetupFlow.tsx• L1286-1293
Connection detail
The connection detail page is the control surface for an existing account. Its controls separate action review from identity, permission, install, health, reconnect, and removal decisions. The Permissions view reads only the saved profiles that belong to the connection or to an eligible task grant, then applies the same current-authority checks used by the broader profile view. This keeps the page focused without turning connection visibility into profile access.
Server-computed capabilities keep the UI from granting a user access to another person's identity. Attention states lead to repair paths. A failed health check, expired grant, revoked identity, or needed reauthorization does not silently appear as a ready connection.
References: ui/…/AppDetail.tsx• L81-186 ui/…/AppDetail.tsx• L525-685 server/…/connection-configuration.ts• L8-63 server/…/connection-management.ts• L108-157
Change checklist
When these files or sections are changed, remember to consider these:
- Keep catalog methods, connection-intent purpose, and setup routes aligned. Tool, AI, and channel methods must not be mixed.
- Preserve the provider-choice interaction ID from search through saved human answer and
connection_request. A pending question is not provider consent. - Keep OAuth interaction IDs and callback outcomes bound to durable server state. Accept browser messages only from the expected origin and interaction. A browser callback must not resolve an intent by itself.
- Keep retained resume and reconnect links bound to the exact saved application. An unavailable retained connection must not fall through to a different provider or a fresh hidden setup.
- Keep identity grants, agent installs, action permissions, and credential bindings consistent. A connection is usable only when all required layers agree.
- Preserve the task completion transaction's membership, task ownership, connection identity, and runtime-readiness checks. Setup choices must not outlive a closed task or removed responsible user.
- Keep AI pool selection, local sign-in sessions, API-key verification, and active-run visibility behind the same company and connection-purpose checks.
- Keep AI account use concurrent. Credential replacement and recovery must retain freshness and ownership checks without restoring an account-wide execution lock.
- Keep subscription credential refresh scoped to the selected grant and connection. Preserve the recovery journal across lost commits, and do not let a late authentication result revoke a newer credential.
- Keep AI usage probes limited to fixed provider origins and normalized output. Do not expose provider responses or secret data.
- Keep Cloud native-connector yielding aligned with the shared catalog rule for customer-owned OAuth apps. Do not offer a native setup path when discovery has selected a verified aggregator route.
- Keep AWS method declarations, endpoint validation, issuer recording, and AWS trust setup aligned. The role subject and audience must match the signer and generated trust policy.
- Keep AWS read-only policy behavior distinct from full-access behavior. Do not let an unknown access value become full access.
- Keep AWS token cache revisions tied to the selected connection, grant, saved credential references, and settings. Edits, expiry, 401 eviction, and issuer changes must not reuse an unsafe token.
- Keep managed connector access checks in both run setup and tool invocation. Do not turn runtime assignments into durable agent preferences.
- Keep plugin worker routing behind gateway authorization. A stopped worker must produce an unavailable result, not a second access path.
- Keep plugin static catalog entries aligned with the current plugin declaration. A changed risk or removed action must not remain active from an old catalog row.
- Keep connection instructions scoped to active installed connections. Do not let instruction text act as an access grant.
- Preserve telemetry's fixed
customfallback and terminal invocation rule when connector metadata or invocation states change. - Keep access requests tied to the saved connection and exact indexed tool names. Do not let a changed catalog silently broaden a grant.
- Keep the task card's addressee gate, inline access-request path, AI repair path, channel setup path, and setup-flow access defaults aligned. A viewer must not load credentials, and a task must not grant more than the requesting agent.
- Keep Google Workspace service selections attached to the same connection and OAuth attempt. Existing service choices must come from the current user's grant, not a broader organization or another user's grant.
- Keep managed Google removal tied to the consenting subject, shared refresh-token use, provider outcome, and audit result. Local revocation is not provider revocation.
- Keep Slack search grants bound to the linked user, workspace, endpoint, client revision, and declared search scopes. Refresh and disconnect must use the same connection-level guard.
- Keep Slack app registration origins, registration state, secret writes, and provider setup locks aligned. A changed public or webhook origin must force repair instead of silently using stale Slack settings.
- Keep Slack test messages bound to the selected workspace member, linked identity, write policy, idempotency record, and uncertain-delivery state. A selected Slack account is not proof that its owner approved the link.
- Keep Slack task authority tied to live chat admission, the bound task, accepted requester, and assigned endpoint. Credential possession or model input must not create authority.
- Keep connector risk policies tied to the reviewed provider identity and catalog contract. New or changed actions must remain quarantined until their risk is reviewed.
- Keep gated connector availability consistent across catalog discovery, direct setup links, retained connections, and task-hosted setup. A disabled connector must not be reachable through a stale route.
- Keep native connector endpoint allowlists and generated operation contracts aligned. A provider token must not be sent to an unreviewed host or an operation outside the published contract.
- Keep provider responses bounded and redacted for native REST actions. Secret values and upstream error payloads must not enter tool results or audit data.
- Keep connection removal closed before provider cleanup. Preserve enough connection and credential reference state for a failed provider operation to resume without reopening access.
- Keep content deletion scoped to the selected connection and request cutoff. Do not clear unsettled runs, approvals, or wakes that can still change state.
- Keep the connection Permissions read scoped to the selected connection and exact eligible task profiles. Connection access alone must not bypass per-profile authority checks.
- Keep delegated connection changes tied to the originating run, responsible user, task mode, target agents, and fresh reauthorization after human setup.
- Keep credential references tied to the grant's owner and secret scope. Re-entry must not rotate or adopt another user's or company's secret.
- Keep connection-intent delivery leases, task guards, and idempotent wake keys aligned. A retried delivery must not wake a closed or reassigned task twice.
- Keep AI repair delivery tied to the latest failed run and active recovery record. Queued agent setup must use lifecycle recheck rather than a generic provider wake.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The agent requests an external provider without a saved user choice | Paperclip could connect an app through a route the user did not approve | Require the returned provider question and its answered interaction ID before creating the setup card. |
| OAuth returns to the browser but the durable connection is not active | The task could claim success without usable access | Finalize and verify server state before resolving the intent. |
| A credential reference points to a secret owned by another identity | Setup or runtime could use the wrong account's credential | Validate the connection, grant, secret scope, and owner before resolving the secret. |
| A personal grant lacks delegation or an agent install | The user can use the account but the requesting agent cannot | Add delegation and the agent install during intent completion. |
| An installed connection has no permitted action | Reconnecting does not make the agent able to work | Return administrative denial and require action review. |
| An AWS role trusts a different issuer, audience, or connection subject | AWS rejects the session or a connection could use a role intended for another connection | Generate and verify the trust policy from the saved issuer and connection identity. |
| An AWS endpoint, region, role ARN, or access method does not match the saved catalog method | The gateway could send credentials to the wrong host or use an unsafe setup | Recheck the reviewed method, AWS endpoint, region, and role format before minting. |
| An AWS read-only session omits federation or MCP sign-in policy | Token minting fails or the session receives broader access than intended | Apply the fixed read-only policy set and require an explicit policy for full access. |
| An AWS mint stalls or returns provider account data in its raw error | A tool call can hang or expose account IDs and role names | Abort each AWS step at its deadline and map failures to safe stable messages. |
| A plugin worker is stopped during a connector call | The tool cannot run even though the connection exists | Return a retryable connector-unavailable result and keep authorization in the shared gateway. |
| A plugin upgrade changes or removes a static tool | An old catalog entry could expose an action with the wrong risk | Compare saved entries with the current declaration and hide stale entries. |
| The responsible user loses write access during completion | A removed user could still grant company access | Recheck membership under the task and company row locks in the completion transaction. |
| An AI request uses a caller-supplied verification URL or follows a redirect | Credentials or provider data could leak | Use fixed provider endpoints, reject redirects, and return normalized verification states. |
| A subscription token refresh loses its commit result or a late run reports authentication failure | A valid replacement could be lost or a newer credential could be marked for reauthorization | Keep the selected grant's recovery record, compare credential generations before writing, and ignore failures from older runs. |
| A managed connector assignment is revoked after a run starts | Stale runtime guidance could expose a tool | Resolve current assignment and authorization again for each tool call. |
| A provider name is custom or untrusted | Telemetry could record provider-controlled data | Map unknown, plugin, and custom identities to custom. |
| A managed Google removal uses the latest subject instead of the consenting subject | Provider access can remain after local grant removal | Revoke each distinct refresh token under its recorded consent subject and report the provider outcome. |
| A retained reconnect link names a different provider or loses its exact application | The operator could reconnect the wrong account or start an unintended fresh setup | Match the saved connection and application before restoring setup. Show an unavailable recovery state when the match fails. |
| A task-card setup finishes after the operator cancels or opens a newer repair | An old credential result could accept the task or replace the current account choice | Ignore stale setup generations and re-read durable setup state before accepting callback results. |
| A new provider action is accepted from metadata without a reviewed connector policy | An agent could receive a write or destructive action as if it were a safe read | Apply the provider policy, quarantine new entries, and require action review before use. |
| A connector is disabled after a catalog link or retained setup URL is created | The user could enter a setup path that the instance cannot safely complete | Recheck feature availability in discovery and setup, then show an unavailable state without changing the saved connection. |
| A native REST catalog entry no longer matches its provider descriptor or risk level | An old action could remain available after its input or safety meaning changed | Compare the stored catalog hashes and risk level with the current provider catalog before allowing the action. |
| A connection removal clears rows but leaves a runtime, gateway token, or OAuth state active | An old process or callback could retain access to the removed app | Close database and runtime access paths before provider cleanup, then revoke tokens and discard pending OAuth state. |
| Content deletion changes an unsettled run or approval | A live task could lose data needed to finish or retry safely | Delete only content tied to settled work and resume the bounded deletion job later. |
| A connection Permissions read loads every profile without connection scoping | The page could expose unrelated rules and increase load without changing effective access | Select the app profile and exact eligible connection-intent profiles before loading entries and bindings, then retain per-profile visibility checks. |
| A delegated connection action continues after its run or responsible user changes | An agent could configure access outside its original authority | Capture the run identity, verify task state and mode, and reauthorize after the human action. |
| A delivery worker retries an accepted card after the task is closed, reassigned, or the user becomes a viewer | The agent could wake from stale approval or the delivery could remain falsely successful | Claim a leased delivery, recheck task and membership guards, and settle invalid deliveries without waking the run. |
| An AI repair card refers to an older failed run or an already resolved recovery | A stale human action could reopen a newer or unrelated task | Match the latest failed run, assignee, blocked state, and active recovery before restoring the task. |
Key files
| File | Why to read it |
|---|---|
| packages/…/app-definitions.ts | Defines provider catalog entries and connection method capabilities. |
| packages/…/connection-routing.ts | Defines provider route parsing, ranking, and external-provider metadata. |
| server/…/connection-intents.ts | Coordinates discovery, provider choice, task requests, access checks, AI recovery, and intent resolution. |
| server/…/connection-intent-delivery.ts | Delivers accepted or declined intents, restores eligible AI-blocked tasks, and wakes agents safely. |
| server/…/satisfied-connection-intents.ts | Reconciles pending requests when an already authorized connection becomes available. |
| server/…/connection-intents.ts | Exposes runtime search, connection request, addressed-user setup, completion, decline, and phase updates. |
| server/…/connection-management.ts | Applies actor, run, task, target-agent, profile, gateway, and connection-management authorization. |
| server/…/tool-access.ts | Owns connection grants, installs, OAuth finalization, action access, and connection health. |
| server/…/grants.ts | Defines grant audiences, agent delegation, installation, and grant revocation. |
| server/…/removal.ts | Defines the closed-first connection removal and credential cleanup flow. |
| server/…/content-deletion.ts | Defines bounded deletion of connection-linked tool and run content. |
| server/…/connection-credential-bindings.ts | Links connection identities to secret declarations. |
| server/…/connection-credentials.ts | Enforces credential ownership and resolves personal or shared connection secrets. |
| server/…/ai-connections.ts | Selects usable AI accounts, resolves their credentials, and refreshes subscription credentials without losing newer account state. |
| server/…/paperclip-cloud-connector.ts | Defines managed provider capability discovery, OAuth handoff, sealed credentials, refresh, and revocation. |
| server/…/google-access-removal.ts | Defines provider-side Google access removal and outcome reporting. |
| server/…/mcp-credentials.ts | Defines AWS MCP endpoint validation, short-lived credential minting, caching, and safe error mapping. |
| server/…/setup.ts | Generates the AWS role trust policy and CloudFormation setup path for one connection. |
| server/…/plugin-connector-runtime.ts | Routes authorized plugin connector calls and keeps worker availability and catalog freshness explicit. |
| server/…/connector-runtime.ts | Shows how managed assignments become runtime tools and how access is rechecked. |
| server/…/rest-registry.ts | Registers the reviewed native REST adapters behind the shared connection gateway. |
| server/…/tool-policy.ts | Maps reviewed provider identities to action-risk rules and quarantine behavior. |
| server/…/connector-telemetry.ts | Defines safe connector lifecycle and terminal invocation telemetry. |
| ui/…/ConnectionSetupFlow.tsx | Provides the shared catalog, access defaults, credential, OAuth, enrollment, reconnect, and completion experience. |
| ui/…/GoogleWorkspaceServices.tsx | Provides the Google Workspace service and access-level consent step. |
| ui/…/ConnectionIntentInteractionBody.tsx | Provides the addressed-user task card and inline access or repair flows. |
| ui/…/AppDetail.tsx | Provides action review, permissions, health, reconnect, and removal controls. |