Skip to main content

​
What Agents Should Prefer

For interactive agents, prefer hosted MCP: 
https://app.uselamina.com/mcp/agent
For server-side agents, use the SDK or REST API with LAMINA_API_KEY. Hosted MCP and REST share the same runtime model: create work, preserve runId, wait or subscribe to completion, inspect typed outputs, and reuse final artifacts explicitly.

​
Recipe 1: Hosted MCP Creative Run

After installing Lamina MCP in Claude Code, Codex, Cursor, or another MCP client, use this flow:
1

Create

Call lamina_create with brief, platform, and modality.
2

Clarify if needed

If the response status is needs_input, ask the user for the listed missing fields and call lamina_create again with those values in inputs.
3

Wait

Call lamina_status with runId and wait=true.
4

Reuse

Inspect each output’s type, status, and value. Reuse completed asset URLs as explicit references in the next Lamina run.
Example MCP call: 
{
  "tool": "lamina_create",
  "arguments": {
    "brief": "Create a cinematic launch image for a premium running shoe.",
    "platform": "instagram",
    "modality": "image"
  }
}
Expected started response: 
{
  "runId": "99ebc7c6-24f3-4fc2-9d53-2e3f49f3bec1",
  "status": "queued",
  "workflowName": "Product Hero Image",
  "selectedApp": {
    "name": "Product Hero Image",
    "whyMatched": "Matches image launch creative intent"
  }
}
Expected clarification response: 
{
  "runId": null,
  "status": "needs_input",
  "needsInput": {
    "message": "This workflow needs additional inputs before Lamina can start the run.",
    "missing": [
      {
        "name": "Product Image",
        "type": "url",
        "accept": ["image"]
      }
    ],
    "suggestedPrompt": "Ask the user for Product Image."
  }
}

​
Recipe 2: Local Stdio MCP Variant

Use local stdio MCP when the agent can spawn local tools but cannot complete remote OAuth. 
{
  "mcpServers": {
    "lamina": {
      "command": "npx",
      "args": ["-y", "@uselamina/mcp"],
      "env": {
        "LAMINA_API_KEY": "lma_your_api_key"
      }
    }
  }
}
The tool flow is the same as hosted MCP: call lamina_create, handle needs_input, then call lamina_status with the returned runId.

​
Recipe 3: TypeScript Agent With SDK

Use this for Node.js agents, backend workers, and agent runtimes that own their own API key. 
import { LaminaClient } from '@uselamina/sdk';

const client = LaminaClient.fromEnv();

const created = await client.content.create({
  brief: 'Create a premium Instagram launch visual for a running shoe.',
  platform: 'instagram',
  modality: 'image',
});

if (created.data.needsInput || !created.data.runId) {
  console.log(created.data.needsInput?.missing);
  console.log(created.data.needsInput?.suggestedPrompt);
  process.exit(0);
}

const result = await client.runs.wait(created.data.runId, {
  timeoutMs: 120_000,
  intervalMs: 4_000,
});

for (const output of result.data.outputs) {
  if (output.status === 'completed') {
    console.log(output.type, output.value);
  }
}
Full example: 
examples/agents/typescript/creative-agent-recipe.ts

​
Recipe 4: Python Agent With REST

Use this when the agent is written in Python or runs in an environment without the TypeScript SDK. 
created = request(
    "/v1/content/create",
    method="POST",
    body={
        "brief": "Create a cinematic launch image for a premium running shoe.",
        "platform": "instagram",
        "modality": "image",
    },
)

if created["data"].get("needsInput") or not created["data"].get("runId"):
    print(created["data"].get("needsInput", {}).get("missing", []))
    raise SystemExit(0)

status = wait_for_run(created["data"]["runId"])
Full example: 
examples/agents/python/creative_agent_recipe.py

​
Recipe 5: Brand-Aware Planning

Agents should call brand context before generating when the user asks for brand-safe, campaign-safe, or performance-aware content. 
const brand = await client.intelligence.getBrandContext({
  platform: 'instagram',
  modality: 'image',
  objective: 'launch campaign',
});

console.log(brand.data.brandDna?.guardrails ?? []);
console.log(brand.data.guidance?.promptDirectives ?? []);
For MCP clients, use lamina_brand before lamina_create when the agent needs explicit voice, visual, guardrail, or winning-pattern context.

​
Recipe 6: Artifact Reuse

Agents should not scrape provider-specific payloads. Treat completed outputs with string value fields as reusable artifact URLs. 
const artifacts = result.data.outputs
  .filter((output) => output.status === 'completed' && typeof output.value === 'string')
  .map((output) => ({ type: output.type, url: output.value }));

if (artifacts[0]) {
  await client.content.create({
    brief: 'Create a matching story variant using this reference.',
    platform: 'instagram-story',
    modality: artifacts[0].type,
    inputs: {
      Reference: artifacts[0].url,
    },
  });
}

​
Smoke Test Checklist

Run this checklist for every supported MCP client before broad distribution:
  1. Install https://app.uselamina.com/mcp/agent.
  2. Complete OAuth and choose a workspace.
  3. Confirm the client lists exactly five Lamina tools.
  4. Call lamina_discover for an image or video launch brief.
  5. Call lamina_create with a simple brief.
  6. If needs_input is returned, provide the missing input and retry.
  7. Call lamina_status with wait=true.
  8. Confirm completed outputs include typed values the agent can reuse.
  9. Remove or revoke the client after testing if it used a temporary workspace.

​
Troubleshooting

  • authorization_required: start OAuth from the MCP client or reinstall the hosted server.
  • insufficient_scope: reconnect and approve the requested scope.
  • needs_input: ask the user for the listed missing field; do not start a run with guessed data.
  • failed: surface errorMessage and output-level errors; do not blindly retry invalid inputs.
  • Timeout while waiting: call lamina_status again with the same runId.