Managing connections
Connection lifecycle — states, reconnect, incremental scopes, standing approvals, and disconnect.
Connections have a lifecycle. This guide covers the states you will see and the actions you can take: inspect, update, reconnect, extend scopes, pre-authorize repeats, and disconnect.
States
| State | Meaning | Your action |
|---|---|---|
| Active | Working; scopes granted | None |
| Needs reauth | Provider grant expired or revoked upstream | Reconnect |
| Missing scope | An action needs a scope you have not granted | Grant the scope or decline the action |
| Disabled | Connector or Flow unavailable | Wait; check status |
| Revoked | You disconnected it | Reconnect to use again |
The connections list shows your active connections plus the ones needing attention — never a faked empty list, never a successful silence on failure.
Reconnect
When a connection needs reauth, start a reconnect from settings. The server injects the connection and grant identities from the path — your client never supplies them. Reconnect re-authorizes the same binding; it does not duplicate it.
Incremental scopes
New tasks may need new scopes. Grant them incrementally on the existing connection instead of reconnecting from scratch. Requests for scopes you already granted return immediately with nothing new to authorize.
Standing approvals
Repeatable, narrow actions can carry a standing approval: pre-authorization for one action shape on one connection, created by you, listed per connection, revocable at any time. Standing approvals never cover changed actions — a changed tool version or new scope needs a fresh decision.
Disconnect
Disconnecting revokes the binding immediately. Sibling impact (other bindings sharing the provider grant) is computed server-side and shown before you confirm; the provider grant itself releases when its last live binding goes away. After disconnect, pending actions on that connection fail closed with CONNECTION_NOT_FOUND — they never run.
If something goes wrong
NEEDS_REAUTH— reconnect the connection.MISSING_SCOPE/SCOPE_NOT_GRANTED— grant the named scope or decline the action.APPROVAL_REQUIRED— approve the exact action, or deny it.ADMIN_POLICY_BLOCKED— your workspace admin blocked the action; ask them for access.UNKNOWN_OUTCOME— check activity before retrying; the action may have completed.