Documentation

Everything you need to run Paperclip.

Guides, references, and walkthroughs for the people running AI agents at work. Start at the quickstart, or jump anywhere below.

Connections v3 (Apps)

Apps is the experimental home for connecting Paperclip to the outside services your agents use — think Google Sheets, remote MCP servers, and REST APIs. Behind it sits Connections v3, a rebuilt foundation for how Paperclip stores, authorizes, and hands out those connections. This release lands the groundwork for one-click Connected Apps: a typed app catalog, a stable connection identity, and subject-aware authorization.

It's early. What ships in this release is the plumbing, not a finished app store. You can turn it on and explore, but treat it as a preview.

Why it exists

Connecting an external service used to mean a loose bundle of config and secrets with no clear owner and no stable name. Connections v3 replaces that with an explicit model:

  • A stable connection identity. Every connection gets a company-scoped uid (like google-sheets/finance-sheet-1a2b3c4d) that stays put even as names change, so other parts of Paperclip can reference it reliably.
  • Explicit ownership, auth, and transport. Each connection now records who owns it, how it authenticates (oauth, api_key, or none), and how it talks to the service.
  • Subject-aware grants. A new connection_grants table separates the connection from who is allowed to use it. A grant is either a workspace grant (shared by the whole company) or a user grant (scoped to one person), so a single connection can serve a shared default and per-user authorizations at the same time.
  • Multi-key credentials. Connections can hold more than one credential reference, which is what real-world apps with several keys or scopes need.

On top of that, a generated AppDefinition catalog gives the browse-and-connect experience a single typed contract, and a runtime layer adds subject-aware authorization state and scoped key handling. Grant management routes are registered in the OpenAPI surface and fail closed for scopes they don't recognize — an unknown scope is refused rather than quietly allowed.

Turn it on

  1. Go to Settings → Instance settings → Experimental.
  2. Turn on Apps — "Show the Apps navigation and allow access to app connections, gateways, and advanced app tooling."

The change takes effect immediately. An Apps section appears in the navigation, where you can browse the app gallery and set up connections. Flip the toggle back off and the surface hides again — your connections and grants aren't deleted.

What you get today

With Apps on, you can:

  • Browse the app gallery — the Wave 1 catalog of connectable apps, served from a single typed AppDefinition contract.
  • Connect an app — set up a connection, including the OAuth handshake for apps that need it.
  • Manage grants — see which workspace and user grants exist on a connection, add an installation, and revoke a grant.

Because this is a foundation, the depth varies by app and some flows are still bare. Expect the browse-and-setup experience to fill in over coming releases.

Note for operators: the remote_http rename

Connections v3 renames the legacy remote_http transport to mcp_remote. This is what remote MCP server connections use.

You don't need to do anything. The change ships as two additive database migrations that run automatically on startup:

  • 0182_connections_v3_schema_core — backfills connection uids, adds the ownership/auth fields, creates the connection_grants table, seeds a default workspace grant for every existing connection, and rewrites any transport of remote_http to mcp_remote.
  • 0183_connection_user_authorization_state — adds subject-aware authorization state used by per-user grants.

The only thing to know: if you have tooling, scripts, or notes that refer to the remote_http transport by name, update them to mcp_remote. The valid transports are now mcp_remote, rest_api, and local_stdio.

Still evolving

This is a foundation shipped behind an experimental flag, and it's still moving:

  • No compatibility guarantees. Schema, routes, catalog entries, and the UI can change, break, or be removed between releases. Don't build critical workflows on top of it yet, and re-read the release notes after upgrading.
  • The catalog is Wave 1. The set of connectable apps is an early cut and will grow.
  • Setup flows are partial. The one-click Connected Apps experience is the destination, not what ships today.

Where to go next