## 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>
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 theAuthorizationheader inserver/src/services/connectors/aws/mcp-credentials.ts. -
Role method (
aws-role, recommended): no stored keys.- The connection proves itself with a 5-minute token signed by the company's
workload identity issuer (
sub = connection:<id>,aud = sts.amazonaws.com). - STS
AssumeRoleWithWebIdentityreturns role credentials. - AWS Sign-in
CreateOAuth2TokenWithIAM(client_credentials, resourceaws-mcp.amazonaws.com) returns the bearer token.
This method needs a public HTTPS address that AWS can reach.
- The connection proves itself with a 5-minute token signed by the company's
workload identity issuer (
-
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 usesGetFederationToken. Full access uses the key directly. With a role ARN, the minter usesAssumeRole. This method works on any instance, including local ones. -
Access level is set per connection:
read_only(the default) addsReadOnlyAccessandAWSMCPSignInOAuthAccessPolicyas session policies, so AWS refuses changes even when the role allows them. Without the second policy, the token exchange fails.fulluses 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:
- Turn on AWS connector in Instance Settings, Experimental.
- Save a draft. Call
connectGalleryAppwithsaveDraft: 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. - In the AWS account:
- Register the issuer
https://<instance>/oidc/companies/<companyId>as an IAM OIDC identity provider with audiencests.amazonaws.com. - Create the role. Its trust policy allows
sts:AssumeRoleWithWebIdentityonly when<issuer host/path>:subequalsconnection:<connectionId>and:audequalssts.amazonaws.com. - Attach
AWSMCPSignInOAuthAccessPolicyand the permissions agents need.
- Register the issuer
- 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) andaws___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_scriptListBucketssucceeded in 8.9 s (cold sandbox).CreateBucketwas 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.
ListBucketssucceeded in 12.8 s (cold sandbox).CreateBucketwas 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).