> ## 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

> One account-aware MCP connection for planning, buying, selling and reporting across sellers.

Semicola keeps the advertising records (advertisers, campaigns, creatives, media buys, storefronts,
briefs and delivery) and does the work of reaching every connected seller. The v3 MCP endpoint
exposes that work as tools an agent can discover and call. Your software brings the interface, the
business data and the decisions it wants to own.

You do not need to think of your project as "an advertising agent". Start from the job: find places to
advertise, compare offers, prepare and launch a campaign, answer briefs as a seller, or pull results
into a report.

## What people build

| You are building               | Semicola gives you                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| A marketing assistant          | Turn a goal into options, draft a campaign, keep a person in control of launch, explain the results. |
| A buyer agent                  | Discover sellers, request and refine proposals, stage media buys and launch with confirmation.       |
| A seller integration           | Connect inventory, write business rules and a playbook, work incoming briefs, approve buys.          |
| A reporting pipeline           | Read delivery by campaign, media buy, package or seller, with currency kept intact.                  |
| A creative tool that also buys | Attach finished creative to a campaign and check format coverage before launch.                      |

## One endpoint, resolved by account

```text theme={null}
https://api.semicola.com/mcp/v3
```

The URL is the same for everyone. What you see depends on the credential: a buyer account gets buyer
tools, a seller account gets seller tools, and both get the shared tools. Call `get_status` first to
learn which account is active and what stands in its way, and treat `tools/list` as the contract for
your session.

Tools that open a widget declare it with `_meta.ui.resourceUri`. In hosts that support MCP Apps, such
as Claude and ChatGPT, the widget renders inline, just as it does in the Semicola app. Other clients
receive the same data as structured content and a text summary.

## MCP or REST

Use **MCP** when a model needs to discover capabilities and choose its next step. Use the **REST
API** (`https://api.semicola.com/api/v2/...`) when your code already knows what to call, for example
a nightly export. Both act on the same records.

## Safety is part of the contract

* **Writes are idempotent.** Every write takes an `idempotencyKey`; repeating it returns the first
  result.
* **Writes are versioned.** Changes send `expectedRevision`; a stale value fails instead of
  overwriting someone else's work.
* **Spending needs a person.** Launching a campaign or approving a buy returns
  `pending_confirmation` first. Only a second call, made after the person agrees, commits it.
* **Missing facts become questions.** A `needs_input` result asks for what is missing rather than
  guessing.

<CardGroup cols={2}>
  <Card title="Connect in five minutes" icon="plug" href="/v3/quickstart">
    Add the endpoint, sign in, and prove access with a read-only call.
  </Card>

  <Card title="MCP client setup" icon="gear" href="/v3/client-setup">
    Host-by-host configuration and connection lifetime.
  </Card>

  <Card title="Authentication" icon="key" href="/v3/authentication">
    OAuth for people, API keys for headless software.
  </Card>

  <Card title="v3 Tool Catalog" icon="toolbox" href="/v3/tool-catalog">
    Every tool, its risk, its widget and its input fields.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/v3/errors">
    Failure shapes and how to recover.
  </Card>

  <Card title="For agents" icon="robot" href="/agents/for-agents">
    The short brief to hand an autonomous agent.
  </Card>
</CardGroup>