codespar_get_started

Read-only setup planner, read live. In Test it reads the project account, its balance and its active mandates, then returns the next step that can actually run. Moves no money.

Shared railUsed by buy-side and sell-side agents alike; not tied to a money direction.

The ordered happy path for this workspace: what is connected, what to connect next, what to call first.

tool codespar_get_startedone operationmoves no money

Call it first when a user opens with "how do I start" or "what can you do". It saves the agent a discovery detour: instead of guessing at tool names, it gets the sequence that works for this workspace in this environment.

Actions

Operation	What it does	Money	Needs
single call, no selector	Return the ordered happy path for this workspace and environment; read-only, no arguments, nothing executed	no	—

Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.

Example

The tool takes no arguments: workspace, project and environment all derive from the API key on the session.

The same call, four ways

arguments

{
  "name": "codespar_get_started",
  "arguments": {}
}

const result = await session.execute("codespar_get_started", {});

result = session.execute("codespar_get_started", {})

codespar tool codespar_get_started \
  -i '{}'

Result · Test, a funded account with no mandate

result

{
  "environment": "test",
  "summary": "You're in the CodeSpar test environment: no real money moves, and Pix in and out need no bank connection, CNPJ or KYC. The project's Test account holds R$ 969,26 now (R$ 969,26 available), so it needs no top-up.",
  "binding": { "environment": "test", "project_id": "prj_…", "consumer_id": "sbx_prj_…" },
  "account": { "kind": "account", "balance_minor": 96926, "available_minor": 96926, "currency": "BRL" },
  "mandates": [],
  "happy_path": [
    { "step": 1, "title": "Read the Test account", "tool": "codespar_wallet", "detail": "action=balance reads the spendable balance and the account's Pix key; action=statement reads its movements. …" },
    { "step": 2, "title": "Receive a Pix", "tool": "codespar_charge", "detail": "Issues an inbound Pix charge on the Test rails (the buyer pays you). No mandate is needed to receive." },
    { "step": 3, "title": "Pay under a signed mandate", "tool": "codespar_pay", "detail": "This project has no active mandate, so codespar_pay refuses and sends nothing. … Only a person creates and signs one, in the CodeSpar dashboard under Agents …" }
  ],
  "tools": {
    "ready": ["codespar_get_started", "codespar_wallet", "codespar_ledger", "codespar_charge", "codespar_discover", "codespar_manage_connections"],
    "need_setup": [{ "tool": "codespar_pay", "reason": "needs an active mandate signed by a person (dashboard, Agents)" }, "…"]
  }
}

The plan is read at call time, never assumed:

Binding. binding names the environment, the project and the consumer that codespar_wallet and codespar_ledger read by default. On the hosted connector and in a conversation, that is the project's Test account, the one the Wallet page shows.
Account, four cases. account.kind is account (the balance as it is now, zero included), preparing (the Test account is being prepared), not_permitted (the key lacks wallets:read, named in required_scope), or account is null (the read failed now). None of them means "fund the wallet". The R$ 1.000 a Test account starts with is its initial credit, not its balance.
Mandates. mandates lists the project's active mandates: whose account pays (consumer_id), the agent it names, the per-payment cap, what is remaining_minor of the cap, how many payees it allows and the expiry. With none, the plan says that only a person creates and signs one, in the dashboard under Agents, and codespar_pay moves to tools.need_setup.
Tools. tools.ready acts now; tools.need_setup needs a connection or a person's setup first, each with its reason.

A csk_live_* key gets a path that starts with onboarding and connecting real rails, since live settlement needs a funding source before it can move money.

A store checkout in Test is a real order at the store

codespar_shop runs the store's real checkout in Test too: it places a real order at the store, awaiting payment, with demo buyer data for any field not given. The Pix that is then paid is a test substitute minted for the same total to the platform's test receiver, so the store is never paid and its order stays unpaid. Tell the person before a Test checkout.

When to use

The first turn of a setup conversation. The result is a structured, ordered plan the agent can follow step by step, each step naming the tool to call and how.
Before deciding anything. It is read-only, so it is safe to call on every fresh session.
Not for an open intent ("buy a TV"): that is codespar_discover.

Arguments

None. The published schema declares no properties. Any argument passed is ignored.

Errors and what to do

Error	Cause	What to do
The tool is the only one visible	The API key is missing or invalid: setup mode exposes exactly one tool, the no-key setup tool that mints a key, under this same name.	Mint or fix the key, then reconnect; the authenticated tool then hands back the happy path.
`account.kind: "not_permitted"`	The key or connection lacks `wallets:read`.	A person grants it in the dashboard under API keys. Never ask for a key or any secret in the conversation.
`account` is `null`	The balance could not be read now.	Read it with `codespar_wallet` `action=balance`; this is a read failure, not an empty account.

Money and mandate

Nothing moves, by construction. The tool returns text: it creates no payment, no charge, no connection and no wallet, and it takes no argument that could target a counterparty. Nothing it returns has a side effect until the agent calls one of the tools named in the plan, each under its own gates.

codespar_discover: use it for an open intent once you are past setup
codespar_manage_connections: connect the rails the plan asks for
Test mode: what the sandbox rails do and do not do

Notes

One name, two tools. Exactly one codespar_get_started is ever visible. With no valid key the MCP server exposes its setup tool, which mints a key. Once a valid key is present the server exposes the backend meta-tools instead, and this one hands back the happy path. An agent with no usable key gets exactly one thing it can do, not a catalog it cannot call.

Result shape (SDK), as previously documented. { environment: "live" | "test", summary, happy_path: Array<{ step, title, tool, detail }>, notes: string[] }, which is the shape of the example above. This revision did not re-run the call to confirm the wording of the current plan.

codespar_get_started

On this page