Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-09 16:35:27 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/plugin-task-execution
PaperClipAI/doc/connections/SUPERAGENT.md
T
Devin Foley 8cbd21b3e7 feat(apps): add Superagent connection (#15394) 
## 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
2026-10-06 15:57:16 -07:00

163 lines
7.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](./GENERIC-REMOTE-MCP.md).
## 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
1. 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.
2. In Paperclip, open **Apps → Browse → Superagent**, paste the key, and click
**Connect**.
3. 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`. The
`delete_agent_group` and `delete_agent_rule` tools 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 the `sk_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 names `https://superagent.sh` as its authorization
server, but neither `/.well-known/oauth-authorization-server` nor
`/.well-known/openid-configuration` exists 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 `classifyRisk` described 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 `initialize` on `/mcp` returned HTTP 401
with the `resource_metadata` header 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.
Reference in new issue View Git Blame Copy Permalink