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

codespar_manage_connections

Meta-tool

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 — discover finds the right tool, manage_connections checks whether it is reachable for this user (and unblocks the flow if not).

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

Typed wrapper

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);
}

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"])

Direct execute

Three operations are supported:

// 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:

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

status:

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

initiate:

{
  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:

// 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/ (placeholder).

codespar_manage_connections

codespar_manage_connections

Typed wrapper

Direct execute

Args shape

Result shape

Connection bias loop

Operator setup

See also

On this page