---
title: codespar_manage_connections
description: Connection wizard backend. List, status, and initiate operations let an agent introspect connections and surface a connect-URL when a provider is missing.
---

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

# codespar_manage_connections

<Callout title="Meta-tool" type="info">
**Shared rail.** Used by both buy-side and sell-side agents; not tied to a money direction.

`codespar_manage_connections` lets the agent inspect which providers the current session has connected and, when a needed provider is missing, kick off a connection flow. Pairs with [`codespar_discover`](/docs/concepts/meta-tools/discover) — discover finds the right tool, manage_connections checks whether it is reachable for this user (and unblocks the flow if not).
</Callout>

Covered by `session.connectionWizard(serverId)` typed wrapper for the most common case (initiate a wizard for a specific server).

## Typed wrapper

<Tabs items={["TypeScript", "Python"]}>

```ts tab="TypeScript"
const wiz = await session.connectionWizard("mercado-pago");

if (wiz.status === "needs_setup") {
  // Surface the wizard URL in your UI — the operator clicks through, completes auth,
  // and the connection becomes available to subsequent tool calls.
  console.log("Open:", wiz.wizard_url);
} else if (wiz.status === "connected") {
  console.log("Already connected:", wiz.connection_id);
}
```

```python tab="Python"
wiz = session.connection_wizard("mercado-pago")

if wiz["status"] == "needs_setup":
    print("Open:", wiz["wizard_url"])
elif wiz["status"] == "connected":
    print("Already connected:", wiz["connection_id"])
```

</Tabs>

## Direct execute

Three operations are supported:

```ts
// List all connected providers in this session
const list = await session.execute("codespar_manage_connections", {
  operation: "list",
});

// Status of a specific server
const status = await session.execute("codespar_manage_connections", {
  operation: "status",
  server_id: "asaas",
});

// Initiate a wizard URL the operator can click
const flow = await session.execute("codespar_manage_connections", {
  operation: "initiate",
  server_id: "z-api",
});
```

## Args shape

| Field | Type | Required | Description |
|---|---|---|---|
| `operation` | `"list"` \| `"status"` \| `"initiate"` | Yes | What to do |
| `server_id` | `string` | for `status` and `initiate` | Server slug (e.g. `asaas`, `mercado-pago`, `z-api`) |

## Result shape

The result depends on the operation.

**`list`:**

```ts
{
  connections: Array<{
    server_id: string;
    connection_id: string;
    status: "connected" | "expired" | "error";
    connected_at: string; // ISO 8601
  }>;
}
```

**`status`:**

```ts
{
  server_id: string;
  status: "connected" | "needs_setup" | "expired" | "error";
  connection_id?: string;
  expires_at?: string;
}
```

**`initiate`:**

```ts
{
  server_id: string;
  status: "needs_setup" | "connected"; // if already connected, returns immediately
  wizard_url?: string; // deep-link the operator follows to complete auth
  connection_id?: string;
}
```

The `wizard_url` is a deep-link into `/dashboard/auth-configs` (or `/dashboard/connections` for project-scoped flows) with the right server preselected. Render it in your chat UI or dashboard — when the operator finishes the flow, the connection is immediately available to subsequent tool calls in the same session.

## Connection bias loop

The canonical agent pattern uses both meta-tools together:

```ts
// 1. Find the right tool
const matches = await session.discover("issue an NF-e for a Brazilian customer");

// 2. Check if the top match is reachable
const top = matches.matches[0];
if (!top.connected) {
  // 3. Surface the wizard URL to the user
  const wiz = await session.connectionWizard(top.server_id);
  return { needs_connection: wiz.wizard_url };
}

// 4. Otherwise, just call the tool
return await session.execute(top.tool_name, args);
```

## Operator setup

No operator setup needed for `codespar_manage_connections` itself — it queries the CodeSpar backend's `connected_accounts` table for the current session. The wizard URLs it returns point at provider-specific connect flows that DO require operator setup; see each provider's page in [`/docs/providers/`](/docs/providers/openai) (placeholder).

## See also

- [SDK reference — connectionWizard](/docs/api/sdk#connectionwizardserverid-promiseconnectionwizardresult)
- [codespar_discover](/docs/concepts/meta-tools/discover) — pair with this for the discover → connect → call loop
- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list
- [Authentication](/docs/concepts/authentication) — how connections are scoped + persisted