Devin Foley
8cbd21b3e7
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents reach external services through the Apps catalog. Each catalog entry is a reviewed `AppDefinition` that connects a provider's hosted MCP server to Paperclip's shared vault, grants, policies, gateway, and audit trail. > - Superagent (`superagent.sh`) is a security platform. Its hosted MCP server lets agents read and triage security findings, start red-team reports, run Contributor Trust and dependency update jobs, and score web pages, email, files, skills, MCP repositories, and packages before an agent trusts them. > - Superagent is not in the catalog. Operators must use the generic "Connect your own MCP server" flow. That flow has no branding, no key guidance, and no warning about billable or destructive tools. > - The connector playbook supports this provider with existing definition fields. The server accepts an organization API key as a bearer header. It publishes no OAuth authorization-server metadata, so browser sign-in is not possible. > - This pull request adds the Superagent definition, its artwork, the research and permission-review ledger rows, documentation, deterministic tests, and one reviewed risk-classification rule. > - The benefit is a branded, governed Superagent connection with clear key guidance and a warning about tools that cost credits or delete data. ## Linked Issues or Issue Description **Problem or motivation** Teams that use Superagent for PR security, red teaming, and agent guardrails want their Paperclip agents to read findings, return structured reports, and score content before they use it. Superagent is not in the Apps catalog. Operators must paste the MCP URL and an `Authorization` header into the generic remote-MCP flow. That flow gives no branding and no provider guidance. It also does not tell the operator that the key reaches the whole organization, or that some tools consume credits or permanently delete findings. **Proposed solution** Add a catalog-only Superagent connection that follows the connector playbook. It has one method: a customer organization API key (`sk_live_...`), sent as an `Authorization: Bearer` header to `https://www.superagent.sh/mcp`. The field helper text explains that Superagent keys are not scoped. The method warning tells operators to set billable and destructive actions to Ask first before agents run unattended. All discovered tools stay governed by the normal per-action policies. **Alternatives considered** A browser sign-in method was not added. The server's protected-resource metadata names `https://superagent.sh` as its authorization server, but that origin publishes no `oauth-authorization-server` or `openid-configuration` document, so Paperclip cannot discover OAuth endpoints. A plugin was not needed because the connection needs no custom UI, tables, workers, or webhooks. Relying on the generic risk classifier was not enough. Several Superagent mutations (`triage_finding`, `scan_*`, `restore_agent_builtin_rule`) use names that it reads as reads, so a narrow reviewed Superagent rule was added instead. **Roadmap alignment** This extends the existing self-serve remote-MCP connection catalog. It does not overlap planned core work. ## What Changed - Added the `superagent` row to `packages/shared/src/self-serve-mcp-research.json` (API-key auth, risk tier S4). - Added the `superagent` provider to `scripts/ingest-app-definitions.mjs` (category, key placement and placeholder, console links, guidance, description). Regenerated `packages/shared/src/app-definitions/superagent.json` and the generated registry. - Added the `superagent/mcp-api-key` permission review to `doc/connections/tool-method-permission-reviews.json`, with key-permission text and evidence links. - Added Superagent's official mark (`ui/public/brands/apps/superagent.png`, the 460×460 avatar of the official `superagent-ai` GitHub organization) and the brand manifest entry. - Added gallery copy for the Superagent card. - Added a reviewed Superagent rule to `classifyRisk` in `server/src/services/tool-access.ts`. Only `list_*` and `get_*` tools, and tools that Superagent marks read-only, are reads. `delete_*` and `revoke_agent_client` are destructive. All other tools are writes, so billable and rule-changing tools can be set to Ask first. - Put the Ask-first advice in the API-key helper text, because the key form shows helper text and not method warnings. - Added `doc/connections/SUPERAGENT.md` (transport and auth, why there is no OAuth, administrator setup, capabilities and policy, manifest, brand provenance, validation hook). Linked it from the connections README and the permission audit. - Tests: definition shape, store visibility and artwork, URL recognition, the bearer header on discovery with the key kept out of connection config, read/write/destructive classification of fixture tools, the Superagent risk rule (including `triage_finding` and `restore_agent_builtin_rule`), the visible Ask-first advice and API-key gating of the connect form, and the pinned catalog counts. ## Verification - `pnpm exec vitest run packages/shared/src/app-definitions.test.ts packages/shared/src/app-definitions-url.test.ts ui/src/pages/apps/AppsConnect.test.tsx ui/src/pages/apps/Browse.test.tsx ui/src/lib/app-brand-assets.test.ts ui/src/pages/apps/AppLogo.brand-assets.test.tsx`: 317 passed. - `pnpm exec vitest run server/src/__tests__/tool-access-service.test.ts`: 385 passed. - `node scripts/check-app-brand-assets.mjs` and `node --test scripts/app-brand-validation.test.mjs`: passed. - `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter @paperclipai/server typecheck`, and `pnpm --filter @paperclipai/ui typecheck`: clean. - Manual: in a local instance, open Apps → Browse and confirm the Superagent card and icon. Open `/apps/connect?source=superagent`. Confirm the single API-key method, and confirm that Connect enables only after a key is entered. - Live metadata probe on 2026-10-06: an unauthenticated `initialize` on `https://www.superagent.sh/mcp` returns 401 with `resource_metadata="https://www.superagent.sh/.well-known/oauth-protected-resource"`. That document returns 200. No authorization-server metadata exists at the named issuer. ## Risks - Low risk to existing providers. The change is additive catalog data plus tests. The generated registry only gains one import. The new risk rule runs only for Superagent connections. - A Superagent key reaches its whole organization. Some tools consume credits (`create_*_report`, `triage_finding`) or delete data permanently (`delete_finding`). Every action starts Allowed under the current product default. The key helper text tells operators to set these actions to Ask first. - The permission-review ledger records live proof as not run. No Superagent account was used. The lifecycle checklist in `doc/connections/SUPERAGENT.md` needs a documented pass before the entry is fully qualified. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`, 1M context) in Claude Code, with extended thinking and tool use (shell, file editing, web fetch, browser checks). ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
13 KiB
Tool connection permission audit — 2026-09-30
This review covers 119 tool methods (85 OAuth methods). The machine-readable source of reviewed defaults lists each method's exact requested scopes, supported actions, restrictions, sources and verification limits. AI runtime authentication and chat/channel setup are separate contracts and were not changed.
Methods reviewed after this audit carry their own reviewedAt date in the same
ledger; the counts above are not restated. Later additions: Neon
(mcp-oauth, mcp-api-key; 2026-10-02), Superagent
(mcp-api-key; 2026-10-06).
Shared credential failure
Zapier's secret URL exposed a shared ownership/resolution problem. The same invariants apply to personal pasted-key and custom-header methods, including Bitly, Cloudflare, Coda, Fireflies, GitHub PATs, Kernel, O'Reilly, PagerDuty, PostHog, Postman, Razorpay, Sanity, Similarweb, Stripe, Supabase and You.com. Generic MCP setup uses this path too, so “Connect your own” was not a reliable workaround. This is a code-path finding, not a claim that every provider was tested with a live account.
Personal invocation secrets now belong to the grant's user. Setup, health, discovery and the run gateway share ownership checks and canonical credential paths. Public unauthenticated URLs need no credential repair. OAuth client registration secrets remain company-owned and separate from invocation tokens. Existing connections with incorrectly owned credentials require the owner to reconnect with a fresh key or secret URL. There is no automatic ownership backfill.
Changes
- Airtable now requests its seven documented record, schema, comment and workspace/base scopes, including writes.
- Explicit scope sets were added for providers that advertise a scoped MCP resource, including Beehiiv, Netlify, Miro, Sentry, Supabase, Todoist and TickTick. Read and write remain subject to provider roles and resource selection.
- Hugging Face adds repository read/contribution and jobs to
read-mcp. Optional tools still need enabling in HF's MCP settings. - Slack's reviewed set now covers the documented message, channel, reaction, canvas, file and list actions. It replaces the obsolete generic search scope with the documented search scopes. The fixed app/approval gate remains.
- Google write/draft methods take priority over managed read-only methods when available. Existing Google profiles, preview verification and availability gates remain. People and Workspace Search stay read-only.
- The hosted Fireflies server also exposes meeting sharing, renaming, moving and soundbite creation. Its identity scopes are retained; meeting ownership and team roles decide which mutations succeed.
- Provider read-only choices stay available under Advanced. Existing OAuth tokens and action restrictions are untouched. Permissions offers reconnect when provider consent needs changing.
Provider-default exceptions
These are deliberate exceptions to supplying scopesHint, not claims that an
old grant can write. Several servers put resource/permission selection in their
own consent screen; Box uses registered app scopes, and managed GitHub uses
installation permissions. An authorization server's general scope catalog is
not a safe substitute for the MCP permission contract.
| Provider / method | Reason and limits |
|---|---|
bitly / mcp-oauth |
The official MCP quickstart uses browser authorization without client-selected scopes; neither protected-resource nor authorization-server metadata advertises a scope list. Bitly account permissions govern link actions. Evidence |
box / mcp-own-oauth |
Box requires scopes (including Manage AI) on the registered Box app in the Admin Console. Its MCP authorization metadata has no request-scope list; consent and the app registration control file operations. Evidence |
egnyte / mcp-oauth |
The hosted authorization server selects the Egnyte tenant/account permissions. Neither MCP nor authorization-server metadata advertises request scopes. Documentation rendered no readable body during this review; tenant-bound write proof remains required. Evidence |
github / managed |
Managed github.code uses a GitHub App installation and selected repositories. Installation permissions, not OAuth scope strings, grant code and pull-request writes; retain the managed profile. Evidence |
make / mcp-oauth |
Make documents selecting scopes and scenarios during its hosted connection flow. Management tools require a paid plan. Do not replace that resource selection with invented MCP client scopes. Evidence |
oauth-generic / oauth |
Operator-defined OAuth endpoints have no provider-specific reviewed scope list. Request only the scopes supplied by the operator; this template is not a curated provider allowlist. Evidence |
planetscale / mcp-oauth |
PlanetScale documents choosing organizations, databases and read/write permission at authorization. Its general authorization server advertises unrelated organization administration too; retain the provider consent selection, and the separate insights-only endpoint. Evidence |
planetscale / mcp-insights-only |
PlanetScale documents choosing organizations, databases and read/write permission at authorization. Its general authorization server advertises unrelated organization administration too; retain the provider consent selection, and the separate insights-only endpoint. Evidence |
posthog / mcp-oauth |
PostHog documents the no-scope MCP setup as read/write, with optional readonly and feature filters. The authorization server advertises account administration unrelated to many tools; retain its MCP consent defaults and the existing explicit filters. Evidence |
postman / mcp-oauth-minimal |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
postman / mcp-oauth-code |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
postman / mcp-oauth-full |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
razorpay / mcp-oauth |
Neither protected-resource nor authorization-server metadata advertises scopes. Keep hosted provider consent; the previous official OAuth documentation URL returned 404 during review. Account-bound writes need live confirmation. Evidence |
ticket-tailor / mcp-oauth |
Hosted authorization controls box-office API-key permissions; do not treat OAuth sign-in as increasing the underlying key permissions. This method requires account-bound proof. Evidence |
webflow / mcp-oauth |
The official MCP setup installs the Bridge App and asks users to authorize sites. Neither protected-resource nor authorization-server metadata publishes a request-scope list; the installed app and site selection govern writes. Evidence |
Read-only and provider-controlled methods
Candid, Context7, O'Reilly, Similarweb and You.com expose retrieval/research capabilities rather than document/account mutation. PlanetScale's insights-only endpoint deliberately excludes query execution. Xero's current published MCP scope set includes invoice/report reads and settings access, without invoice write permission. Do not widen these using unrelated general API scopes.
Scopes such as openid, global, mcp:all or workspace:member do not have to
contain the word “write” to authorize work. The provider's MCP tool contract,
role and consent selection determine their meaning. In particular, Cloudflare,
Vercel, Wix, Kernel and Supermemory retain their provider-side permission gates.
Evidence and verification boundaries
Official docs and unauthenticated protected-resource/authorization metadata were retrieved on 2026-09-30. The review records source URLs per method. Some pages (especially Egnyte and Razorpay's old OAuth URL) were unavailable or unreadable; those entries explicitly retain that limitation. Embat publishes identity metadata but no verified write contract. No account-bound write guarantee is made for these entries.
No provider account was used for live read/write verification in this task. In particular, public scope metadata is not proof that an existing token has those permissions or that an account has the required paid plan, resource ACLs, admin approval, or Google preview enrollment. Use test accounts/resources for that proof before claiming provider-level acceptance.
Backend regressions execute catalog Zapier, generic secret URLs, personal bearer/custom headers, organization credentials and public URLs through the run-scoped gateway using a fixture transport. They assert canonical persisted ownership/declarations and run read and write calls. Reconnect regressions cover replacing legacy company credentials with user-owned values and declarations. OAuth fixtures assert exact authorization scopes and rejection of an unrelated advertised admin scope; they do not contact provider accounts.
The managed worktree has a separate instance configuration and database path.
Local CLI provisioning was attempted with both minimal and full seed modes;
both failed while applying the copied database's migrations because
tool_connections_transport_check was missing. The development instance was
not started from that clone. Clean fixture databases were used for the backend and Apps browser
checks; their success does not establish successful seeding of that local copy.
Embedded-browser acceptance
On 2026-09-30, a hands-on walkthrough used the PR checkout's built UI and actual server, a fresh isolated database created through CLI onboarding, and a local HTTP MCP fixture. Starting from the sidebar's Connectors page, the operator selected “Just me,” entered a bearer key, and created and read back a disposable widget through the Permissions screen's agent test controls.
After seeding the legacy ownership mismatch in that disposable connection,
invocation and catalog refresh rejected it with grant_credential_invalid.
The catalog showed “Needs attention” and offered Reconnect. Replacing the key
through that UI preserved the connection and personal grant, created a fresh
user-owned secret and canonical declaration, and restored writes. The legacy
company secret retained its ownership. Separate HTTP calls through a session
bound to a fixture agent run also completed a write and read-back.
The walkthrough exposed and verified fixes for a false “Still not working” message after successful reconnect, incorrect action-input advice for ownership errors, and Cancel attempting to save an invalid Zapier URL. The browser reconnect regression now performs the replacement through the form and checks that the stale warning disappears.
A second personal connection used a secret URL. After reproducing its legacy ownership failure, the browser could replace the URL and create/read back a widget. Generic reconnect now derives URL/header fields from the stored credential placement instead of assuming a bearer key, and rejects replacement URLs for a different public endpoint. A new public, organization-wide connection also appeared immediately when returning to Browse, without a page reload. The walkthrough fixed setup cache invalidation and a cramped reconnect banner.
Zapier's URL validation and cancellation were exercised, but a live Zapier connection was not completed. Gmail stopped at instance enrollment. Neither journey establishes provider-account consent or live provider read/write proof.
Automated verification
- Run
pnpm -r typecheck,pnpm build, andpnpm check:token-gates. - The affected Apps browser suites passed 10 tests, with one existing restart case skipped. These used clean, isolated fixture databases.
- Run
pnpm test:runfor the full suite. Current-head CI and local results are recorded in the pull request; fixture coverage is distinct from provider proof. - New gateway fixtures execute both read and write calls through real run-scoped gateway sessions. They also verify that invalid ownership requires reconnect and that the owner's fresh credentials restore access without changing identity.