Skip to main content
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 and 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 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.
  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 and 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.