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.

codespar_get_started

Meta-tool

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.

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.

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

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

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)

{
  "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.

codespar_get_started

codespar_get_started

Read-only guarantee

When it appears

Args shape

Result shape

Example response (test environment)

See also

On this page