MCP OAuth Install

Recommended Endpoint

Connect normal agent workflows to:

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

It exposes seven 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

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 seven 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 exactly: lamina_plan, lamina_execute, lamina_status, lamina_cancel, lamina_upload_asset, lamina_brand_context, 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

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

​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

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