Files
PaperClipAI/doc/connections
deacaf727c feat(connections): guided AWS role setup with a per-connection CloudFormation template (#22233)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The AWS connector (#22195) lets agents use AWS with credentials
minted per connection. Its role method stores no AWS keys
> - That method needs the customer to create an IAM role that trusts
exactly one Paperclip connection, but setup only offered the generic
form and a doc
> - The connect API also refused the draft step this method needs, so
the role method could not be set up through the UI at all
> - This pull request adds a guided setup screen. Paperclip saves a
draft, hands the user a prompt for their own agent that creates the
role, takes back the role ARN the agent reports, and tests the same
draft. CloudFormation and IAM steps are there under "Or do it by hand"
> - The benefit is that a person can connect AWS without stored keys and
without typing account details, using a template AWS has validated

## Linked Issues or Issue Description

Refs #22195.

**Subsystem affected**
Connections (AWS connector setup), UI, tool-access API.

**Problem or motivation**
The AWS role method must save a connection before AWS can trust it. The
API rejected `saveDraft` for every method except custom MCP servers, so
the UI could not complete this flow. There was also no screen that
showed the issuer, the subject, the trust policy or a template.

**Proposed solution**
- The connect API accepts `saveDraft` for methods that declare
`credentialMinter`.
- `GET /tool-connections/:id/aws-setup` returns the setup values and a
CloudFormation template generated for that connection.
- A new `AwsRoleSetup` step runs between saving the draft and testing
it. The role is named after the connection and CloudFormation fills in
the account, so the first form no longer asks for a role ARN; the user
pastes it back once the role exists.

**Alternatives considered**
- A one-click CloudFormation quick-create link. Rejected: AWS accepts
quick-create templates only from Amazon S3, so Paperclip would need to
host a public template bucket. The screen offers a download and a
console link instead.
- Instructions in a doc only. Rejected: too many hand-copied values.
- Asking for the role ARN up front. Rejected: the role does not exist
yet, so users had to invent an ARN and then match it exactly.
- Letting the user's agent report the role ARN to Paperclip itself,
through a short-lived link. Not done here: it needs a new
unauthenticated endpoint (and a Paperclip Cloud front-door change). The
user pastes the ARN instead.

## What Changed

- `packages/shared`:
  - The `saveDraft` validation allows methods with minted credentials.
  - New `AwsConnectionSetup` type.
- `server/src/services/connectors/aws/setup.ts` builds the setup values:
  - The issuer, audience and connection subject.
  - The provider host and the trust policy.
- A CloudFormation template with an optional identity provider
(`CreateIdentityProvider`), a role named `paperclip-<connection id>`,
`AccessPolicyArn` (`ReadOnlyAccess` by default for read-only
connections) and `AWSMCPSignInOAuthAccessPolicy`. The account comes from
CloudFormation, so the template needs no edits.
- The service method `getAwsSetup` and the route `GET
/api/tool-connections/{connectionId}/aws-setup`:
  - The route requires `connections:configure`.
  - It returns 422 for a connection that is not an AWS role connection.
- It reports whether the issuer key is published and any role ARN
already saved.
- It returns `available: false` (`address_changed`) when the instance
address changed after the draft was saved, since a role set up for the
old address could never pass the test.
  - It is registered in OpenAPI.
- UI:
- The AWS form no longer shows a Role ARN field (it is hidden with an
empty default).
- `AwsRoleSetup.tsx` shows, by default, only "Set it up with your agent"
(a copyable prompt that checks the AWS account, deploys the template
with `aws cloudformation deploy`, and reports the role ARN) and a field
to paste that ARN. "Or do it by hand" reveals the CloudFormation steps
(download, console link, parameter notes, IAM acknowledgement) and the
IAM console / AWS CLI steps with copyable values; the CLI commands read
the account ID themselves.
- It shows an access-key message when AWS cannot reach the instance, and
asks the user to save again when the instance address changed.
- Failed tests appear in place. AWS error codes show the server's own
plain message, because the shared error copy replaces every 502 with
"temporarily unavailable".
- `useAwsRoleSetupStep` owns the AWS sequence; `ConnectionSetupFlow`
only asks it for request options, hands back results and renders its
step:
- The first Connect for `aws-role` saves a draft and opens the AWS step.
  - "Test connection" resumes the same draft with the pasted role ARN.
- Back keeps the draft, so a later Connect updates it and does not
create a second one. Returning to an unfinished draft reopens the step.
- Docs: the `doc/connections/AWS.md` setup section and the plan's phase
table. The SDK public input pins are refreshed.

## Verification

- `server/src/__tests__/aws-mcp-connector.test.ts` covers a new
API-level case through the real route validation:
- Saving an `aws-role` draft over HTTP works without a role ARN, and
stores the keys the screen uses to reopen it.
- `aws-setup` returns the issuer, subject and the connection's role
name.
- The template's trust condition keys equal `<issuer host>:aud` and
`<issuer host>:sub`.
  - The template provider URL equals the issuer.
- After an address change it returns `address_changed`, and saving the
draft again records the new address.
  - An access-key connection returns 422.
  - No response field looks like a secret.
- `ui/src/features/connections/AwsRoleSetup.test.tsx` covers:
- Only the agent setup shows by default; Test connection stays off until
a valid role ARN is pasted, then sends it.
  - A saved role ARN is filled in.
- The by-hand steps and CLI commands; the agent prompt for read-only and
full access.
  - The template download (filename and object URL cleanup).
  - The unreachable-instance message.
  - The in-place error and the address-changed message.
  - The AWS message mapping.
- `ui/src/pages/apps/AppsConnect.test.tsx` covers the full two-step
flow: the form has no Role ARN field, the first Connect sends
`saveDraft: true` with no role ARN and does not finish, the AWS step
loads the setup, and "Test connection" resumes `aws-draft` with the
pasted role ARN and finishes. A second test reopens the step for a
returning draft.
- Red/green:
  - Removing the API change fails the API test.
  - Removing the draft-first wiring fails the flow test.
- Totals: server AWS, OpenAPI and connector tests (75), shared
`app-definitions` (42), UI connections and apps pages (1108). Typecheck
is clean for shared, server, UI (except Storybook's generated catalog,
which this worktree has not built) and all four server test-tree layers.
- Browser, on a real dev server with an HTTPS public address:
  - AWS appears in Connectors with its logo.
- The form has only region and access level. Connect saves the draft
(reusing an earlier one) and shows only the agent prompt and the role
ARN field; "Or do it by hand" reveals the CloudFormation and IAM steps.
- The copied prompt names the connection's role and stack, and the
template.
- Test connection with a pasted role ARN showed AWS's refusal in place
(no such role, placeholder issuer), as expected. An earlier run found
the generic 502 copy problem, which is fixed and re-checked.
- AWS CloudFormation `validate-template` (dev account, read-only)
accepts the current generated template (role named after the connection)
and reports `CAPABILITY_NAMED_IAM`. The screen tells the user to
acknowledge it.
- Not run: an agent actually running the prompt and creating a stack in
AWS, and Paperclip Cloud staging.

## Risks

- The feature is still behind `enableAwsConnector` (off by default). No
migration.
- The template creates IAM resources in the customer's account, and the
customer must acknowledge that. The role trusts only this connection's
subject.
- If the customer already has an identity provider for the issuer and
leaves `CreateIdentityProvider` at true, AWS fails the stack with a
clear error. The screen explains the parameter.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, the in-app browser against a local dev server, AWS
CLI `validate-template` in the dev account, an exploration subagent).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-19 10:53:53 -06:00
..
…
…

Apps, Connections, and Integrations

Audience: internal engineers and product contributors working on integrations.

Start here when adding a provider: Connection authoring runbook. It is the canonical agent tutorial from provider research and protocol classification through manifest generation, branding, secrets, deterministic tests, real-account proof, and PR submission.

Chat and email channels: conversation-channel contract, question inventory and quality bar, and per-provider question coverage index.

Runtime authentication: AI Connections.

MCP protocol versions (2026-07-28 stateless MCP and older handshake servers): MCP-PROTOCOL-VERSIONS.md.

MCP extensions: MCP Apps (interactive views in the task chat), MCP Skills (skills that connected apps publish, reviewed by the board and delivered to agents), MCP Tasks (long provider calls that survive timeouts, restarts, and deploys), MCP elicitation (an app's question to the person, answered in the task chat), and Machine sign-in (OAuth client credentials for organization connections where no person signs in).

Machine sign-in (OAuth client credentials for organization connections where no person signs in).

Long-term memory: Experimental memory connectors.

Provider notes: AWS, Google Workspace, Gmail, Asana, Sentry, PostHog, Braintrust, Neon, Superagent, Gauge, Ditto, Circleback, 1Password, Unikraft, AgentMail, Telem.AI, iMessage Photon, Enterpret, Supabase, and Vercel. Optional credential custody: Vercel Connect.

Post-read action: classify a new integration request, pick the right Paperclip layer to change, and avoid creating a parallel connection framework.

Decision Record

Board decisions from PAP-13211 make the Apps v2 substrate on the PAP-10341 branch canonical:

  • D1: Apps v2 is the substrate. The active model is tool_applications, tool_connections, catalog entries, profiles, policy rules, action requests, gateway sessions, audit events, and runtime slots. Connections v1 is retired as an implementation path.
  • D2: one credential authority per connection, brokered projections. The default is the Paperclip instance vault: durable third-party credentials live in company_secrets as secret refs. A reviewed remote MCP method may instead opt in to Vercel Connect, in which case Vercel is the durable credential authority and Paperclip stores only the connector reference and redacted grant metadata. A connection must never mix those two sources. Adapter config, plugin config, harness credential files, and run environments may receive only brokered or projected credentials.
  • D3: the vocabulary and three-door IA are product law. The default product doors are Apps, Connections, and Review. Protocol and operator-depth concepts live behind Developer or Advanced surfaces.
  • D4: unification lands on PAP-10341. Pages, CircleBack-style harness MCP OAuth, provider gallery work, and plugin-provided integrations converge on this branch instead of spawning new integration substrates.
  • D5: inbound stays thin. External clients that call Paperclip use scoped Paperclip tokens and existing profiles/rules. They do not get a separate permission model.

Canonical Object Model

Use connection as the unifying noun. A connection is four things:

  1. A stored credential reference.
  2. A capability catalog.
  3. A governance layer.
  4. An audit trail.

Everything else is an axis on that object:

Axis Values It answers
Direction outbound, inbound Who is the client?
Transport MCP, native REST/OpenAPI, OAuth app install, webhook How do bytes move?
Auth mode OAuth, API key/PAT, app installation, none What does the secret represent?
Credential owner company, user, run Whose identity acts?
Packaging catalog entry, plugin, skill How does it ship?

MCP is a transport, not a product category. "Install the Discord app", "connect Google Drive", and "add an MCP endpoint" all produce governed connections with different transport/auth values.

Layer Stack

When you are unsure where a change belongs, place it on the narrowest layer that solves the problem:

Layer Owns Examples
Surface user-facing Apps, Connections, Review, Developer/Advanced screens gallery cards, setup wizard, review queue
Governance profiles, bindings, allow/ask-first/block rules, quarantine, audit read-only profile, ask-first write policy
Capability action catalogs, schemas, risk classes, changed-tool review search_issues, create_comment, schema hash
Credential company_secrets, OAuth broker, credential resolver, token broker Slack bot token ref, Google OAuth refresh token ref
Identity actor attribution and token exchange board user, agent run, first-party service identity
Transport how the external system is reached remote HTTP MCP, local stdio, REST/OpenAPI, webhook

The agent should not hold a durable provider credential. It should hold a Paperclip run/session token; the server or broker resolves the connection, checks governance, invokes the provider, and writes audit.

Identity vs. connections

Signing a user in and connecting a resource are different planes with different owners, different token profiles, and different homes. Do not merge them. This section is the public, connections-side statement of the identity model so connector implementers inherit the rule without depending on private identity-service documentation or re-deriving it.

Plane Question Lives where Token profile
P1. Sign-in methods Who are you? paperclip-id (id.paperclip.ing → Account) Minimal-scope provider tokens (openid email profile), used once to authenticate, encrypted at rest, never exported
P2. Connections (Apps) What may your agents touch? Paperclip App instances (tool_connections), acquired via the connect broker for hosted + self-hosted Rich-scope, long-lived resource tokens in the instance's encrypted vault; per-agent grants; risk-tier policy defaults
P3. Login with Paperclip Who may authenticate against us? paperclip-id OIDC provider + DB-backed client registry Our ES256 ID/access tokens issued by us to registered RPs (instances, the broker, future third parties)

Everything in doc/connections/ — the First-30 matrix, the connection authoring runbook, and the connect-broker work — lives on plane P2. It never acquires, stores, or brokers a P1 sign-in token.

The standing rule (D7)

Adopted as a standing rule (decision D7) with the identity-model plan. State it verbatim in any P2 design so the app-store work cannot drift into merging the planes:

Sign-in tokens are never reused as resource tokens; id.paperclip.ing never stores resource tokens; no connections hub on the ID service.

P2 tokens flow broker → instance vault as pass-through only; the id.paperclip.ing Account page therefore must not grow a "Connections" hub. The reasons to hold the planes apart (from the plan §3):

  • Scope discipline. Sign-in wants the narrowest grant; connections want deliberately broad ones. One button that does both is how you grant repo access just to log in.
  • Blast radius. id.paperclip.ing holding every customer's Vercel/Slack/GitHub resource tokens would make it the single juiciest target in the fleet; the broker is intentionally pass-through.
  • Self-hosted symmetry. Instances own their vaults, so self-hosters don't depend on our uptime to use their own connections.
  • Legibility. Sign-in and connections answer different user questions, and every product we benchmarked (Vercel, Railway, GitHub, Google) keeps them on separate pages with separate names.

The explicit Vercel Connect exception does not change D7 or merge P1 and P2. The operator chooses Vercel as the P2 credential authority for an individual connection. id.paperclip.ing is not involved, and neither sign-in tokens nor provider tokens pass through it. The deployment's Vercel access token or workload OIDC identity is bootstrap authority for that external vault, not a provider resource credential.

Naming alignment

Use the surface-correct name for each plane; they intentionally differ:

Surface Plane Name to use
Paperclip App instances P2 "Connections"
id.paperclip.ing Account P1 "Ways to sign in"
id.paperclip.ing admin P3 "OIDC clients" (until the app store productizes it)

Packaging Rule

Default to a catalog entry when an integration can be described as metadata: manifest, auth config, action catalog, resource filters, and policy defaults.

Use a plugin only when the integration needs product code such as custom UI pages, its own tables, workers, migrations, routines, or specialized ingestion. A plugin may bundle catalog entries, but it must not bypass the connection, profile, policy, credential, and audit model.

Use a skill for agent instructions. Skills may use connections; they must not own durable tokens.

Canonical Docs

  • Glossary defines product and internal terms.
  • Identity vs. connections is the public statement of the P1/P2/P3 boundary and the D7 standing rule for connections work.
  • Security threat model harvests the keeper from PAP-2359 and maps it onto Apps v2.
  • First-30 matrix harvests the keeper from PAP-2432 and is the source matrix for connector playbook work.
  • Connecting any remote MCP server is the baseline: how an operator connects a standards-compliant remote MCP endpoint with no Paperclip code change, and how sign-in resolves a client.
  • Connection authoring runbook is the one end-to-end, agent-executable guide for adding a vendor as a catalog entry on Apps v2: research, connection-type selection, OAuth/API-key/generated-URL setup, encrypted credential handling, branding, implementation, browser and live-provider testing, verification, and PR submission.
  • Vercel Connect operator guide documents the optional external credential source, deployment flags, runtime resolution, recovery, and smoke requirements.
  • MCP access governance remains the operator runbook for the current gateway, profile, policy, approval, runtime, and audit APIs.

Migration Notes

Connections v1 contributed useful policy, UX, and rollout thinking, but its implementation branch is no longer the target. When you see old tickets or code using connections, connection_grants, or a provider-directory mental model, translate the intent into Apps v2:

Connections v1 intent Apps v2 home
Provider directory Apps gallery / tool_applications
Configured provider instance Connection / tool_connections
Grant allowlist Profiles, profile bindings, policies
Resource filters Policy/profile conditions plus provider config
Tool broker Tool gateway and runtime supervisor
Connection UX tail Apps, Connections, Review, Developer/Advanced IA

Do not add new work to the retired v1 branch. If an old ticket still describes a valid product gap, retarget it to an active Apps v2 issue or close it as superseded with a link to the replacement.

For Slack chat bot creation, installation, recovery, and live qualification, see Automatic Slack app setup.