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

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

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

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

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:

The server's instructions tell the agent to poll, so in practice a connected agent waits for completion on its own. See Jobs for job states.

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

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 contract.)

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.

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.)