MCP OAuth Install

Recommended Endpoint

Connect normal agent workflows to:

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

It exposes task-level tools for planning, approval, execution, status, cancellation, asset upload, brand context, and credits. The lower-level 30-tool endpoint is:

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

Use the advanced endpoint only when the agent needs direct app/model control, composition, brand or app mutations, refinement, or checkout. The hosted install page provides copyable values:

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

Brand MCP apps

After connecting, ask the agent to show available reference people without generating. MCP Apps hosts can display the Brand gallery/player; other hosts use native image previews or named file links. Keep media content blocks when forwarding tool results. See presentation and troubleshooting. For catalogue photos, banners, try-on and product ad films, connect separately to https://app.uselamina.ai/mcp/commerce. It uses the same OAuth service with its own workspace-scoped authorization. The main connection does not automatically add it.

npx add-mcp https://app.uselamina.ai/mcp/commerce --name lamina-brand

Follow the Brand MCP setup guide for app selection, multiple files, preset/custom person photos, required inputs, credits and output retrieval. No Shopify reconnection is required.

Install Pattern

Use a remote Streamable HTTP MCP configuration when the client supports it:

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

The client discovers Lamina OAuth, opens browser consent, lets the user choose a workspace, and stores a workspace-scoped access token. Do not paste an API key into tool arguments.

add-mcp

For clients supported by the community installer:

npx add-mcp https://app.uselamina.ai/mcp/agent/v2

Add -g for a global install:

npx add-mcp -g https://app.uselamina.ai/mcp/agent/v2

Codex CLI

codex mcp add lamina --url https://app.uselamina.ai/mcp/agent/v2
codex mcp list

Equivalent ~/.codex/config.toml:

[mcp_servers.lamina]
url = "https://app.uselamina.ai/mcp/agent/v2"

Claude Code

claude mcp add --transport http lamina --scope user \
  https://app.uselamina.ai/mcp/agent/v2

Run /mcp in Claude Code to authenticate, then verify with:

claude mcp list
claude mcp get lamina

Cursor

Use .cursor/mcp.json or the global MCP configuration:

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

Refresh MCP servers and complete OAuth when prompted.

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "lamina": {
      "type": "http",
      "url": "https://app.uselamina.ai/mcp/agent/v2"
    }
  }
}

Start or restart the server from the MCP server list, complete OAuth, and enable the Lamina tools in agent mode.

Other Remote MCP Clients

Use the same v2 URL as a custom Streamable HTTP or remote MCP server:

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

Configuration field names vary (url, serverUrl, httpUrl, or endpoint URL), but authentication must use the hosted OAuth flow.

Stdio-Only Clients

If a client can only launch a local process, bridge stdio to Lamina’s hosted server:

npx -y mcp-remote https://app.uselamina.ai/mcp/agent/v2

Example configuration:

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

mcp-remote opens Lamina OAuth in a browser and forwards the hosted tools. Do not add LAMINA_API_KEY for this bridge.

The self-hosted @uselamina/mcp npm package is retired. Connect to the hosted v2 endpoint directly or through mcp-remote.

OAuth Discovery

Each MCP endpoint publishes protected-resource metadata whose resource matches the URL you connect to — as RFC 9728 requires. A spec-correct client verifies that the metadata’s resource equals the server it is protecting and aborts on a mismatch, so v2 and v1 each advertise their own identifier:

# v2 front door (recommended)
GET /.well-known/oauth-protected-resource/mcp/agent/v2   → resource: …/mcp/agent/v2

# v1 advanced endpoint
GET /.well-known/oauth-protected-resource/mcp/agent      → resource: …/mcp/agent

# shared authorization server
GET /.well-known/oauth-authorization-server

Connecting to /mcp/agent/v2 without a token returns a bearer challenge pointing at the v2 metadata:

WWW-Authenticate: Bearer resource_metadata="https://app.uselamina.ai/.well-known/oauth-protected-resource/mcp/agent/v2"

The v2 protected-resource response:

{
  "resource": "https://app.uselamina.ai/mcp/agent/v2",
  "authorization_servers": ["https://app.uselamina.ai"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["lamina:creative:read", "lamina:creative:write", "lamina:brand:read"]
}

Use the resource indicator that matches the endpoint you connect to (/mcp/agent/v2 for the front door). You do not need to re-authorize when migrating v1 → v2: tokens minted for the legacy /mcp/agent resource are cross-accepted at the v2 endpoint, and both endpoints share one authorization server, so an existing grant keeps working.

Authorization Flow

Dynamic clients call POST /mcp/oauth/register with their name and redirect URIs. Public clients use token_endpoint_auth_method: "none".

Start authorization

Open /mcp/oauth/authorize with the standard authorization-code fields, the resource matching the endpoint you connect to (https://app.uselamina.ai/mcp/agent/v2 for the front door), and a PKCE S256 challenge.

Approve a workspace

The user chooses the Lamina workspace and approves the requested scopes.

Exchange the code

POST the code and PKCE verifier to /mcp/oauth/token, again using the same resource.

Call v2

Send MCP requests to /mcp/agent/v2 with Authorization: Bearer <access_token>.

Revoke on disconnect

POST the token to /mcp/oauth/revoke when the user removes Lamina.

Scopes

lamina:creative:read allows credits and run status.
lamina:creative:write allows planning, execution, cancellation, and signed uploads.
lamina:brand:read allows reading brand context.

If a token lacks a tool’s required scope, Lamina returns an insufficient-scope bearer challenge so the client can request step-up authorization.

Verify the Install

Confirm the client lists the task-level tools, including lamina_plan, lamina_execute, lamina_status, and lamina_credits.
Call lamina_credits.
Call lamina_plan with a small test brief.
Confirm planning returns a plan or clarification without dispatching generation.
Display the plan and estimated cost before testing lamina_execute.

Example plan:

{
  "tool": "lamina_plan",
  "arguments": {
    "brief": "Create a cinematic product hero image for a running shoe.",
    "platform": "instagram",
    "modality": "image",
    "maxEstimatedCredits": 80
  }
}

After explicit approval:

{
  "tool": "lamina_execute",
  "arguments": {
    "planId": "<plan-id>",
    "planFingerprint": "<exact-plan-fingerprint>",
    "inputs": {},
    "maxCredits": 80,
    "idempotencyKey": "mcp-install-smoke-test-v1"
  }
}

Poll the returned run:

{
  "tool": "lamina_status",
  "arguments": {
    "runId": "<run-id>",
    "wait": true,
    "timeoutSeconds": 25
  }
}

If status reports timedOut: true or remains non-terminal, call it again with the same run ID. Completed artifacts are returned in normalized outputs[] entries with durable url values.

Revoke Access

POST /mcp/oauth/revoke
Content-Type: application/json

{
  "client_id": "lamina_mcp_client_...",
  "token": "lma_mcp_at_or_rt_...",
  "token_type_hint": "refresh_token"
}

Revoking either token revokes the stored token pair for that grant. A later MCP call with the bearer token returns invalid_token.

Troubleshooting

The client shows 30 tools: it is connected to /mcp/agent; switch normal workflows to /mcp/agent/v2.
The client shows no tools: inspect the OAuth prompt and server logs, then reconnect.
invalid_token: revoke/reconnect and complete OAuth again.
insufficient_scope: reconnect and approve the requested scope.
The client only supports stdio: use mcp-remote with the v2 URL.
Planning works but execution fails: verify the exact fingerprint, required inputs, positive credit ceiling, and idempotency key.

Overview

Install

Concepts

API Reference

Guides

MCP OAuth Install

Recommended Endpoint

Brand MCP apps

Install Pattern

add-mcp

Codex CLI

Claude Code

Cursor

VS Code

Other Remote MCP Clients

Stdio-Only Clients

OAuth Discovery

Authorization Flow

Scopes

Verify the Install

Revoke Access

Troubleshooting

​Recommended Endpoint

​Brand MCP apps

​Install Pattern

​add-mcp

​Codex CLI

​Claude Code

​Cursor

​VS Code

​Other Remote MCP Clients

​Stdio-Only Clients

​OAuth Discovery

​Authorization Flow

​Scopes

​Verify the Install

​Revoke Access

​Troubleshooting

Recommended Endpoint

Brand MCP apps

Install Pattern

add-mcp

Codex CLI

Claude Code

Cursor

VS Code

Other Remote MCP Clients

Stdio-Only Clients

OAuth Discovery

Authorization Flow

Scopes

Verify the Install

Revoke Access

Troubleshooting