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
7.4 KiB
Superagent
Updated: 2026-10-06. Status: catalog definition reviewed against official documentation and live provider metadata; live account qualification outstanding.
Superagent (superagent.sh) is a security platform: PR security scans,
dependency updates, red-team reports, context guardrails that score content
before agents consume it, and runtime guardrails for coding agents. It appears
in Apps and uses Paperclip's shared remote-MCP connection, vault, catalog,
grants, policies, gateway, and audit trail. It is a resource connection, not
Paperclip sign-in. No plugin or database migration is required. The only
provider-specific runtime code is a reviewed risk-classification rule.
Paperclip connects to Superagent's hosted MCP server at
https://www.superagent.sh/mcp (Streamable HTTP) with one method: an
organization API key stored as a Paperclip secret and sent as an
Authorization: Bearer sk_live_... header.
The www host is pinned deliberately. The bare superagent.sh domain
redirects to www, and Superagent documents that some MCP clients fail on
that redirect for POST requests.
This curated connection is the polished route: it provides branding, key guidance, and a billable/destructive-tool warning. None of it is required to reach Superagent's server. It can also be connected generically from Connect your own MCP server with the same URL and header. See Connecting any remote MCP server.
Service involvement
Superagent hosts the MCP resource. Paperclip stores the key as a secret
reference, discovers tools with tools/list, and sends the key on every
governed call. No Paperclip-operated vendor relay is involved; cloud and
self-hosted instances use the same path.
Administrator setup
- In Superagent, open Settings → API keys (
/app/settings#api-keys) and create a key for Paperclip. Use a separate key so it can be revoked independently. - In Paperclip, open Apps → Browse → Superagent, paste the key, and click Connect.
- On the connection's Permissions screen, set the billable and destructive actions listed below to Ask first or Off if agents run unattended.
Revoke the key in Superagent, then remove the connection in Paperclip, to disconnect.
Capabilities and policy
The server exposes roughly 70 tools that mirror the Superagent REST API: findings and triage, red-team reports, Contributor Trust scans, dependency update runs, context-guardrail scoring (web pages, email, messages, files, skills, MCP repositories, packages), Applications, Agents and endpoint clients, runtime guardrail groups, rules and alerts, OpenTelemetry destinations, and the structured agent report return path.
Superagent's documentation calls out these tools:
- Billable:
create_repository_report,create_web_app_report,create_agent_report,create_package_report,triage_finding. - Permanent deletes:
delete_finding,delete_telemetry_endpoint. Thedelete_agent_groupanddelete_agent_ruletools also delete. - Immediate endpoint-policy changes:
set_agent_builtin_rule_mode,restore_agent_builtin_rule.
Paperclip applies a reviewed Superagent risk rule in classifyRisk, because
several mutations use names the generic classifier reads as reads
(triage_finding, scan_*, restore_agent_builtin_rule). Only list_* and
get_* tools, and tools Superagent marks readOnlyHint: true, are reads.
delete_* and revoke_agent_client are destructive. Everything else is a
write. The API-key helper text tells operators to put billable and
destructive tools behind Ask first.
Vendor
- Product: Superagent,
https://www.superagent.sh. - MCP documentation:
https://www.superagent.sh/docs/mcp. - API keys:
https://www.superagent.sh/docs/reference/settings. - Rate limits: per key per minute; HTTP 429 with
Retry-After.
Transport and auth
- Transport:
mcp_remote, Streamable HTTP. - Auth:
api_key,Authorization: Bearer <key>. Keys use thesk_live_prefix. - Key permissions: not scoped. A key reaches everything in its organization. Paperclip cannot narrow an issued key.
- OAuth: not offered. The server returns
WWW-Authenticate: Bearer ... resource_metadata="https://www.superagent.sh/.well-known/oauth-protected-resource", and that document nameshttps://superagent.shas its authorization server, but neither/.well-known/oauth-authorization-servernor/.well-known/openid-configurationexists there, so browser sign-in cannot be discovered. Add an OAuth method if Superagent publishes authorization-server metadata.
Resource filters
None. Superagent documents no query or header options that narrow the hosted server. Narrowing is done with per-action policies.
Manifest
| Field | Value |
|---|---|
| Slug | superagent |
| Category | developer |
| Method | mcp-api-key (customer ownership, risk tier S4) |
| Server URL | https://www.superagent.sh/mcp |
| Credential | authorization, password, required, placeholder sk_live_... |
| Key placement | header Authorization, prefix Bearer |
| Console links | keys https://www.superagent.sh/app/settings#api-keys, docs https://www.superagent.sh/docs/mcp |
The definition is generated from the superagent row in
packages/shared/src/self-serve-mcp-research.json and the superagent branch
of specialMethodsFor in scripts/ingest-app-definitions.mjs.
Wizard path
/apps/connect?source=superagent opens a single-method form: the API key
field and Connect, which stays disabled until a key is entered. A
successful key check and tool discovery lead to the connection's
Permissions screen.
Governance defaults
- Default profile and bindings: the standard connection profile; every discovered action starts Allowed under the current product default.
- Policies: operators narrow billable and destructive tools to Ask first or Off on the Permissions screen.
- Risk: the reviewed Superagent rule in
classifyRiskdescribed above. - Quarantine rules: the shared defaults; no Superagent-specific exceptions.
Brand provenance
Superagent's site publishes its pyramid mark only as 32×32 WebP favicons
(light and dark), below the catalog's 128px minimum. The same mark is the
avatar of Superagent's official GitHub organization (superagent-ai, whose
profile links https://superagent.sh), published as a 460×460 transparent
PNG. That file is used unchanged in both themes.
| File | Source | SHA-256 |
|---|---|---|
ui/public/brands/apps/superagent.png (460×460) |
https://avatars.githubusercontent.com/u/152537519?v=4&s=512 |
2c731c7a4cdaabe2ed341b141dc75608e23b362b9a6e5ee81d1c7a373154fbcf |
Validation hook
- Environment: definition review on 2026-10-06 against
origin/master; no Superagent account was used. - Metadata probe: an unauthenticated
initializeon/mcpreturned HTTP 401 with theresource_metadataheader above; the protected-resource document returned HTTP 200; no authorization-server metadata was found. - Deterministic tests: manifest shape, store visibility, artwork, URL recognition, bearer-header projection with the key kept out of connection config, risk classification of read, write and destructive fixture tools, and the connect form's API-key gating.
- Connect evidence, catalog evidence, allowed read, governed write, denied case, revoke, audit: not run. The API-key method still needs the full live lifecycle with a Superagent organization before this connection is considered qualified.