diff --git a/docs/connectors.md b/docs/connectors.md index 580c7ff..b386d1b 100644 --- a/docs/connectors.md +++ b/docs/connectors.md @@ -70,6 +70,7 @@ Find an app and open its setup guide. | --- | --- | --- | | [Arcade](connectors/arcade.md) | Tool gateway combining the tools you select from several servers behind one URL. Agents use the exposed tools; authentication follows your gateway settings. Setup is unverified. Needs the experimental **MCP aggregators** setting. | Gateway URL · Browser sign-in or token/headers | | [Asana](connectors/asana.md) | Work management for team projects, tasks, and goals. Agents work with the projects and tasks your Asana app can reach. | Your own OAuth app | +| [Browser Use Cloud](connectors/browser-use-cloud.md) — **Upcoming; not yet stable** | Hosted browser tasks with saved-profile access and per-run cost controls. Setup is unverified. | Browser Use API key | | [Composio](connectors/composio.md) | App discovery and execution through Composio Connect or a configured session. Upstream app authorization happens in Composio; broad execution actions need separate review. Setup is unverified. Needs the experimental **MCP aggregators** setting. | Composio Connect sign-in · Configured session URL and headers | | [Executor](connectors/executor.md) | One remote endpoint for configured integrations. Agents use its exposed actions within Executor's upstream policies. Setup is unverified. Needs the experimental **MCP aggregators** setting. | Deployment URL · Browser sign-in or token/headers | | [Fireflies](connectors/fireflies.md) — **Live exception; not yet stable** | Meeting transcripts, summaries, and action items the connected account can access. Setup is unverified. | Sign in with Fireflies · API key | @@ -118,6 +119,7 @@ Services that connect to many apps for you and hand them to Paperclip through on | [Airtable](connectors/airtable.md) | Spreadsheet-database hybrid for structured team data. Agents work with the bases your Airtable sign-in can reach. | Sign in with Airtable | | [ClickHouse](connectors/clickhouse.md) | Columnar database built for analytical queries over very large datasets. Agents query the ClickHouse Cloud service you name. | Sign in with ClickHouse | | [Mixpanel](connectors/mixpanel.md) | Product analytics for user and event behaviour. Agents work with the events and reports your Mixpanel account can reach. | Sign in with Mixpanel | +| [Neon](connectors/neon.md) — **Upcoming; not yet stable** | Development and testing databases only. Pin a project, enable read-only mode, and review credentials and writes. Setup is unverified. | Sign in with Neon · API key | | [PostHog](connectors/posthog.md) | Product analytics with session replay, feature flags, and experiments. Agents analyse product usage, errors, flags, and experiments. | Sign in with PostHog · API key | | [Supabase](connectors/supabase.md) | Hosted Postgres with authentication, storage, and edge functions. Agents work with the Supabase project you scope the connection to. Use a development project. | Sign in with Supabase · API key | diff --git a/docs/connectors/browser-use-cloud.md b/docs/connectors/browser-use-cloud.md new file mode 100644 index 0000000..f85170e --- /dev/null +++ b/docs/connectors/browser-use-cloud.md @@ -0,0 +1,97 @@ +--- +seo_title: Browser Use Cloud Connector +seo_description: Connect Browser Use Cloud with an API key for hosted browser tasks. Review saved login access, action permissions, cost limits, and cleanup. +--- + +# Browser Use Cloud + +> **Not in a stable release yet:** This guide describes the next-release connector. It is absent from the pinned stable release, `v2026.1001.0`. + +Browser Use Cloud delegates website tasks to Browser Use's hosted agent through its v4 REST API. You can watch and interact with the browser from the task's **Browser** tab. Paperclip uses a customer API key; this is not an MCP connection or an agent adapter. + +## Before you connect + +- A Browser Use account and an API key from [Browser Use settings](https://cloud.browser-use.com/settings). +- Provider credits and capacity for the tasks you intend to run. Browser Use's billing, rate, and concurrency limits apply. +- Outbound HTTPS from Paperclip to `api.browser-use.com`, and browser access to `live.browser-use.com`. If you set your own Content Security Policy, permit the viewer origin in `frame-src`. + +Cloud and self-hosted instances use the same server-side path. No OAuth app, callback registration, or Paperclip Cloud enrollment is required. + +## Connect Browser Use Cloud + +> **Unverified setup:** These steps follow pinned product source and provider documentation. This guide has not been tested with a live connection. Each step below is unverified. + +1. **Unverified:** Open **Connectors**, browse the catalog, and select **Browser Use Cloud**. +2. **Unverified:** Choose the **Browser Use Cloud** method. On **Access**, choose the identity and the agents that may use it. +3. **Unverified:** Create an API key in Browser Use settings and enter it in **API key**. Paperclip calls `https://api.browser-use.com/api/v4` using the `X-Browser-Use-API-Key` header. +4. **Unverified:** Finish the connection check. The setup probe reads profiles without starting paid work. +5. **Unverified:** Review **Permissions**, set a maximum cost per run, and choose saved profiles the credential may use. Leave profiles unselected for fresh browsers. +6. **Unverified:** Review the seven actions below and set **Ask first** or **Off** where you want approval or denial before use. + +The pinned definition mentions keys with read and write permissions, but the provider documentation does not verify such a key setting. This guide does not require that unverified option. + +## Choose access and action permissions + +Paperclip's identity, selected agents, credential grants, and action permissions govern connector calls. A saved profile can contain authenticated website sessions. Allowing one gives agents access through those saved logins; select only profiles suitable for their assigned work. Paperclip does not create or import profiles. + +The API key stays in Paperclip's vault and is not exported to the agent or the board UI. Hosted work requires a real Paperclip task and agent run. The connector test surface can list allowed profiles, but it cannot start paid browser work. + +| Action | Review and behavior | +| --- | --- | +| `browser_start` | Write; delegates a task that can change websites. Supports an allowed profile and a lower requested cost cap. | +| `browser_continue` | Write; starts another turn in an idle, owned conversation. Busy sessions reject it. | +| `browser_cancel` | Write; cancels hosted work and retains the browser for the idle window. | +| `browser_end` | Write; cancels work and stops every browser registered to the conversation. | +| `browser_status` | Read; reports run status, sanitized results, progress, and recorded run cost. | +| `browser_sessions` | Read; lists conversations for the current task, agent, and selected grant. | +| `browser_profiles` | Read; lists existing profiles explicitly allowed for the selected grant. | + +The product classifies start, continue, cancel, and end as destructive-capable. Natural-language website tasks can submit forms, purchase items, or change external systems. Check the effective **Allowed / Ask first / Off** setting; a Write label does not mean approval is enabled. Inspect the action list after a refresh. New or changed actions follow the connection's catalog review and quarantine settings. + +Each dispatch uses the lowest of the requested cap, the credential's configured cap, and applicable remaining hard company, agent, and project budgets. Unconfigured limits do not create a cap. Concurrent work is not a shared provider-side reservation. Browser Use's API-key monthly spending caps are soft limits that running or simultaneous work can exceed. + +## Try it + +After setting a small per-run cap and leaving saved profiles unselected, create a real task: + +```txt +Open https://example.com and report the page title. Do not sign in, submit forms, buy anything, or change website data. End the browser when finished. +``` + +Inspect the task's Browser tab, the result, and the recorded cost. Do not post viewer URLs in comments, logs, or artifacts: they are sensitive access links. + +> **Unverified check:** Illustrative task, not a recorded live test. Hosted execution can incur provider charges. + +## Stop work and revoke access + +**Stop browsing** requests cancellation of hosted work. Closing the Browser tab only hides the viewer. **Close browser** stops the provider browser. A completed browser can remain open during a ten-minute idle window, bounded by provider expiry; **Keep browser open** renews that window. An agent can use `browser_end` to stop the conversation's browsers. + +Removing the connection disables its access first and waits for confirmed provider shutdown before deleting stored secrets. Pending shutdown can return a retryable conflict; retry removal after cleanup completes. Revoke the API key separately in Browser Use if it should no longer work outside Paperclip. + +> **Unverified revocation:** Shutdown, secret deletion, and provider-key revocation were not exercised for this guide. Check provider state and test denied access in your own instance. + +## Troubleshooting and limitations + +| Problem | Check | +| --- | --- | +| Paid start is rejected in the connector test screen | Use a real task and agent run; setup testing does not create paid work. | +| A saved login is missing | Confirm that the selected credential explicitly allows that existing profile. | +| The viewer is blank or blocked | Check viewer network access and CSP; **Reconnect view** reloads the display without restarting work. | +| Provider limits reject a run | Check the project's credits, API-key spending cap, and provider rate/concurrency limits. | +| A paid-create outcome is unknown | Inspect Browser Use before starting replacement work. Paperclip does not automatically repeat an uncertain paid request. | +| Connection removal is pending | Wait for provider shutdown, inspect active work, and retry removal. | + +Passkey-dependent sign-in can require human interaction. Recording, artifact/file import, profile creation, arbitrary HTTP endpoints, and arbitrary CDP commands are outside this connector. A stopped hosted agent can leave an idle browser open; end it when finished. + +## Related guides + +- [Connector overview](https://paperclip.ing/product/connectors/browser-use-cloud/) (upcoming website route; preview-only until publication). +- [How connector access works](access-model.md) +- [Set action permissions](action-permissions.md) +- [Reauthorize or disconnect](reauthorize-and-disconnect.md) +- [Verify and troubleshoot](verify-and-troubleshoot.md) + +## Sources + +- [Pinned Paperclip definition](https://github.com/paperclipai/paperclip/blob/22cea6b2e6aeb54b484ef095eab1378ecd0b4d79/packages/shared/src/app-definitions/browser-use-cloud.json) and [connection behavior](https://github.com/paperclipai/paperclip/blob/22cea6b2e6aeb54b484ef095eab1378ecd0b4d79/doc/connections/BROWSER-USE.md): methods, access, reviewed actions, budgets, and lifecycle. Historical tests in the source are not tests of this guide. +- [Browser Use v4 API](https://docs.browser-use.com/cloud/api-v4-overview), [billing and caps](https://docs.browser-use.com/cloud/guides/billing), and [concurrency limits](https://docs.browser-use.com/cloud/guides/concurrency): provider behavior and limits. diff --git a/docs/connectors/neon.md b/docs/connectors/neon.md new file mode 100644 index 0000000..f0e8280 --- /dev/null +++ b/docs/connectors/neon.md @@ -0,0 +1,108 @@ +--- +seo_title: Neon Connector +seo_description: Connect Neon by browser sign-in or API key for development databases. Set project scope, read-only mode, and permissions; protect returned credentials. +--- + +# Neon + +> **Not in a stable release yet:** This guide describes the next-release connector. It is absent from the pinned stable release, `v2026.1001.0`. + +Neon connects agents to its hosted MCP server for Postgres project and branch management, SQL, schema inspection, and related development tools. Paperclip offers **Sign in with Neon** and **Use an API key**. + +> **Development and testing only:** Neon advises never connecting MCP agents to production databases. Use anonymized development or test data, and avoid production or personally identifiable information. **Ask first** does not make production database access appropriate. + +## Before you connect + +- A Neon account with access to a development or testing project. +- For the key method, a customer-created Neon API key. Prefer a project-scoped key for one development project; creating it requires an organization Admin. +- A public HTTPS Paperclip origin or a loopback HTTP origin. A plain HTTP tailnet hostname is not loopback. + +Both methods use `https://mcp.neon.tech/mcp` with Streamable HTTP. Browser sign-in uses dynamic client registration and PKCE, so you do not register your own OAuth app. The API-key method sends the key in an `Authorization: Bearer` header. The deprecated SSE endpoint is not offered. + +## Connect Neon + +> **Unverified setup:** These steps follow pinned product source and Neon's documentation. No Neon account connection, authenticated tool discovery, or live lifecycle test was performed for this guide. Each step below is unverified. + +1. **Unverified:** Open **Connectors**, browse the catalog, and select **Neon**. +2. **Unverified:** Choose **Sign in with Neon** or **Use an API key**. On **Access**, choose the identity and the agents that may use it. +3. **Unverified:** Open **Advanced** to set **Pin to project ID** and enable **Read-only mode**. Neither is required by the default path; read-only mode is off by default. Copy a development project's ID from Neon Console → **Project settings → General**. +4. **Unverified:** For browser sign-in, complete Neon's consent flow. Paperclip requests `read` and `write` scopes; the read-only switch restricts the server rather than narrowing that token. +5. **Unverified:** For the key method, create a key in Neon Console and enter it in **Neon API key**. To create a project-scoped key, switch to your organization, open **Settings → API keys**, and select **Project-scoped** (organization Admins only). Personal keys are under the profile menu → **Settings → API keys**. +6. **Unverified:** Finish discovery, inspect **Permissions**, and set writes, destructive actions, and credential-returning tools to **Ask first** or **Off** before agents run work. Discovered actions start **Allowed**, including writes and destructive actions. + +Do not put keys or returned database credentials in a URL, comment, log, or connection configuration field intended for non-secret values. + +## Choose access and project scope + +The credential's Neon permissions determine provider reach. A project-scoped key has Editor rights on one project. Personal keys follow the user's access; organization keys have admin-level access to organization resources. Paperclip cannot widen an existing key's permissions. + +**Pin to project ID** optionally narrows the server to one project. Paperclip sends `projectId=` on the same server URL for discovery and execution; callers cannot override it. Neon enforces this restriction. A pinned connection hides project-management tools such as `list_projects` and `create_project`. An OAuth project scope may require logout and reauthorization to change or remove. + +The product definition's `requiredResourceFilters: ["project"]` is policy metadata, not a required local allowlist. A default connection has no required project filter. Set the pin deliberately instead of assuming it is already bounded. + +**Read-only mode** sends `readonly=true` and restricts the server to read operations such as SELECT queries and schema inspection. It disables writes including branch creation, migrations, and auth changes. It does not merely limit SQL. It also does not relabel Paperclip's SQL tools as Read or guarantee that returned data is non-sensitive. + +## Review action permissions + +Paperclip discovers the tool catalog from Neon. Review your connected account's action list; a public preview does not prove its effective access. Both methods use the same endpoint, but tool availability follows the credential and server filters. + +| Tool group | What to review | +| --- | --- | +| Documentation, schema, and observability | Reads can expose application data, query text, or logs. Use suitable test data. | +| Projects, branches, computes, snapshots, roles, and databases | Creation, reset, deletion, and restoration can change or remove data. | +| SQL and transactions | `run_sql`, `run_sql_transaction`, and `explain_sql_statement` retain conservative Write/destructive classification, even when available with server-enforced read-only restrictions. | +| Neon Auth, Data API, functions, and storage | Configuration, deployment, and object changes need explicit review. | +| `get_connection_string` | Returns a connection string containing a privileged role password; treat it as sensitive even if the UI labels it Read. | + +`get_connection_string` returns a password for a role with `neon_superuser` membership and `CREATEROLE`. Anyone holding it can change data directly, outside Paperclip's action permissions and gateway audit. Neon excludes it from read-only mode. Set it to **Ask first** or **Off** unless agents need direct database credentials, and avoid retaining the result in shared artifacts. Its presentation class remains under review; a Read label is not evidence that credential disclosure is safe. + +**Allowed** runs without approval, **Ask first** requires approval per call, and **Off** denies calls. These settings govern Paperclip connector calls. They cannot contain a credential already disclosed to an agent. New or changed tools follow the connection's catalog review settings; do not assume a refresh places every new action in quarantine. Inspect the effective list and permissions after a refresh. + +## Try it + +With a development project pinned and read-only mode enabled, ask an authorized agent: + +```txt +Describe the tables in the connected development database. Do not return row data, connection strings, passwords, or other credentials. Do not run migrations or change anything. +``` + +Compare the schema with Neon Console and inspect the connector call. Confirm the project pin, read-only flag, and effective action permissions before broader work. + +> **Unverified check:** Illustrative task, not a recorded live test. A successful schema read does not prove that other actions are denied. + +## Revoke or disconnect + +Remove the identity or connection in Paperclip to revoke its grant and delete stored secrets. Also revoke the provider authorization or delete the API key in Neon if it should no longer work outside Paperclip. Neon publishes an OAuth revocation endpoint; this guide does not claim that Paperclip removal successfully exercised it. + +If `get_connection_string` disclosed a database role password, removing the MCP connection does not prove that password is invalid. Rotate or revoke the exposed database credential in Neon and check denied access separately. + +> **Unverified revocation:** OAuth revocation, API-key deletion, database-credential rotation, and denied access were not live-tested for this guide. Follow Neon's current console controls and verify the result. + +## Troubleshooting and limitations + +| Problem | Check | +| --- | --- | +| Project-scoped key creation is unavailable | Switch to the organization and confirm organization Admin rights. | +| Project ID is rejected | Copy the project ID, not its display name; the field accepts lowercase letters, digits, and hyphens, up to 64 characters. | +| Authorization fails on a plain HTTP hostname | Use HTTPS or a loopback HTTP canonical origin. | +| Write actions disappear | Check **Read-only mode** and the credential's provider permissions. | +| Project-management tools disappear | Check the project pin; Neon restricts the tool catalog for pinned connections. | +| A project scope cannot be changed | Check the OAuth authorization's project scope; logout and reauthorization may be required. | +| An action appears after refresh | Review its effective permission before agent work; newly discovered actions can become active. | + +Paperclip does not offer Neon's repeatable category filter through this connector. Use project pinning, read-only mode, and per-action permissions. Provider rate limits apply. Live authorization, governed writes, denial, revocation, and audit behavior still need qualification with a development project. + +## Related guides + +- [Connector overview](https://paperclip.ing/product/connectors/neon/) (upcoming website route; preview-only until publication). +- [How connector access works](access-model.md) +- [Set action permissions](action-permissions.md) +- [Reauthorize or disconnect](reauthorize-and-disconnect.md) +- [Verify and troubleshoot](verify-and-troubleshoot.md) +- [Supabase](supabase.md), [ClickHouse](clickhouse.md), and [Airtable](airtable.md) + +## Sources + +- [Pinned Paperclip definition](https://github.com/paperclipai/paperclip/blob/22cea6b2e6aeb54b484ef095eab1378ecd0b4d79/packages/shared/src/app-definitions/neon.json) and [connection notes](https://github.com/paperclipai/paperclip/blob/22cea6b2e6aeb54b484ef095eab1378ecd0b4d79/doc/connections/NEON.md): method labels, optional filters, scopes, and defaults. The provider guidance below takes precedence over weaker production-safety wording in those sources. +- [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) and [API keys](https://neon.com/docs/manage/api-keys): development-only security guidance, server filters, key scope, and setup. +- [Pinned Neon tool definitions](https://github.com/neondatabase/mcp-server-neon/blob/00d82d4e5c925380fc077fe1932780035f564d8b/mcp/tools/definitions.ts): privileged connection-string credentials and their exclusion from read-only mode. This provider source pin is not proof of a particular hosted deployment. diff --git a/site/content.json b/site/content.json index 6986344..081e603 100644 --- a/site/content.json +++ b/site/content.json @@ -226,6 +226,10 @@ "title": "Box", "file": "../docs/connectors/box.md" }, + { + "title": "Browser Use Cloud", + "file": "../docs/connectors/browser-use-cloud.md" + }, { "title": "ClickHouse", "file": "../docs/connectors/clickhouse.md" @@ -351,6 +355,10 @@ "title": "Mixpanel", "file": "../docs/connectors/mixpanel.md" }, + { + "title": "Neon", + "file": "../docs/connectors/neon.md" + }, { "title": "Netlify", "file": "../docs/connectors/netlify.md"