Devin Foley
53105d5830
## 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. > - Gauge (`withgauge.com`) measures how AI answer engines mention and cite a brand. Its hosted MCP server also gives SEO, analytics and ads reports, and runs a content pipeline that can publish to a connected CMS. > - Gauge is not in the catalog. Operators must use the generic "Connect your own MCP server" flow. That flow has no branding, no organization guidance, and no warning about live CMS publishing. > - The connector playbook supports this provider with existing definition fields. The server supports dynamic client registration with a reviewed `mcp` scope, and it accepts an organization API key as a bearer header. > - This pull request adds the Gauge definition, its artwork, the research and permission-review ledger rows, documentation, and deterministic tests. > - The benefit is a branded, governed Gauge connection with browser sign-in, an API-key option, and a clear publish warning. ## Linked Issues or Issue Description **Problem or motivation** Marketing and growth teams use Gauge to track their brand in AI answers and to run content workflows. They want their Paperclip agents to read visibility, keyword and traffic data, and to prepare content. Gauge is not in the Apps catalog. Operators must paste the MCP URL into the generic remote-MCP flow, which gives no branding, no method guidance, and no warning that content tools can publish live. **Proposed solution** Add a catalog-only Gauge connection built from the connector playbook. Browser sign-in uses Gauge's dynamic client registration and requests only the reviewed `mcp` scope. The user selects one Gauge organization on the consent screen. An optional method sends a customer-created organization API key as an `Authorization: Bearer` header. Both methods warn the operator to set publish actions to Ask first. Every discovered tool stays governed by the normal per-action policies. **Alternatives considered** A plugin was not needed because no custom UI, tables, workers, or webhooks are involved. The identity scopes that Gauge also advertises (`openid`, `profile`, `email`, `organizations`) are not requested, because Gauge selects the organization on its consent screen. A Gauge-specific `classifyRisk` rule was not added, because the tool names cannot be seen without an account. The generic rule already classifies `publish`, `create` and `update` tools as writes. **Roadmap alignment** This extends the existing self-serve remote-MCP connection catalog and does not overlap planned core work. ## What Changed - Added the `gauge` provider to `scripts/ingest-app-definitions.mjs` (category `analytics`, API-key placement, guidance, warnings, description) and regenerated `packages/shared/src/app-definitions/gauge.json` and the generated registry. - Added the Gauge row to the self-serve MCP research ledger with `dcr_or_api_key` auth and risk tier S3. - Added permission reviews for `gauge/mcp-oauth` (explicit scope `mcp`, from Gauge's live authorization-server metadata) and `gauge/mcp-api-key` (provider key), with evidence links. - Added Gauge's mark (`ui/public/brands/apps/gauge.png`, the avatar of Gauge's official GitHub organization) and the brand manifest entry. - Added gallery copy for the Gauge card. - Added `doc/connections/GAUGE.md` (endpoints, scopes, administrator setup, capabilities and policy, manifest, brand provenance, validation hook) and linked it from the connections README and the permission audit. - Tests: Gauge definition shape, store visibility and artwork, URL recognition, reviewed scope, bearer-header placement, the connect form's sign-in default and API-key gating, 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 server/src/__tests__/tool-access-service.test.ts` — 738 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`, `pnpm --filter @paperclipai/ui typecheck` — clean. - `node scripts/ingest-app-definitions.mjs --definitions-only` produces no Gauge drift. - Manual: on a local instance, open Apps → Browse and confirm the Gauge card and icon. Open `/apps/connect?source=gauge` and confirm that sign-in is the default and that the API-key method is under Advanced. - Live metadata probe on 2026-10-08: an unauthenticated `initialize` on `https://app.withgauge.com/mcp` returns 401 with `resource_metadata`. Both `.well-known` documents return the recorded endpoints and scopes. Dynamic client registration succeeds. The authorize endpoint accepts `scope=mcp` and rejects an unknown scope with HTTP 400. ## Risks - Low risk to existing providers: the change is additive catalog data plus tests. The generated registry only gains one import. - Gauge content tools can publish to a connected CMS, including live, and a bulk keyword update replaces each prompt's keyword list. Both methods warn the operator, and the API-key helper text tells operators to set publish actions to Ask first. - Gauge API keys are not scoped and reach the whole organization. Paperclip cannot narrow an issued key. - The permission-review ledger records live proof for both methods as not run. The lifecycle checklist in `doc/connections/GAUGE.md` still needs a documented pass with a Gauge organization. > 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 tool use (shell, file editing, web research). ## 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
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), Gauge
(mcp-oauth, mcp-api-key; 2026-10-08).
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.