# How it works (/docs/api/mcp-server/how-it-works)



The MCP server is a thin translation layer between an MCP client and the Partner API. These are the conventions it applies across the whole tool surface — learn them once and they hold for every tool.

## Transport [#transport]

It's a **stdio** server. The client spawns `@layers/mcp-server` as a child process and speaks JSON-RPC over stdin/stdout. There is **no HTTP listener** and no hosted endpoint — the server runs wherever the MCP client runs and makes outbound calls to the Partner API. That's why setup is just a `command` + `args`, never a URL.

## Server instructions [#server-instructions]

At MCP `initialize`, the server returns an `instructions` block describing how to drive the surface — what state to track, when to poll, how pagination and idempotency work, how errors are shaped. MCP clients load this automatically, so a connected agent starts already knowing the conventions below. You don't need to prompt them in.

## Tool annotations [#tool-annotations]

Every tool carries MCP annotation hints so a client can reason about safety before calling:

* **`readOnlyHint`** — the 25 read tools (`list_*`, `get_*`). A client may auto-approve these.
* **`destructiveHint`** — `delete_*`, `archive_*`, and `cancel_*` tools, which remove or tear down state.
* **`idempotentHint`** — `PATCH`/set-style writes (`update_*`) that converge to the same state on repeat.

Clients that surface approval prompts can use these to auto-approve reads while still gating destructive writes.

## Async jobs [#async-jobs]

Generation and a few other tools kick off background work. They return a **`202` job envelope** — a `jobId` plus the IDs of the resources being created (`containerIds`, `influencerId`) — and the work is **not finished** when the tool returns. Poll the matching read tool until the resource reaches a terminal state:

| Started by                                                                                     | Poll with              |
| ---------------------------------------------------------------------------------------------- | ---------------------- |
| `generate_slideshow`, `generate_ugc_remix`, `generate_video_remix`, `generate_slideshow_remix` | `get_content_progress` |
| `create_influencer`, `clone_influencer`                                                        | `get_influencer`       |
| `refresh_keywords`                                                                             | `get_keywords`         |

The server's instructions tell the agent to poll, so in practice a connected agent waits for completion on its own. See [Jobs](/docs/api/concepts/jobs) for job states.

## Pagination [#pagination]

List tools take `cursor` and `limit` and return `{ items, nextCursor }`. To page forward, pass the previous response's `nextCursor` back as `cursor`. A `null` (or absent) `nextCursor` means there's nothing more. This is the same keyset pagination the API uses.

## Idempotency [#idempotency]

The server stamps a fresh UUID `Idempotency-Key` on every mutating `POST`/`PATCH` automatically — one per tool call. You don't manage idempotency keys yourself. (Because each call gets a new key, a retried *tool call* is a new logical action; idempotency protects against transport-level duplication within a single call, matching the API's [idempotency](/docs/api/operational/idempotency) contract.)

## Errors [#errors]

When the API returns a 4xx/5xx, the server surfaces it as an **MCP tool error** carrying the Partner API envelope: a message of the form `Layers API <status> <code>`, plus the `requestId` and any `details`. The agent sees a structured failure it can act on — and you have the `requestId` to quote to support. The error codes are the same stable codes documented under [Errors](/docs/api/operational/errors).

## Timestamps [#timestamps]

All timestamps are **ISO 8601 UTC with a `Z` suffix**. In particular, `scheduledFor` is a literal UTC instant — convert from the customer's local time before calling. (The underlying project timezone still governs how the API interprets scheduling; see the [publishing reference](/docs/api/reference/publishing/schedule-content).)

<Callout type="info">
  None of these conventions are MCP-specific inventions — they're the Partner
  API's own semantics, surfaced through MCP. The endpoint reference pages remain
  the source of truth for every request and response shape.
</Callout>