---
title: codespar_manage_connections
description: List, inspect or connect the accounts and identity the agent needs. Dashboard connect deep-links for API-key and OAuth providers, a one-time login for login-walled stores, and the buyer's vaulted checkout identity for guest-checkout stores.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

<MetaToolHeader tool="codespar_manage_connections" />

Pairs with [`codespar_discover`](/docs/concepts/meta-tools/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

<MetaToolActions tool="codespar_manage_connections" />

## Example

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

<Split min={380}>
<SplitPane label="Call · tools/call">

```json title="arguments"
{
  "name": "codespar_manage_connections",
  "arguments": {
    "action": "list",
    "environment": "test"
  }
}
```

</SplitPane>
<SplitPane label="Result">

Result shape: see runtime. The tool document names result fields only for `save_profile` (`needs: "email"` and `profile_complete: false` until an email is set) and says `initiate` surfaces a dashboard connect deep-link and `connect_start` a live-view URL. The published document is [`/v1/meta-tools.json`](https://api.codespar.dev/v1/meta-tools.json).

</SplitPane>
</Split>

## 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`](/docs/concepts/meta-tools/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

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | No | `list` \| `status` \| `initiate` (dashboard providers) · `connect_start` \| `connect_finish` (login-walled stores) · `save_profile` \| `get_profile` (vaulted shopper identity) |
| `server_id` | `string` | For `status`, `initiate`, `connect_start`, `connect_finish` | Provider or store id (`asaas`, `nfe-io`, `meli`, `ifood`) |
| `country` | `string` | No | ISO 3166-1 alpha-2 filter (`list` only) |
| `environment` | `string` | No | `live` \| `test`. Defaults to `live` |
| `return_to` | `string` | No | Path inside the dashboard to redirect to after the user finishes connecting (`initiate` only) |
| `session_id` | `string` | For `connect_finish` | From `connect_start` |
| `context_id` | `string` | For `connect_finish` | From `connect_start`; persists the buyer's login |
| `consumer_id` | `string` | No | Which buyer is connecting, or whose profile to save. Defaults to the session's user id |
| `profile` | `object` | For `save_profile` | `{ buyer: { firstName, lastName, email, document (CPF), phone }, address: { postalCode, street, number, neighborhood, city, state, complement } }`. Stored encrypted |

## Errors and what to do

| Error | Cause | What to do |
|---|---|---|
| `invalid_args` | An unknown `action` (the message lists the accepted values), or a `status` / `initiate` / `connect_*` without `server_id`. Nothing is connected or saved. | Fix the call against the Arguments table. |
| `needs: "email"`, `profile_complete: false` on `save_profile` | Not an error: the profile has no email yet. | Ask the buyer for a dedicated checkout email and save it. |
| A `status` of not connected | The provider is not connected for this session. | `initiate` and hand the deep-link to the operator. |

## 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`](/docs/concepts/meta-tools/discover): the discover → connect → call loop
- [`codespar_shop`](/docs/concepts/meta-tools/shop): the buyer whose identity and logins this tool holds
- [Shopper identity](/docs/concepts/shopper-identity): what the vault stores and the email rule
- [Authentication](/docs/concepts/authentication): how connections are scoped and persisted
- [Connect links](/docs/concepts/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](/docs/api/sdk/session#connectionwizardserverid-promiseconnectionwizardresult)).

**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).