Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselamina.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Use Hosted MCP When Your Agent Supports Remote Install

The preferred agent integration is Lamina’s hosted remote MCP server. It lets MCP clients install Lamina through OAuth, bind access to a Lamina workspace, and call the five high-level creative tools without placing an API key in every tool call. Install page: 
https://app.uselamina.ai/mcp/install
Hosted endpoint: 
https://app.uselamina.ai/mcp/agent
The endpoint supports OAuth discovery:
  • protected resource metadata: /.well-known/oauth-protected-resource/mcp/agent
  • authorization server metadata: /.well-known/oauth-authorization-server
  • authorization endpoint: /mcp/oauth/authorize
  • token endpoint: /mcp/oauth/token
  • dynamic client registration: /mcp/oauth/register
Read MCP OAuth Install for the full install and verification flow. Read Agent Recipes for end-to-end create, wait, clarification, brand context, and artifact reuse examples. Use Agent Runtime Benchmarks to measure install success, auth reliability, first generation time, clarification loops, and output usability across MCP clients.

​
Use Local MCP When Your Agent Can Spawn Tools

If your agent platform only supports local stdio MCP, run the Lamina MCP server locally and let the agent call tools instead of hand-rolling HTTP requests. Today, the MCP server lives in this repository and can be started with: 
lamina mcp serve
Or directly: 
npx -y @uselamina/mcp
The local stdio MCP server uses the same Lamina API key resolution order as the CLI:
  1. explicit --api-key
  2. LAMINA_API_KEY
  3. saved CLI login from ~/.lamina/config.json

​
MCP Tool Surface

The MCP server intentionally exposes five high-level tools. This keeps agent tool selection simple while preserving the full /v1 REST API for developer integrations and power users.
  • lamina_create - create brand-aware content from a natural-language brief
  • lamina_status - check a run or wait for generated assets
  • lamina_discover - find what Lamina can make for a creative goal
  • lamina_brand - load brand memory, guidance, and winning patterns
  • lamina_batch - queue up to 10 related content creations
Lower-level operations such as direct app inspection, direct app execution, publishing, asset transfer, usage, templates, and webhook management remain available through /v1.

​
Example MCP Client Configuration

For hosted remote MCP clients, add the remote server URL and complete OAuth in the client: 
{
  "mcpServers": {
    "lamina": {
      "url": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
For local agent clients that support a spawned process: 
{
  "mcpServers": {
    "lamina": {
      "command": "npx",
      "args": ["-y", "@uselamina/mcp"],
      "env": {
        "LAMINA_API_KEY": "lma_your_api_key"
      }
    }
  }
}
If the agent runs under the same user account as your CLI login, it can also reuse the saved key from ~/.lamina/config.json.

​
Build Agents Around Outcomes, Not Raw APIs

Lamina apps are not single-shot utility functions. They are packaged creative workflows with asynchronous execution. Agents should usually describe the desired outcome to lamina_create instead of chaining low-level calls themselves. An agent should treat Lamina as a system with:
  • discoverable app capabilities
  • brand-aware prompt and input mapping
  • asynchronous execution
  • polling-based result delivery through lamina_status
  • typed outputs
The best integrations do not guess raw workflow inputs from app names alone. They let Lamina select and run the workflow, and only pass appId or advanced inputs when a developer already knows the exact workflow contract.
1

Create from a brief

Call lamina_create with the user’s creative request, target platform, and modality when known.
2

Track the run

Call lamina_status with the returned runId. Set wait=true when the agent should block for final assets.
3

Discover options when unsure

Call lamina_discover when the user asks what Lamina can make, or when the agent needs workflow suggestions before creating.
4

Load brand context when useful

Call lamina_brand when the agent needs explicit voice, visual, guardrail, or pattern context for planning.
5

Batch related work

Call lamina_batch for catalog shots, campaign variants, or content series.

​
Webhooks For REST Integrations

The MCP surface uses lamina_status for result polling. If you are building a server-side integration against /v1, you can use REST webhooks instead:
  1. expose a public HTTPS callback URL from your integration
  2. start a run with POST /v1/apps/{appId}/runs?webhook=<public_callback_url>
  3. verify the signed callback when Lamina sends completion data
This lets your application react to the Lamina callback directly instead of polling.

​
Direct REST App Runs

When using direct REST app execution instead of lamina_create, fetch app metadata unless you already have fresh metadata cached for that exact appId. This is important because the app metadata is the source of truth for:
  • parameter names
  • whether fields are required
  • valid options labels
  • whether a field expects a media URL

​
Use Parameter Names Exactly

When calling POST /v1/apps/{appId}/runs, inputs should be keyed by parameter name. Example: 
{
  "inputs": {
    "Front": "https://example.com/front.jpg",
    "Location": "Studio"
  }
}
Do not invent aliases or normalize parameter names unless your integration keeps a reliable mapping layer.

​
Handle options Carefully

For parameters of type options, send one of the labels returned by the app metadata. If the app says the valid options are: 
["Male", "Female"]
then the execution request should send one of those exact labels.

​
Prefer Webhooks In Production

For production agent integrations, always use webhooks instead of polling: 
POST /v1/apps/{appId}/runs?webhook=https://your-agent.com/lamina-callback
Benefits over polling:
  • No polling loop to manage
  • Results arrive immediately when ready
  • Signed with ED25519 - verify authenticity
  • Automatic retries if your endpoint is temporarily down
For MCP clients, prefer lamina_create followed by lamina_status unless your integration needs direct REST webhook control.

​
Webhook Payload Structure

The webhook payload matches the polling response exactly: 
{
  "data": {
    "runId": "...",
    "workflowId": "...",
    "status": "completed",
    "outputs": [
      { "id": "...", "label": "Generated Image", "type": "image", "value": "https://...", "status": "completed", "error": null }
    ],
    "errorMessage": null,
    "startedAt": "...",
    "completedAt": "...",
    "createdAt": "..."
  }
}
data.executionId may also be present as a deprecated compatibility alias for data.runId. New integrations should store and compare runId.

​
Read Output Type Before Consuming Value

Do not assume every output is an image URL. Check:
  • type
  • status
  • value
Examples of output types include:
  • image
  • video
  • text
  • pending

​
Handle Failures Explicitly

If execution fails:
  • inspect top-level errorMessage
  • inspect each output’s error
  • avoid blindly retrying the same invalid inputs
If the failure is caused by invalid inputs, fetch the app metadata again and rebuild the request payload.

​
Good Agent Behaviors

  • use lamina_create for brief-to-result work
  • cache app metadata briefly, but refresh when uncertain
  • use lamina_status for MCP result delivery
  • preserve runId for later retrieval
  • branch logic on output type
  • verify webhook signatures
  • surface execution failure with the returned error details

​
Poor Agent Behaviors

  • guessing parameter names from natural language
  • sending internal option IDs that were never returned by the API
  • treating execution as synchronous
  • resubmitting the same long-running request repeatedly because output is not immediate
  • ignoring webhook signatures