Guide

Agent integration

Tool-using LLMs talking to Clement directly — MCP, dry-runs, confirmation patterns, llms.txt.

Clement is designed to be wired to a tool-using LLM directly. The full agent surface ships in API phase A8 and this guide fills in when that phase merges. Until then, here’s the shape so you can plan against it.

What’s already in place

• Type-prefixed IDs. An LLM looking at inb_… knows it’s an inbox without a schema lookup. Same for cmp_…, snd_…, whk_…, etc.
• OpenAPI 3.1 spec. Hosted at api.clement.so/openapi.json. Self-describing JSON Schema. Any tool that ingests OpenAPI — mcp-openapi, openapi-typescript, Postman, Bruno — speaks Clement out of the box.
• llms.txt and llms-full.txt. Concise and verbose dumps of the API for agent ingestion.
• Stable error codes with doc_urls. When an agent gets a 422, the URL leads it to a page that explains exactly how to fix the request. See Errors.

What lands with A8

• Hosted MCP server at mcp.clement.so — workspace-scoped, bearer-auth’d. The toolset is generated from the OpenAPI spec at boot, so endpoint additions automatically become tools.
• ?dry_run=true on side-effect-bearing operations. POST /v1/campaigns/{id}/start?dry_run=true returns the projected schedule — which inbox, when, to whom — without committing. Agent presents it, human approves, then re-call without dry_run.
• ?confirm=true on high-blast-radius destructive operations. DELETE /v1/inboxes/{id} and POST /v1/api_keys/{id}/rotate require it; without, you get 400 confirmation_required with a body describing the impact (counts, names, downstream effects).
• Per-key auto_confirm: true — bypasses the confirmation prompt for trusted automation. Off by default. The column already exists on api_keys.
• Examples on every endpoint. OpenAPI examples will be filled out for both request and response on every operation, and the docs site (this site) renders them automatically — they’re already pulled if present in the spec.

Recommended pattern

import { Clement } from "@clement/sdk";
const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });

// 1. Probe the workspace.
const ws = await c.request("GET", "/v1/workspace");
// returns { id, name, plan, limits, usage } — useful for planning

// 2. Dry-run before committing.
const projection = await c.campaigns.start("cmp_...", { dryRun: true });
// projection.steps describes exactly what would happen

// 3. After human ack, commit.
const live = await c.campaigns.start("cmp_...");

Until A8 ships, design against the contract above and the existing reference. The pieces that aren’t live yet (?dry_run, ?confirm, MCP) will turn on without breaking call sites — additive only is the rule, see API design principles §1.