Agent Integration Patterns

Choose the Right MCP Surface

Lamina has two hosted OAuth MCP endpoints:

Endpoint	Use it for	Tool count
`https://app.uselamina.ai/mcp/agent/v2`	Outcome-level creative tasks, safe multi-step pipelines, and normal agent use	7
`https://app.uselamina.ai/mcp/agent`	Direct app/model control, composition, brand mutations, generated-app management, or checkout	30

Start with v2. It gives the agent a small task-level contract and lets Lamina select and stitch creative capabilities into a frozen plan. Move to the advanced surface only when the request requires a lower-level operation that v2 does not expose. Both endpoints share one authorization server, but each advertises its own OAuth resource matching the URL you connect to (as RFC 9728 requires):

https://app.uselamina.ai/mcp/agent/v2   ← resource for the v2 front door
https://app.uselamina.ai/mcp/agent      ← resource for the v1 advanced endpoint

So a client connecting to /mcp/agent/v2 discovers metadata at /.well-known/oauth-protected-resource/mcp/agent/v2. Migrating v1 → v2 needs no re-authorization: tokens minted for the legacy /mcp/agent resource are cross-accepted at the v2 endpoint.

Connect

Install page:

https://app.uselamina.ai/mcp/install

Recommended hosted endpoint:

https://app.uselamina.ai/mcp/agent/v2

For a remote MCP client:

{
  "mcpServers": {
    "lamina": {
      "url": "https://app.uselamina.ai/mcp/agent/v2"
    }
  }
}

For a client that only supports local stdio servers, bridge to the hosted OAuth server:

{
  "mcpServers": {
    "lamina": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent/v2"]
    }
  }
}

mcp-remote opens the hosted OAuth flow in a browser. Do not add an API key to the configuration. The retired @uselamina/mcp package is not a supported local server.

The Seven v2 Tools

Tool	Purpose
`lamina_plan`	Turn a brief into a stored, costed, immutable pipeline without dispatching generation
`lamina_execute`	Execute the exact approved plan with a hard credit ceiling and idempotency key
`lamina_status`	Read or wait for pipeline, workflow, atomic, or compose runs through one normalized lifecycle
`lamina_cancel`	Request idempotent cancellation for any supported run family
`lamina_upload_asset`	Issue a signed URL for uploading an image, video, or audio input
`lamina_brand_context`	Read workspace brand context and return the profile ID to use during planning
`lamina_credits`	Read the workspace credit balance before paid work

Recommended Agent Flow

Load context

Call lamina_credits before expensive work. If the request is brand-sensitive, call lamina_brand_context and pass its brandProfileId into planning.

Plan

Call lamina_plan with the brief, known platform/modality, asset URLs, and any maximum estimated cost. Planning may use a paid router, but it does not dispatch creative generation.

Clarify

If the plan status is needs_clarification, ask questions[] and plan again. If it is awaiting_approval, collect answers for requiredInputs[] and keep them for execution without re-planning.

Approve

Show the frozen steps, outputs, warnings, and estimated credits. Obtain explicit user approval for the plan and budget.

Execute

Call lamina_execute with the unchanged planId, planFingerprint, collected inputs, a finite positive maxCredits, and an idempotencyKey.

Track

Call lamina_status with the returned runId. Use wait=true and an optional timeoutSeconds of at most 25. If the response is still non-terminal or reports timedOut: true, call status again with the same run ID.

Deliver

Return completed entries from outputs[], using each output’s url, media type, and label. Never claim success from a queued or running snapshot.

Plan and Execute Contract

Example plan request:

{
  "tool": "lamina_plan",
  "arguments": {
    "brief": "Create a branded product hero image and a matching five-second launch clip.",
    "platform": "instagram",
    "brandProfileId": "<brand-profile-id>",
    "inputs": {
      "productImage": "https://example.com/shoe.png"
    },
    "maxEstimatedCredits": 120
  }
}

A successful plan returns a stored planId, planFingerprint, steps, output descriptions, required inputs, warnings, expiry, and estimatedCredits. A null estimate means unknown, not free. Execution must preserve the approved plan:

{
  "tool": "lamina_execute",
  "arguments": {
    "planId": "<plan-id>",
    "planFingerprint": "<exact-fingerprint-from-plan>",
    "inputs": {
      "productImage": "https://example.com/shoe.png"
    },
    "maxCredits": 120,
    "idempotencyKey": "launch-shoe-v1"
  }
}

Set allowUnknownCost: true only after displaying the unknown-cost warning and receiving approval. Reuse an idempotency key only for an exact retry; change it when the plan, inputs, or budget changes.

Uploading Local Assets

lamina_upload_asset issues an upload URL; it does not transfer the file bytes:

{
  "tool": "lamina_upload_asset",
  "arguments": {
    "filename": "shoe.png",
    "mediaType": "image"
  }
}

PUT the bytes to the returned uploadUrl with the required content type, then use assetUrl as a plan input. If the agent host cannot upload bytes, ask the user for a public asset URL.

Status and Cancellation

Always pass runId back exactly as returned. The v2 status tool normalizes pipeline, app-workflow, atomic image/video, and compose runs into the same lifecycle and returns completed assets in outputs[]. For voiceover runs, a completed status also carries details.legibility — a word-timed transcript plus measured delivery (words-per-minute, pace arc, pauses, emphasised words, and per-word loudness: dynamic range, loudest/softest words, and strong-emphasis words that are both drawn-out and loud) and the voice direction that was requested. Use it to evaluate whether the audio is on-brand and to give feedback, since the audio itself cannot be heard. Cancellation is provider-dependent. cancel_requested means Lamina accepted the request but may need the active provider operation to finish before stopping the next step. not_cancellable and cancel_requested must not be reported as confirmed cancelled.

When to Use the Advanced Endpoint

Connect separately to https://app.uselamina.ai/mcp/agent when the user needs:

direct app discovery, description, or app execution
direct atomic image/video model selection and generation
narrated-video composition controls
brand score, feedback, refinement, or brand-kit mutation
generated-app versioning, feedback, or visibility changes
a Stripe-hosted credit top-up link

The advanced endpoint exposes 30 tools. Its lamina_create tool is plan-only:

lamina_create → ask askUser[] questions → lamina_run

It never dispatches generation itself. Use lamina_run for a selected app, and use the universal lamina_status and lamina_cancel tools for the returned run ID.

REST Integrations

MCP uses lamina_status for delivery. Server-side integrations against /v1 can instead attach a signed webhook:

POST /v1/apps/{appId}/runs?webhook=https://your-agent.com/lamina-callback

For direct REST app runs, fetch current app metadata first and use the exact parameter keys and option labels it returns. REST workflow outputs use their documented value field; v2 MCP status normalizes completed artifact links as outputs[].url.

Reliable Agent Behaviors

plan before spending and obtain explicit approval
preserve the plan fingerprint and run ID exactly
keep a finite credit ceiling
retry timed-out status waits instead of redispatching work
upload bytes before using a signed asset URL
treat unknown cost as unknown
surface typed failures and cancellation states truthfully

Avoid guessing app IDs, model IDs, parameter names, option labels, brand facts, output URLs, or required assets.

Overview

Install

Concepts

API Reference

Guides

Agent Integration Patterns

Choose the Right MCP Surface

Connect

The Seven v2 Tools

Recommended Agent Flow

Plan and Execute Contract

Uploading Local Assets

Status and Cancellation

When to Use the Advanced Endpoint

REST Integrations

Reliable Agent Behaviors

​Choose the Right MCP Surface

​Connect

​The Seven v2 Tools

​Recommended Agent Flow

​Plan and Execute Contract

​Uploading Local Assets

​Status and Cancellation

​When to Use the Advanced Endpoint

​REST Integrations

​Reliable Agent Behaviors

Choose the Right MCP Surface

Connect

The Seven v2 Tools

Recommended Agent Flow

Plan and Execute Contract

Uploading Local Assets

Status and Cancellation

When to Use the Advanced Endpoint

REST Integrations

Reliable Agent Behaviors