mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use apps through connections to remote MCP servers
> - Today an organization connection must sign in as a person (browser
sign-in) or use a static key
> - Service accounts and CI-style integrations have no person who can
sign in
> - The MCP OAuth Client Credentials extension (2026-07-28) defines
machine-to-machine sign-in for this case
> - This pull request adds "Machine sign-in" for organization
connections, with a Paperclip-held signing key (recommended) or a client
secret
> - The benefit is that organizations can connect automation-owned MCP
servers safely, with credentials only in the vault and bound to one
sign-in service
## Linked Issues or Issue Description
**Subsystem affected**
Connections: remote MCP OAuth (server `tool-access/oauth`, tool gateway
token refresh) and the custom MCP server setup flow in the UI.
**Problem or motivation**
Organization-owned automation (service accounts, CI integrations) cannot
connect an MCP server that requires OAuth, because no person can
complete a browser sign-in. The MCP OAuth Client Credentials extension
(`io.modelcontextprotocol/oauth-client-credentials`) solves this with
`grant_type=client_credentials` and RFC 7523 signed client assertions.
**Proposed solution**
Add machine sign-in for organization connections only. Paperclip creates
a keypair per connection, keeps the private key in the company vault,
and shows the public key (PEM and JWK) for the admin to register. A
client secret is also supported. The sign-in service (issuer and token
endpoint) is pinned at setup. Tokens use the existing organization grant
refresh path, so caching, concurrent dedupe and 401 re-request reuse the
existing lease and single flight.
**Alternatives considered**
Reuse the deployment-wide `PAPERCLIP_TOOL_OAUTH_*` client env path that
already sent `client_credentials`. Rejected: it is not per connection,
it keeps secrets in env, and it has no issuer pin. Route machine sign-in
through `connectGalleryApp`. Rejected: its rollback deletes the draft on
a failed test, which would lose a key the admin already registered.
**Roadmap alignment**
Phase 1 of the enterprise MCP plan (no enterprise single sign-on
needed). OIDC login and enterprise-managed authorization (ID-JAG) are
later phases.
## What Changed
- `oauth/client-credentials.ts`: keypair generation (RS256, or ES256
when the service requires it), RFC 7638 key IDs, and RFC 7523 assertions
(`iss` = `sub` = client ID, `aud` = token endpoint, 60 s `exp`, unique
`jti`) with Node `crypto` only.
- `oauth/client.ts`: the token exchange accepts a signed assertion and
then sends only `client_assertion_type` and `client_assertion` (no
`client_id` or secret), as the extension specifies.
- `oauth/client-credentials-service.ts`: discovery of the sign-in
service (protected-resource metadata, then RFC 8414/OIDC metadata with
issuer check, or a token URL entered directly), issuer pinning,
vault-only key and secret handling, draft creation, test-and-activate,
and no-downtime rotation (test the new secret first; stage a new key and
switch only after the provider accepts it).
- `oauth/grant-refresh.ts` and `oauth/connection-refresh.ts`: machine
sign-in requests a new access token with the connection's own
credentials instead of needing a refresh token. It never falls back to
deployment-wide OAuth clients.
- `catalog/discovery.ts`: a rejected token on a machine sign-in
connection never re-runs discovery or rewrites the pinned endpoints.
- `mcp-http.ts` and the tool gateway: declare
`io.modelcontextprotocol/oauth-client-credentials` in client
capabilities only for connections that use it.
- Routes (with OpenAPI and activity logging): `POST
/companies/{companyId}/tools/machine-sign-in`, `GET|POST
/tool-connections/{id}/machine-sign-in[/test|/rotate|/rotate/complete]`.
Removal activity now records `machineSignIn: true`. The runner API
treats these routes as sensitive.
- Shared validators and types for machine sign-in.
- UI: "Machine sign-in" under Advanced authentication in the custom MCP
server flow (organization connections only), `MachineSignInSetup`
(choose Paperclip key or client secret, register the public key, test),
and Storybook stories for each setup state.
- Docs: `doc/connections/MCP-CLIENT-CREDENTIALS.md`, linked from
`doc/connections/README.md` and `GENERIC-REMOTE-MCP.md`.
## Verification
- `server/src/__tests__/tool-access-client-credentials.test.ts`: 16/16
pass. It uses a fake sign-in service that verifies real signatures
against registered keys, and a fake MCP server. It covers RS256 and
ES256 assertion claims and signatures, assertion-only client
authentication, the secret flow (`client_secret_basic`), discovery and
direct token URL, issuer pinning (refuses a different sign-in service
and sends it nothing), the pinned endpoint surviving a hostile
challenge, the token cache (0 token requests while live), concurrent
dedupe (5 callers on 2 service instances produce 1 token request), 401
re-request, key and secret rotation, a refused personal connection,
secret redaction in responses, rows and activity, and vault cleanup on
removal.
- Red/green: with the grant-refresh machine sign-in branch and the
discovery pin guard disabled, 5 runtime tests fail (pin, cache/dedupe,
401 re-request, both rotations). Restored: 16/16 pass. The other tests
cover new routes and services that do not exist on `master`.
- `ui/src/features/connections/MachineSignInSetup.test.tsx`: 3/3.
`ConnectionSetupFlow.architecture` and `.oauth` tests: 19/19.
- `openapi-routes.test.ts`: 51/51. `runner-api.test.ts`: 2153/2153.
`mcp-http.test.ts`: 9/9. Existing `tool-access-service.test.ts` refresh
and legacy client-credentials tests: 54/54 (filtered).
- Server package `tsc --noEmit`: clean. UI `tsc`: clean except the
pre-existing generated Storybook catalog imports.
- Not run locally (machine under heavy load): full suites, repo-wide
typecheck, browser check of the live app. CI covers breadth.
## Risks
- No migration. New config lives in `config.oauth` (`grantType:
"client_credentials"` plus `clientAuth`). Older env-configured
client-credentials connections have no `clientAuth` and keep their
original path.
- The capability declaration adds one extension key only for machine
sign-in connections. Other requests are unchanged.
- Rotation has no settings-page control yet; it is available through the
API. This is a follow-up.
- Low risk to agent boot and time to first token: a live token is read
exactly like a browser sign-in token.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, test runs).
## 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
- [ ] 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>
232 lines
12 KiB
Markdown
232 lines
12 KiB
Markdown
# Apps, Connections, and Integrations
|
|
|
|
Audience: internal engineers and product contributors working on integrations.
|
|
|
|
Start here when adding a provider:
|
|
[Connection authoring runbook](./CONNECTOR-PLAYBOOK.md). 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](./CONNECTOR-PLAYBOOK.md#chat-channel-connectors),
|
|
[question inventory and quality bar](./CONNECTOR-PLAYBOOK.md#question-experience-inventory),
|
|
and [per-provider question coverage index](./CHAT-QUESTION-COVERAGE.md).
|
|
|
|
Runtime authentication: [AI Connections](./AI-CONNECTIONS.md).
|
|
|
|
MCP protocol versions (2026-07-28 stateless MCP and older handshake servers):
|
|
[MCP-PROTOCOL-VERSIONS.md](./MCP-PROTOCOL-VERSIONS.md).
|
|
|
|
MCP extensions: [MCP Apps](./MCP-APPS.md) (interactive views in the task chat),
|
|
[MCP Skills](./MCP-SKILLS.md) (skills that connected apps publish, reviewed
|
|
by the board and delivered to agents), [MCP Tasks](./MCP-TASKS.md) (long
|
|
provider calls that survive timeouts, restarts, and deploys),
|
|
[MCP elicitation](./MCP-ELICITATION.md) (an app's question to the person,
|
|
answered in the task chat), and [Machine sign-in](./MCP-CLIENT-CREDENTIALS.md)
|
|
(OAuth client credentials for organization connections where no person signs
|
|
in).
|
|
|
|
[Machine sign-in](./MCP-CLIENT-CREDENTIALS.md) (OAuth client credentials for
|
|
organization connections where no person signs in).
|
|
|
|
Long-term memory: [Experimental memory connectors](./MEMORY.md).
|
|
|
|
Provider notes: [Google Workspace](./GOOGLE-WORKSPACE.md),
|
|
[Gmail](./GMAIL.md), [Asana](./ASANA.md), [Sentry](./SENTRY.md), [PostHog](./POSTHOG.md), [Braintrust](./BRAINTRUST.md), [Neon](./NEON.md), [Superagent](./SUPERAGENT.md), [Gauge](./GAUGE.md), [Ditto](./DITTO.md), [Circleback](./CIRCLEBACK.md),
|
|
[1Password](./1PASSWORD.md), [Unikraft](./UNIKRAFT.md), [AgentMail](./AGENTMAIL.md), [Telem.AI](./TELEM.md), [iMessage Photon](./IMESSAGE-PHOTON.md),
|
|
[Enterpret](./ENTERPRET.md), [Supabase](./SUPABASE.md), and
|
|
[Vercel](./vercel.md). Optional credential custody:
|
|
[Vercel Connect](./VERCEL-CONNECT.md).
|
|
|
|
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](/PAP/issues/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](./VERCEL-CONNECT.md), 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](./FIRST-30-MATRIX.md),
|
|
the [connection authoring runbook](./CONNECTOR-PLAYBOOK.md), 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](./GLOSSARY.md) defines product and internal terms.
|
|
- [Identity vs. connections](#identity-vs-connections) is the public statement
|
|
of the P1/P2/P3 boundary and the D7 standing rule for connections work.
|
|
- [Security threat model](./SECURITY-THREAT-MODEL.md) harvests the keeper from
|
|
[PAP-2359](/PAP/issues/PAP-2359) and maps it onto Apps v2.
|
|
- [First-30 matrix](./FIRST-30-MATRIX.md) harvests the keeper from
|
|
[PAP-2432](/PAP/issues/PAP-2432) and is the source matrix for connector
|
|
playbook work.
|
|
- [Connecting any remote MCP server](./GENERIC-REMOTE-MCP.md) 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](./CONNECTOR-PLAYBOOK.md) 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](./VERCEL-CONNECT.md) documents the optional
|
|
external credential source, deployment flags, runtime resolution, recovery,
|
|
and smoke requirements.
|
|
- [MCP access governance](../MCP-ACCESS-GOVERNANCE.md) 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](SLACK-AUTOMATIC-SETUP.md).
|