---
title: codespar_get_started
description: Read-only setup planner. Returns the ordered happy path for the authenticated workspace, covering which rails are already connected, what to connect next, and the first calls to try. Moves no money.
---

import { Callout } from "fumadocs-ui/components/callout";

# codespar_get_started

<Callout title="Meta-tool" type="info">
**Shared rail.** Read-only. `codespar_get_started` answers "how do I start / what
can you do" with a structured, ordered plan for the workspace the API key
belongs to. It never executes a charge and never moves money, so an agent can
call it before it has decided anything.
</Callout>

Call it first when a user opens with an open question about setup. It saves the
agent a discovery detour: instead of guessing at tool names, it gets the
sequence that actually works for this workspace in this environment.

## Read-only guarantee

The tool returns text. It creates no payment, no charge, no connection, and no
wallet, and it takes no arguments that could target a counterparty. Nothing it
returns has a side effect until the agent calls one of the tools named in the
plan.

## When it appears

`codespar_get_started` is always available on an authenticated session, and it
is the **only** tool surfaced when the API key is missing or invalid. That
setup mode is deliberate: an agent with no usable key gets exactly one thing it
can do, rather than a catalog it cannot call.

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. Same name, one entry point.

## Args shape

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

```ts
const plan = await session.execute("codespar_get_started", {});
```

```bash
curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/execute \
  -H "Authorization: Bearer csk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "codespar_get_started", "arguments": {} }'
```

## Result shape

```ts
type GetStartedGuidance = {
  environment: "live" | "test";
  summary: string;              // what this environment can do right now
  happy_path: Array<{
    step: number;               // ordered, 1-based
    title: string;
    tool: string;               // the meta-tool to call for this step
    detail: string;             // how to call it
  }>;
  notes: string[];              // caveats worth reading before step 1
};
```

### Example response (test environment)

```json
{
  "result": {
    "environment": "test",
    "summary": "You're in the CodeSpar test environment: sandbox rails (Pix in/out, wallet) ship PRE-CONNECTED. No bank connection, CNPJ, or KYC is needed to run the full happy path end to end.",
    "happy_path": [
      {
        "step": 1,
        "title": "Shop for a product",
        "tool": "codespar_shop",
        "detail": "action=search to browse a store's live catalog, then action=checkout and poll action=checkout_status until ready_for_payment returns the payable Pix copia-e-cola."
      },
      {
        "step": 2,
        "title": "Fund / inspect the governed wallet",
        "tool": "codespar_wallet",
        "detail": "action=balance reads the spendable balance; action=receive mints a Pix copia-e-cola to top the wallet up if it needs funding."
      },
      {
        "step": 3,
        "title": "Pay under a signed mandate",
        "tool": "codespar_pay",
        "detail": "action=pay settles the store's Pix from the governed wallet with policy + mandate + routing."
      }
    ],
    "notes": [
      "Sandbox rails are pre-connected — do NOT steer the user to connect a bank or upload a certificate in test."
    ]
  }
}
```

The plan differs by environment. A `csk_test_*` key gets the sandbox-first path
above, because the test environment ships every sandbox rail pre-connected. 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.

## See also

- [codespar_discover](/docs/concepts/meta-tools/discover): use it for an open intent once you are past setup
- [codespar_manage_connections](/docs/concepts/meta-tools/manage-connections): connect the rails the plan asks for
- [Tools & meta-tools](/docs/concepts/tools): full meta-tool list