codespar_manage_connections

Pairs with codespar_discover: discover finds the right tool, this one tells you whether it is reachable for this user and unblocks it if not. Credentials never pass through here; they travel via the dashboard or the OAuth callback.

Actions

Example

action: "list": what this session has connected.

{
  "name": "codespar_manage_connections",
  "arguments": {
    "action": "list",
    "environment": "test"
  }
}

When to use

• API-key and OAuth providers (server_id like asaas, nfe-io): list, status, initiate. initiate returns a deep-link into the dashboard where the operator completes the connection; render it, and the connection is available to subsequent calls once they finish.
• Login-walled stores with no buyer API (meli, ifood): connect_start returns a live-view URL the user opens to log into their own account once (their 2FA); then connect_finish with the session_id and context_id from connect_start persists that login. For meli, that login is what codespar_shop buys with. iFood checkout is not supported yet: connecting an iFood login only stores the session for a future capability, so tell the user that before asking them to log in.
• Guest-checkout stores (VTEX: Cobasi, Animale, Lojas Pompeia): save_profile vaults the buyer's checkout identity once (name, email, CPF, full address; encrypted) so codespar_shop auto-fills it; get_profile returns it masked. Always ask the buyer which email to use at checkout, do not infer it: it is where the order confirmation goes, and an email already registered at the store forces a login wall the agent cannot pass, so use a dedicated checkout email not registered there. save_profile merges field by field: save the address first and add the email later; the response returns needs: "email" and profile_complete: false until an email is set.

Arguments

Errors and what to do

Money and mandate

Nothing moves. This tool reads and writes connections and the buyer's vaulted identity; the tools that then use those connections have their own gates. The identity vault is per consumer and encrypted, and get_profile returns it masked. What a saved profile changes is convenience: later purchases do not re-ask for CEP, email or CPF.

Related

• codespar_discover: the discover → connect → call loop
• codespar_shop: the buyer whose identity and logins this tool holds
• Shopper identity: what the vault stores and the email rule
• Authentication: how connections are scoped and persisted
• Connect links: the dashboard deep-links initiate returns

Notes

The discover → connect → call loop. Find the tool with codespar_discover; if the top match is not connected, initiate it (or connect_start for a store) and surface the URL to the user; otherwise call the tool. session.connectionWizard(serverId) is the typed wrapper for the most common case (SDK reference).

Operator setup. None for this tool itself: it queries the CodeSpar backend's connected accounts for the current session. The connect flows it returns point at provider-specific setup that does require the operator.

Result shapes (SDK), as previously documented. list: { connections: Array<{ server_id, connection_id, status: "connected" | "expired" | "error", connected_at }> }; status: { server_id, status: "connected" | "needs_setup" | "expired" | "error", connection_id?, expires_at? }; initiate: { server_id, status: "needs_setup" | "connected", wizard_url?, connection_id? }, where wizard_url deep-links into /dashboard/auth-configs with the server preselected. This revision did not re-verify those lists against the runtime.

From the SDK. session.execute("codespar_manage_connections", arguments) takes the same arguments as the MCP call; the selector is action (an earlier version of this page wrote operation, which the schema does not declare).