Files
PaperClipAI/doc/connections/AWS.md
T
651749bdb4 feat(connections): AWS connector with credentials minted per connection (#22195)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use outside services through connections, and the control
plane holds each connection's credentials
> - Companies want agents to "do things on AWS" with exactly the
permissions they choose, without Paperclip storing long-lived AWS keys
or rebuilding the AWS API
> - AWS hosts an MCP server that runs any AWS API call in its own
sandbox, and it accepts a one-hour bearer token that can be minted from
IAM credentials
> - This pull request adds an AWS connection that mints that token for
each connection at call time. The role method proves the connection with
the company's workload identity issuer (#22083), so no AWS key is stored
> - The benefit is that each AWS connection carries its own role and
permissions, AWS enforces them, and agents never see any AWS credential

## Linked Issues or Issue Description

Refs #22083 (workload identity issuer) and #22191 (spike findings).

**Subsystem affected**
Connections (tool access), tool gateway, shared app definitions,
instance settings.

**Problem or motivation**
Paperclip has no way to connect AWS. AWS's hosted MCP server needs a
bearer token from AWS Sign-in, minted from IAM credentials. No existing
credential path mints a header at call time from a role or key.

**Proposed solution**
Methods can declare `credentialMinter: "aws_mcp"`. The gateway and
connection health checks mint the `Authorization` header at call time,
and they share one in-memory cache per connection and grant (about 55
minutes). There are two methods:
- Role (`AssumeRoleWithWebIdentity` with a Paperclip-signed connection
token).
- Access key (the key directly, `GetFederationToken`, or `AssumeRole`).

Read-only connections add `ReadOnlyAccess` and
`AWSMCPSignInOAuthAccessPolicy` as session policies, so AWS refuses
changes. The feature is behind the `enableAwsConnector` experimental
setting.

**Alternatives considered**
- Run AWS's `mcp-proxy-for-aws` process on the control plane. Rejected:
it adds a Python runtime and processes, and gives nothing the token
exchange does not.
- Put credentials in the agent sandbox and use the AWS CLI. Deferred:
there is no per-call governance, and every sandbox would need the CLI.
- Add a new `credentialSource`. Rejected: it needs a migration, and the
`vercel_connect` database rules do not fit stored access keys.

## What Changed

- `packages/shared`:
- `credentialMinter` on connection methods. The validator requires
`mcp_remote` and `api_key`, and does not allow `keyPlacement` or another
credential source.
- The `aws` app definition (two methods, reviewed tools,
`mcpSessionRequired`, experimental key).
- The `enableAwsConnector` setting in the catalog, types and validators.
  - `aws` added to the connectable apps.
- `server/src/services/connectors/aws/mcp-credentials.ts`:
- Settings parsing and checks. The URL must be AWS's endpoint for the
saved region, and the role ARN must be valid.
- The minter: role or key session, read-only session policies, Sign-in
exchange, cache keyed on settings, key references and status, in-flight
de-duplication, eviction.
- A plain-language error mapping that never shows AWS's own text,
because that text can contain account IDs and ARNs.
- Gateway (`resolveCredentialHeadersUnrecorded`), credential access
(`resolveCredentialHeaders`), catalog discovery and health-failure
mapping:
  - The AWS branch.
- After a 401, the gateway evicts the token and mints again, then
requires an explicit retry (no replay). Discovery lists again.
- Setup:
- Minted methods may save a draft without contacting the provider. The
role must trust a connection that already exists.
- Saving an AWS role draft publishes the company's issuer, so AWS can
validate it when the customer registers it.
- `workload-identity.ts`: a draft connection can get a token, so setup
can test it. Disabled, archived or switched-off connections still get
none.
- `server/package.json`: `@aws-sdk/client-sts` and
`@aws-sdk/client-signin`. The lockfile is left to the refresh workflow.
- Artwork: AWS light and dark marks from LobeHub's MIT icon set (already
licensed in the repo). The manifest entry passes the brand checks.
- `scripts/ingest-app-definitions.mjs`: minted methods are exempt from
the `keyPlacement` requirement. The override source is
`scripts/app-definition-overrides/aws.json`. Permission reviews are
added.
- UI: the experimental settings toggle, in alphabetical position.
- Docs: `doc/connections/AWS.md`, the connections index, the issuer API
doc (draft rule), and the plan's phase table.

## Verification

- `server/src/services/connectors/aws/mcp-credentials.test.ts` (7 tests)
covers these items:
  - Both methods and the read-only policies.
  - Caching, revision, forced refresh, expiry and eviction.
  - Concurrent de-duplication.
  - The error mapping, with no AWS text leaking.
- Settings validation, including the URL and region check and the rule
that an unknown access level means read only.
- `server/src/__tests__/aws-mcp-connector.test.ts` (3 tests, real setup,
catalog and gateway code with a fake AWS and a session-requiring fake
MCP server) covers these items:
  - The setting gates setup.
  - The access key is never sent as a header or stored in config.
  - A cached token is reused.
  - After a 401, a fresh token is minted and the call is not replayed.
  - Role draft-then-resume publishes the issuer.
  - The signed token has the right `iss`, `sub` and `aud`.
  - An AWS refusal shows a plain health message without the account ID.
- Red/green:
  - Removing the gateway hook fails the access-key test.
  - Turning off `mcpSessionRequired` fails both integration tests.
- Removing draft support for minted methods fails both integration
tests.
  - Restoring each change passes again.
- Nearby suites: `tool-gateway-service`, `tool-access-service`,
`remote-mcp-connectors`, `instance-settings-service`,
`workload-identity`, plus the new files. 775 of 775 pass.
- Shared `app-definitions.test.ts` passes (42), including new
`credentialMinter` schema tests. UI `InstanceExperimentalSettings` (63)
and the brand asset tests pass. `check-app-brand-assets` validates 112
identities.
- Typecheck is clean for `packages/shared`, `server` and `ui`. The only
UI errors are in Storybook's generated catalog files, which this
worktree has not built.
- **Real AWS** (Paperclip dev account, integrated code path, issuer
behind a temporary public tunnel):
- Access key, read only: 8 tools listed. `run_script` `ListBuckets`
succeeded in 8.9 s on a cold sandbox. AWS refused `CreateBucket` ("no
session policy allows").
- Role: the draft was saved without contacting AWS, and the issuer was
published. After an IAM provider and a role trusting only that
connection were created, resuming setup listed 8 tools. `ListBuckets`
succeeded in 12.8 s. The role's own permissions refused `CreateBucket`.
- This run found two bugs the fakes did not: AWS needs MCP sessions for
calls, and the role method needs draft-first setup with the issuer
published. Both are fixed and both now have tests.
- All IAM users, keys, roles, providers and buckets were deleted, and a
listing confirmed it.
- Not run: Paperclip Cloud staging (the setting is off by default), and
`AssumeRole` from an access key with a role ARN against real AWS (unit
tests only).

## Risks

- The feature is off by default, behind `enableAwsConnector`. No
migration.
- New dependencies `@aws-sdk/client-sts` and `@aws-sdk/client-signin`
are in the existing `@aws-sdk` family (the server already uses
`client-s3`).
- Minted tokens are held only in process memory. A restart mints again.
A cached token can outlive a deactivated key by up to an hour, unless
AWS returns 401, which evicts it.
- `aws___run_script` is classified as a write, so the normal approval
and ask-first policy applies. Read-only connections rely on AWS session
policies.
- The guided setup screen and the CloudFormation template are not in
this PR. Setup uses the generic form and the documented draft and resume
steps.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, AWS SDK for JavaScript against the Paperclip dev AWS
account, a Cloudflare quick tunnel, 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-18 12:48:49 -06:00

7.9 KiB

AWS

The AWS connection lets agents work in an AWS account through AWS's hosted MCP server (https://aws-mcp.<region>.api.aws/mcp). Paperclip stores no long-lived AWS key for the role method. For each connection, the control plane mints a one-hour bearer token at call time. Agents see the AWS tools like any other connector's tools and never receive AWS credentials.

It is behind the enableAwsConnector experimental setting (off by default). The design and the spike that proved it are in the AWS connector plan and the workload identity issuer.

Vendor

  • App key: aws
  • App name: AWS
  • Reuse classification: MCP-direct (AWS-hosted MCP server), with credentials minted by Paperclip.
  • Security tier: S4
  • Plugin needed? No

Transport and auth

  • Transport: mcp_remote. The endpoint is chosen from AWS's eight published regions. Tool calls need an initialized MCP session (mcpSessionRequired).

  • Auth: the method declares credentialMinter: "aws_mcp". Stored credential fields are inputs to the minter and are never sent as headers. The gateway and connection health checks resolve the Authorization header in server/src/services/connectors/aws/mcp-credentials.ts.

  • Role method (aws-role, recommended): no stored keys.

    1. The connection proves itself with a 5-minute token signed by the company's workload identity issuer (sub = connection:<id>, aud = sts.amazonaws.com).
    2. STS AssumeRoleWithWebIdentity returns role credentials.
    3. AWS Sign-in CreateOAuth2TokenWithIAM (client_credentials, resource aws-mcp.amazonaws.com) returns the bearer token.

    This method needs a public HTTPS address that AWS can reach.

  • Access-key method (aws-access-key): a dedicated IAM user's key, stored as this connection's vault secrets (credentials.accessKeyId, credentials.secretAccessKey). Read only uses GetFederationToken. Full access uses the key directly. With a role ARN, the minter uses AssumeRole. This method works on any instance, including local ones.

  • Access level is set per connection:

    • read_only (the default) adds ReadOnlyAccess and AWSMCPSignInOAuthAccessPolicy as session policies, so AWS refuses changes even when the role allows them. Without the second policy, the token exchange fails.
    • full uses everything the role or key allows.
  • Caching: the token is cached in memory for each connection and grant until about 55 minutes in. It is minted again when these change:

    • the saved settings;
    • the stored key references;
    • connection or grant status.

    When AWS answers 401, the gateway mints a fresh token and does not replay the call. The caller retries. Catalog discovery lists again automatically.

  • Revocation: delete the connection, or remove the role's trust or the IAM user's key in AWS. Tokens already issued expire within the hour.

Connection flow

sequenceDiagram
    participant Agent
    participant Gateway as Paperclip control plane
    participant STS as AWS STS
    participant Signin as AWS Sign-in
    participant MCP as AWS MCP server
    Agent->>Gateway: tools/call aws___run_script
    Gateway->>Gateway: sign connection token (cached bearer skips the next three steps)
    Gateway->>STS: AssumeRoleWithWebIdentity (role, token, read-only policies)
    STS->>Gateway: fetches issuer JWKS, returns role credentials
    Gateway->>Signin: CreateOAuth2TokenWithIAM (SigV4 with role credentials)
    Signin->>Gateway: bearer token (1 hour)
    Gateway->>MCP: tools/call with Authorization Bearer
    MCP->>Gateway: result (AWS ran the script in its sandbox)
    Gateway->>Agent: result
  • Issuer discovery: GET /oidc/companies/<companyId>/.well-known/openid-configuration
  • Issuer keys: GET /oidc/companies/<companyId>/jwks.json
  • Paperclip callback: none.
  • Paperclip ID / Paperclip Connect involvement: none. The instance is its own OIDC issuer.

Administrator setup

The role method uses three steps, because the role must trust a connection that already exists:

  1. Turn on AWS connector in Instance Settings, Experimental.
  2. Save a draft. Call connectGalleryApp with saveDraft: true, the role ARN to be created, the endpoint region and the access level. Paperclip creates the connection without contacting AWS. It also publishes the company's issuer, so AWS can validate it in the next step.
  3. In the AWS account:
    • Register the issuer https://<instance>/oidc/companies/<companyId> as an IAM OIDC identity provider with audience sts.amazonaws.com.
    • Create the role. Its trust policy allows sts:AssumeRoleWithWebIdentity only when <issuer host/path>:sub equals connection:<connectionId> and :aud equals sts.amazonaws.com.
    • Attach AWSMCPSignInOAuthAccessPolicy and the permissions agents need.
  4. Resume with resumeConnectionId. Paperclip mints a token, lists the tools, and the connection becomes active.

For the access-key method, create a dedicated IAM user with AWSMCPSignInOAuthAccessPolicy, sts:GetFederationToken and the agents' permissions. Then connect with the key. Setup lists the tools immediately.

A guided setup screen and a CloudFormation template are planned next. Until then, the generic setup form and these steps apply.

Verify: the connection lists 8 tools. A test call of aws___run_script that runs ListBuckets succeeds. With read-only access, a CreateBucket call is refused by AWS with "no session policy allows".

Tools and risk

Reviewed tool risk is declared in the app definition:

  • Writes: aws___run_script (the only tool that calls AWS APIs) and aws___get_presigned_url.
  • Reads: documentation search and read, skills, regions, regional availability and task status.
  • Unlisted tools: treated as writes.

Read-only connections are enforced by AWS through the session policy, not by hiding run_script.

Failure codes

Each code appears on the connection's health with a plain message. AWS's own error text is never shown, because it can contain account IDs and ARNs.

Code Health Meaning
aws_mcp_settings_invalid error Saved settings are incomplete, or the URL is not AWS's endpoint for the saved region.
aws_identity_unavailable error The role method needs a stable public HTTPS address.
aws_issuer_changed error The instance's address changed since setup. Register the new issuer in AWS (and update the role's trust), then reconnect: reconnecting records the current address.
aws_role_access_denied error AWS refused the role: it is missing, or its trust does not match this connection.
aws_access_key_invalid error The access key is invalid or inactive, or the user cannot call GetFederationToken.
aws_mcp_signin_denied error The token exchange was refused. Attach AWSMCPSignInOAuthAccessPolicy.
aws_unavailable degraded AWS did not respond, or throttled the request.

Verification record

On 2026-11-18, the integrated path ran against the Paperclip dev AWS account. It used Paperclip's own setup, catalog and gateway code, real STS and Sign-in, and AWS's MCP server. The issuer was behind a temporary public tunnel.

  • Access key, read only: 8 tools listed. run_script ListBuckets succeeded in 8.9 s (cold sandbox). CreateBucket was refused by the session policy.
  • Role: the draft was saved without contacting AWS, and the issuer was published. After the IAM provider and a role trusting only that connection were created, resuming setup listed 8 tools. ListBuckets succeeded in 12.8 s (cold sandbox). CreateBucket was refused by the role's own permissions.

All IAM users, keys, roles, providers and buckets were deleted afterwards.

Not live-tested yet: Paperclip Cloud staging, the CloudFormation template (not built yet), and AssumeRole from an access key with a role ARN (covered by unit tests only).