How connector access works

Connecting a service and letting an agent use it are not the same act. Paperclip separates them — but how it separates them depends on what kind of connector you are looking at. Start here.

First: which kind of connector is this?

Four shapes, with genuinely different controls. Reading the wrong section is the most common way to end up with a wrong expectation.

Warning: Do not carry an assumption across rows. "Set the writes to Ask first" is meaningless on a channel or a model connection, and a channel's reach cannot be narrowed from the Permissions tab.

The control channels do have

Channels have no action switches, but they are not ungoverned. Each one has an Access tab with External identity access, and one toggle on it decides what happens when someone Paperclip does not recognize sends a message:

Linked identities act as their current Paperclip user, with that person's permissions.

iMessage Photon is the exception: it does not permit unlinked senders at all, so linking there is a required setup step rather than a policy choice.

The four gates on a tool connection

The rest of this page describes app tool connections. They separate access into four decisions, made at different moments by different people, and every tool call is checked against all four.

      credential                   who it belongs to              which agents           which actions
  ┌──────────────────┐         ┌──────────────────────┐      ┌──────────────────┐   ┌──────────────────┐
  │ the connection   │────────▶│ the grant            │─────▶│ agent access     │──▶│ action           │
  │ token or key,    │         │ personal, org, or    │      │ any agent, or    │   │ Allowed /        │
  │ server URL,      │         │ dedicated to one     │      │ just the ones    │   │ Ask first /      │
  │ transport        │         │ agent                │      │ you pick         │   │ Off              │
  └──────────────────┘         └──────────────────────┘      └──────────────────┘   └──────────────────┘

A call has to clear all four gates. Holding the credential is not enough; being an allowed agent is not enough.

The connection

The connection is the stored credential plus everything needed to reach the service: the transport, the server URL, and how it authenticates (oauth, api_key, or none). Tool connections use mcp_remote, rest_api, or local_stdio; the chat_sdk and runtime_auth transports belong to the channel and model shapes above, which is why the action gate does not apply to them.

Each connection carries a company-scoped identity — a uid like google-sheets/finance-sheet-1a2b3c4d — that survives renaming. That identity is what the rest of Paperclip references, which is why renaming a connection in the UI never breaks a policy pointed at it.

Secrets are never part of the connection record you can read back. Credential values are stored as secrets and referenced; the API returns metadata.

The grant: who the credential belongs to

A grant answers "whose account is this?". Paperclip supports three kinds. Available choices and UI labels depend on the connector and method; this table describes the data model, not three options offered by every setup screen:

You do not have to answer this before you connect. Setup states the identity it will use in one line above the main button, and Change opens these choices. A new connection starts on the organization identity when the method allows it; a method that only supports personal or dedicated-agent access starts on one of those. When an agent asked for the connection from a task, setup starts on Just me and on that agent alone.

Creating a personal connection is available to any active member. Creating an organization or dedicated-agent grant is a manager operation — Paperclip rejects the request with "Only a connection manager can share this credential with the organization" if you lack the permission, and it enforces that on the server rather than trusting the browser.

AgentMail is a setup exception: its new key defaults to everyone in the company and only the selected inbox owner. Reusing a key retains its existing grants.

An organization grant has its own human audience, set on the connector's identity card: Any human in the company, or Humans I pick with a named member list. That audience governs which people's runs the shared credential will back.

Use separate accounts for people and agents walks through choosing between them.

Agent access: which agents may use it

Independently of the grant, each connection says which agents may use it at all. Two options, under Which agents can use this connection? — behind Change while you connect, and on the Permissions tab afterwards:

• Any agent — "Available across your company."
• Just agents I pick — "Available only to selected agents." You then choose the agents.

New tool connections normally default to all_agents; setup for a requesting agent narrows access to that agent. Methods and saved connections can carry more specific access. This does not bypass approval: creating the connection is itself an authorized, audited operation, and every individual action still has its own permission.

For a dedicated agent identity the question narrows to "Which agent owns this GitHub account?" — the identity and the agent are the same decision.

Saved connection guidance

Some connections also contribute editable instructions to an eligible agent's task context. The five experimental memory providers include defaults; saved instructions can be used with other connections too.

Guidance never grants access or removes an approval requirement. Turning it off retains tool access, and a connection must still have an accessible tool and current grant before its enabled guidance is delivered. See Saved connection instructions.

Action permission: which calls are allowed

Once connected, Paperclip reads the service's action list and gives each entry one of three states:

Every discovered action is also classified by risk, which is what "set all writes to Ask first" operates on:

• read — no known mutation.
• write — creates or changes something.
• destructive — deletes, removes, or is otherwise not reversible. An explicit destructiveHint annotation from the provider forces this classification.

Classification is deliberately conservative for providers with broad, fast-moving catalogs. PostHog is the clearest example: an unannotated PostHog tool is treated as a write, not a read, because silently assuming "read" for an unknown tool is the failure mode worth avoiding. Its exec tool is hard-classified destructive.

One family of connectors has a limit that no permission setting can widen:

Google Workspace connectors — Gmail, Drive, Docs, Sheets, Slides, Calendar, Chat, People, and Workspace Search — are limited to the reviewed read and write operations of the capability group you connected. A tool Google adds that is not on the reviewed list is switched off rather than allowed by default.

This is why Gmail cannot send. Its draft group requests Google's gmail.compose scope, which does permit sending at Google's end, but the reviewed write list for that group contains exactly one operation, create-draft. The credential could send; the connector will not offer it. The same mechanism is why Google Drive can copy and create files but has no delete or share operation.

Set action permissions is the how-to.

When an Ask-first call happens

An agent calling an Ask first action does not get an error and does not get the result. The call becomes an action request, and the agent waits.

You answer it from the Review tab on the connector, or the company-wide review queue, where it shows as Waiting for your OK. Three answers:

• Allowed once — the call runs this time, and nothing else changes.
• Always allowed — the call runs, and Paperclip creates a trust rule so matching calls stop asking.
• Declined — the call does not run.

Trust rules are visible and revocable afterwards. Answer a connector review request covers the flow from both sides.

The one exception worth knowing

Per-tool Ask first governs tool calls that go through Paperclip's tool gateway. It does not govern a shell.

When a GitHub connection is bound to an agent as a dedicated identity, that identity is also handed to the run's shell. Paperclip states this plainly at the moment you change a GitHub permission: "Shell Git and gh use this account for the run and are not constrained by per-tool Ask-first controls." An agent that can run git push or gh pr merge in its workspace is limited by what the GitHub account can do, not by the connector's action switches.

This is not a general sandbox claim, and it is not a claim in the other direction either. Nothing about it says other connectors are sandboxed, and human approval of a tool call is a different thing from a code review on a pull request. GitHub has the detail.

Where this is enforced

Access decisions resolve at call time, not at setup time. The tool gateway holds the effective policy for an agent — the connection's own settings, plus any tool profiles and company tool policies that apply — and decides allow, ask, or deny before the request reaches the provider. Changing a permission takes effect on the next call; it does not require reconnecting.

Note: Custom tools:use permission grants — the stored per-agent or per-person kind, not the connection identities described above — are enforced exactly as written. A grant whose scope.allow list names a different tool, connection, or application doesn't cover the call, and a grant with an unrecognised selector or a malformed restriction covers nothing. Review custom grants after upgrading: if an agent loses a tool it used before, check its grant first. The Tool Gateway reference lists the matching rules.

Related

• Connectors
• Share a connector with people and agents
• Set action permissions
• Tool Gateway
• Trust and low-trust review

Sources

• Connection setup — one-screen access choices and setup behavior.
• Remote MCP setup — provider-specific connection controls.