> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build with Semicola

> Use when connecting an agent or app to Semicola for the first time: reach the v3 MCP endpoint, verify access read-only, read the live tool contract and learn the rules every other skill assumes.

Skill `build-with-semicola` · version 1.0.0 · for any agent, buyer or seller.

## When to use

* You are wiring a new agent, script or MCP client to Semicola.
* A person asks you to work in Semicola and you have not connected in this session.
* Another skill failed on its first call and you need to check the connection itself.

Once you are connected, switch to the skill for the task at hand. This skill never creates or
changes anything.

## Before you start

* An MCP client that speaks Streamable HTTP, or a plain HTTP client for the REST API.
* One credential. Use OAuth 2.1 with PKCE when a person is present to sign in, or an API key the
  person has placed in your environment when you run headless. Never ask for a key in chat.
* If the person belongs to several accounts, know which one they want you to act for.

## Steps

1. Add `https://api.semicola.com/mcp/v3` to your client and authenticate. The details are in
   [MCP client setup](/v3/client-setup) and [Authentication](/v3/authentication).
2. Call `tools/list` and read every schema you plan to use. The result is the contract for this
   session. The [v3 Tool Catalog](/v3/tool-catalog) describes the same tools, but your account and
   role may list fewer.
3. Call `get_status`. It is read-only. Note the active account, your role, readiness, blockers and
   `nextActions`.
4. If the active account is not the one the person meant, call `switch_account` with a `customerId`
   taken from the `get_status` result, then call `get_status` again.
5. Before you create anything, look for what already exists: `search` with a `kind` such as
   `advertiser`, `campaign` or `seller`, then `get` for the full record.
6. Call `get` with `kind: "skill"` to read any workflow guidance the account has configured, then
   load the matching task skill from the [skills catalog](/skills/overview).
7. When the person should see a screen rather than a text summary, open it with `open_page` or the
   more specific opener the task skill names, instead of rebuilding the view in text.

## Guardrails

* Keep three claims apart: signed in (the OAuth or key exchange worked), allowed (the account and
  role list the tool), and called (a tool returned a result). Report only what you observed.
* Every write takes an `idempotencyKey` of 16 to 255 characters from `A–Z a–z 0–9 _ . : -`. Reuse a
  key only to retry the same attempt; a new attempt gets a new key.
* Writes to an existing object send `expectedRevision`. After a `REVISION_CONFLICT`, read the object
  again and decide again rather than bumping the number.
* `needs_input` means a fact is missing. Ask the person the question it returns; never invent the
  value.
* `pending_confirmation` means a person must approve. Show the summary, wait for an explicit yes,
  then call the same tool with `confirm: true` and the `confirmationUid`. Confirmations expire after
  15 minutes.
* A brief, a budget or a proposal is never authority to spend.
* If the platform cannot do what the person needs, file it with `save_ask` rather than working
  around it. See [Errors](/v3/errors) and [Limits](/v3/limits) for failure shapes and bounds.

## Done when

* `get_status` succeeds on the account the person intended.
* You have read `tools/list` and know which tools this account can call.
* You have told the person the account, your role, any blockers, and the task skill you will use
  next.