request_connection with what it read in the vendor’s documentation and hands you a link. You can also start it yourself, under Connections → Add connection, and put the connection in an agent’s scope afterwards.
From the agent’s proposal
1
The agent proposes
The agent reads the vendor’s documentation and calls
request_connection with a vendor slug, the primary host, the auth scheme and its non-secret parameters, and the documentation URL it read. It never sends a secret, and the tool does not take one.The call waits a short while for you. If you have not finished, it answers awaiting_connection with a link, and the agent relays it with a sentence saying what it is for.2
Open the link
The link lands on a card under Pending actions that reads your agent asks to connect <name>, with the vendor and the hosts. It is marked proposed by the agent’s model, and the documentation page the agent read is linked so you can check the hosts against the vendor’s own. If the agent named no page, the card says so.
3
Check the form
The form is pre-filled with everything the agent proposed and nothing secret, and every field is editable:
- Vendor. A kebab-case slug,
github. Tools authored against this connection are bound to it. - Name. What you and your agents will see,
Acme GitHub (production). - Primary host. The https base URL vendor paths resolve against.
- Additional hosts (optional). One hostname per line, for a vendor whose API spans several.
- Auth scheme. How the proxy presents the credential to the vendor. The secret fields below follow it.
- The scheme’s parameters, when it has any: a header name and an optional prefix, a query parameter name, a token URL and scopes.
4
Enter the secret and connect
The secret fields are rendered from the scheme: an API key, a token, a username and password, a client id and secret, an API id and key, a private key. They are rendered as password inputs with autocomplete off. What you type goes to the server once, encrypted, and is never read back.Choose Connect. The connection is created with its credential, added to the requesting agent’s scope, and the agent’s waiting call answers
connected. Other agents get it when you add it to their scope on their pages.connection_declined; the skill tells it to ask you before proposing the same connection again.
What the form refuses
Every host must be a public https host. Private, loopback, link-local, cloud-metadata and internal addresses are refused under the input as you type, with the reason, and nothing is created. The same rule refused the agent’s proposal before the ask was ever made, and the proxy applies it a third time at call time on the address a name actually resolves to. A credential is only ever sent to a public host. The primary host must use https, must not carry credentials in the URL, and takes a path but no query string or fragment.Adding a connection yourself
Connections → Add connection opens the same form with no ask behind it. Fill it in, enter the secret, choose Connect. The connection belongs to you and reaches an agent when you tick it under Scope on that agent’s page.Already connected
If the agent proposes a vendor and host you already have connected and in its scope,request_connection answers connected at once and no ask is made. A second account at the same host is added in the console, not proposed.
If the vendor is one you already have connected without a credential and the agent proposes a host that connection does not reach, the ask is a widening of that connection rather than a second one: your agent asks to widen <name>, listing the hosts it adds and the set the connection will reach, with no form. This is the common case of a public API whose documented host redirects to a sibling, api.frankfurter.app to api.frankfurter.dev say: the tool’s first read fails on the host the connection did not list, the agent proposes the sibling, and you confirm once more. Connect adds the hosts to the connection you already have; nothing new is made, and the agent’s call answers connected. A connection with a credential is never widened this way, since its secret would go to a host you never approved; the agent’s proposal takes the form as a new connection.
One click on Graft Cloud
On Graft Cloud, a vendor that Pipedream Connect’s catalogue offers with its proxy turned on connects without a form: Gmail, Google Calendar and the rest of that catalogue, decided from the catalogue itself rather than a list Graft keeps. Two kinds of proposal never take this path: a vendor whose catalogue entry needs no account, and a proposal for a public API that takes no credential — Coinbase’s public prices, say, for which Pipedream has an OAuth app. Both are the one-click confirmation of the hosts, with no vendor sign-in. The agent proposes it as it proposes anything, and the card, in the chat on Claude and ChatGPT and under Pending actions in the console, reads your agent asks to connect Gmail, marked via pipedream with the Pipedream app it maps to, and has one button: Connect through pipedream. It opens Pipedream’s sign-in for the vendor in a popup, you sign in to your Google account there, and when Pipedream sends you back the card settles and the agent’s waiting call answersconnected.
Nothing is typed in the console and nothing secret is stored in Graft. The vendor’s token stays with Pipedream; what Graft keeps is the id of the account you connected, and every call an authored tool makes for that connection is relayed through Pipedream’s proxy, which adds the token on the way to the vendor. The tool’s code is the same ctx.fetch against the vendor’s own API, and Graft’s model reads the vendor’s own documentation to write it. There is no Google client to register and no seven-day Testing-mode expiry, because the client is Pipedream’s.
The permissions Google shows you on the way are the ones Pipedream’s Gmail app asks for, and they are wider than the read-only access your agent proposed: you are granting Pipedream’s app, not the proposal. What the proposal decides is which hosts the connection may reach, and every call still passes through Graft’s proxy, where a write stops at the dry run.
A sign-in you close or that the vendor refuses leaves the ask open, with the reason under the button, and Connect through pipedream tries again with a fresh link. The link is good for fifteen minutes.
The same path is open to a self-hosted Graft with its own Pipedream Connect project, under GRAFT_PIPEDREAM_PROJECT_ID, GRAFT_PIPEDREAM_ENVIRONMENT, GRAFT_PIPEDREAM_CLIENT_ID and GRAFT_PIPEDREAM_CLIENT_SECRET (see Configuration). Without them, every vendor takes the form below.
When the vendor is behind your API gateway
A self-hosted deployment can name the vendors its API gateway covers. For one of those,request_connection answers connected at once with provider: gateway: no link, no secret, and the card under Connections reads Through your API gateway. See Route vendors through your API gateway.