> ## 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.

# MCP OAuth Install

> Install Lamina as a hosted remote MCP server with OAuth and workspace-scoped access.

## What This Enables

Hosted MCP lets an AI client connect to Lamina without asking you to paste an API key into tool arguments. The client discovers Lamina's OAuth metadata, sends you to Lamina to approve access for a workspace, receives an access token, and then calls the remote MCP endpoint with `Authorization: Bearer <token>`.

Remote MCP endpoint:

```text theme={null}
https://app.uselamina.ai/mcp/agent
```

Hosted install surface:

```text theme={null}
https://app.uselamina.ai/mcp/install
```

Use the install page when you want copyable endpoint values, OAuth metadata links, and setup
patterns for remote OAuth-capable MCP clients or local stdio fallback clients.

## Install in Popular MCP Clients

Prefer the hosted endpoint whenever the client supports remote Streamable HTTP MCP with OAuth.
Use the local stdio fallback when a client only supports local servers or cannot complete OAuth.

### Supported Clients

The list of popular AI tools that can connect to Lamina MCP:

* [Claude Code](#claude-code)
* [Claude.ai and Claude Desktop](#claudeai-and-claude-desktop)
* [ChatGPT](#chatgpt)
* [Codex CLI](#codex-cli)
* [Cursor](#cursor)
* [VS Code with Copilot](#vs-code-with-copilot)
* [Devin](#devin)
* [Raycast](#raycast)
* [Goose](#goose)
* [Windsurf](#windsurf)
* [Gemini Code Assist](#gemini-code-assist)
* [Gemini CLI](#gemini-cli)
* [Continue](#continue)
* [Cline](#cline)
* [Zed](#zed)

Additional clients can use the same hosted endpoint if they support remote Streamable HTTP MCP with
OAuth, or the local stdio fallback if they only support local MCP servers.

### Quick Compatibility Matrix

| Client                       | Recommended Lamina setup                                                          | Notes                                                                                                          |
| ---------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| ChatGPT                      | Hosted remote MCP                                                                 | Remote MCP only. Full write-tool support depends on plan, workspace settings, and developer mode availability. |
| Codex CLI                    | Hosted remote MCP                                                                 | Works through the Codex MCP CLI/config flow.                                                                   |
| VS Code with Copilot         | Hosted remote MCP                                                                 | Use `type: "http"` in `mcp.json`; VS Code handles authentication-capable MCP servers.                          |
| Claude Code                  | Hosted remote MCP                                                                 | Add HTTP transport, then use `/mcp` to authenticate.                                                           |
| Claude.ai and Claude Desktop | Hosted remote MCP when available; local stdio fallback otherwise                  | Use hosted custom connectors when the Claude plan/client supports them.                                        |
| Cursor                       | Hosted remote MCP                                                                 | Cursor supports Streamable HTTP and OAuth-capable MCP servers.                                                 |
| Windsurf                     | Hosted remote MCP                                                                 | Add a Streamable HTTP server and refresh Cascade tools.                                                        |
| Continue                     | Local stdio fallback first                                                        | Use remote `streamable-http` only if your Continue build can complete OAuth for remote MCP.                    |
| Cline                        | Hosted remote MCP when OAuth is available; local stdio otherwise                  | Cline supports HTTP and stdio MCP configuration.                                                               |
| Zed                          | Hosted remote MCP on recent builds; local stdio fallback                          | Recent Zed builds support OAuth for remote MCP servers.                                                        |
| Devin                        | Hosted remote MCP                                                                 | Add Lamina as a custom HTTP MCP server in Devin's MCP Marketplace.                                             |
| Raycast                      | Hosted remote MCP                                                                 | Add Lamina through Raycast's MCP server install flow.                                                          |
| Goose                        | Hosted remote MCP when OAuth is available; local command-line extension otherwise | Add Lamina as a remote Streamable HTTP extension or a command-line extension.                                  |
| Gemini Code Assist           | Hosted remote MCP through Gemini settings                                         | Use native HTTP support when available or `mcp-remote` fallback.                                               |
| Gemini CLI                   | Hosted remote MCP when OAuth is available; local stdio otherwise                  | Gemini CLI supports HTTP, SSE, and stdio MCP servers.                                                          |

### Setup

Connect your AI client to Lamina MCP and authorize access to your workspace.

#### Install with add-mcp

Install Lamina MCP for supported coding agents with the community `add-mcp` installer:

```bash theme={null}
npx add-mcp https://app.uselamina.ai/mcp/agent
```

Add `-y` to skip confirmation prompts. Add `-g` to install globally across projects:

```bash theme={null}
npx add-mcp -g https://app.uselamina.ai/mcp/agent
```

If `add-mcp` does not detect your client or cannot complete OAuth, use the manual client-specific
instructions below.

#### ChatGPT

ChatGPT custom MCP connectors are remote-only. They are controlled by ChatGPT plan and workspace
settings, and full MCP write actions may require developer mode or workspace admin approval.

1. In ChatGPT, open **Settings**.
2. Open **Apps** or **Connectors**, then enable **Developer mode** if your plan/workspace requires it.
3. Create a custom app/connector for a remote MCP server.
4. Use this server URL:

```text theme={null}
https://app.uselamina.ai/mcp/agent
```

5. Complete Lamina OAuth, choose the workspace, and test with `lamina_discover`.

If ChatGPT reports that the connector is unsupported, verify that the workspace supports full MCP
connectors and write tools. Some ChatGPT connector surfaces are read/fetch-oriented and may not
expose Lamina's creative write tools.

#### Codex CLI

Add Lamina as a remote MCP server:

```bash theme={null}
codex mcp add lamina --url https://app.uselamina.ai/mcp/agent
codex mcp list
```

Codex shares MCP configuration between the CLI and IDE extension. If your Codex build prompts for
browser authentication, complete Lamina OAuth and choose the workspace.

You can also configure the hosted server directly in `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.lamina]
url = "https://app.uselamina.ai/mcp/agent"
```

#### VS Code with Copilot

Create `.vscode/mcp.json` for a workspace install:

```json theme={null}
{
  "servers": {
    "lamina": {
      "type": "http",
      "url": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
```

Then restart the MCP server from the MCP server list or reload VS Code. When prompted, trust the
server and complete OAuth. In Copilot Chat Agent mode, use the tools picker to enable Lamina tools.

For a local fallback, use stdio with an input variable:

```json theme={null}
{
  "inputs": [
    {
      "id": "lamina-api-key",
      "type": "promptString",
      "description": "Lamina API key",
      "password": true
    }
  ],
  "servers": {
    "lamina-local": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent"],
      "env": {
        "LAMINA_API_KEY": "${input:lamina-api-key}"
      }
    }
  }
}
```

#### Devin

Devin supports custom MCP servers through the MCP Marketplace.

1. Open Devin **Settings > MCP Marketplace**.
2. Select **Add Your Own**.
3. Choose **HTTP** as the transport.
4. Set the server URL:

```text theme={null}
https://app.uselamina.ai/mcp/agent
```

5. Save the server, then complete Lamina OAuth when Devin prompts for authorization.

If Devin asks for headers, leave them empty for the hosted OAuth flow. Lamina issues workspace-scoped
tokens after OAuth consent.

#### Raycast

Raycast supports installing MCP servers from its MCP server management commands.

1. Open Raycast and run the MCP **Install Server** command.
2. Enter these details:

```text theme={null}
Name: Lamina
Transport: HTTP
URL: https://app.uselamina.ai/mcp/agent
```

3. Click **Install** and authenticate with Lamina if prompted.

If your Raycast build only supports local stdio MCP servers, use:

```text theme={null}
Name: Lamina
Command: npx
Arguments: -y mcp-remote https://app.uselamina.ai/mcp/agent
Environment: LAMINA_API_KEY=YOUR_LAMINA_API_KEY
```

#### Claude Code

Add the hosted HTTP server:

```bash theme={null}
claude mcp add --transport http lamina --scope user https://app.uselamina.ai/mcp/agent
```

Inside Claude Code, run:

```text theme={null}
/mcp
```

Choose Lamina and authenticate in the browser. Verify the install:

```bash theme={null}
claude mcp list
claude mcp get lamina
```

For local stdio fallback:

```bash theme={null}
claude mcp add --transport stdio lamina-local \
  --env LAMINA_API_KEY=YOUR_LAMINA_API_KEY \
  -- npx -y mcp-remote https://app.uselamina.ai/mcp/agent
```

#### Claude.ai and Claude Desktop

Claude Desktop primarily uses local MCP servers and Desktop Extensions. Until Lamina ships a DXT
package, configure the local stdio package in `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent"],
      "env": {
        "LAMINA_API_KEY": "YOUR_LAMINA_API_KEY"
      }
    }
  }
}
```

Restart Claude Desktop after saving the file. If your Claude client exposes a remote MCP connector
surface, use the hosted endpoint instead:

```text theme={null}
https://app.uselamina.ai/mcp/agent
```

#### Cursor

Create a project config at `.cursor/mcp.json` or a global config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "url": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
```

In Cursor, open MCP settings, refresh servers, and authenticate if prompted. For Cursor CLI:

```bash theme={null}
cursor-agent mcp list
cursor-agent mcp login lamina
cursor-agent mcp list-tools lamina
```

For local stdio fallback:

```json theme={null}
{
  "mcpServers": {
    "lamina-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent"],
      "env": {
        "LAMINA_API_KEY": "YOUR_LAMINA_API_KEY"
      }
    }
  }
}
```

#### Windsurf

In Windsurf, open **Settings > Tools > Windsurf Settings > Add Server**, or edit the raw
`~/.codeium/windsurf/mcp_config.json` file:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "serverUrl": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
```

Use `url` instead of `serverUrl` if your Windsurf build expects that key. Press refresh in Cascade
after adding the server, then authenticate if prompted.

Local fallback:

```json theme={null}
{
  "mcpServers": {
    "lamina-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent"],
      "env": {
        "LAMINA_API_KEY": "YOUR_LAMINA_API_KEY"
      }
    }
  }
}
```

#### Continue

Continue MCP servers run in agent mode. Create `.continue/mcpServers/lamina.yaml`:

```yaml theme={null}
name: Lamina MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: Lamina
    type: streamable-http
    url: https://app.uselamina.ai/mcp/agent
```

Use this hosted config only if your Continue build supports OAuth for remote MCP. Otherwise, use the
local stdio fallback:

```yaml theme={null}
name: Lamina MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: Lamina
    type: stdio
    command: npx
    args:
      - "-y"
      - "mcp-remote"
      - "https://app.uselamina.ai/mcp/agent"
```

Restart Continue and switch to agent mode before testing.

#### Cline

For hosted HTTP MCP:

```bash theme={null}
cline mcp add lamina https://app.uselamina.ai/mcp/agent --type http
```

If your Cline build cannot complete remote OAuth, edit
`~/.cline/data/settings/cline_mcp_settings.json` for local stdio:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent"],
      "env": {
        "LAMINA_API_KEY": "YOUR_LAMINA_API_KEY"
      },
      "disabled": false
    }
  }
}
```

#### Zed

In Zed, open settings and add a custom context server:

```json theme={null}
{
  "context_servers": {
    "lamina": {
      "url": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
```

Recent Zed builds show an authentication action when a remote MCP server requires OAuth. If your
build does not, use the local stdio fallback:

```json theme={null}
{
  "context_servers": {
    "lamina-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/agent"],
      "env": {
        "LAMINA_API_KEY": "YOUR_LAMINA_API_KEY"
      }
    }
  }
}
```

Open the Agent Panel settings and verify the Lamina server status indicator is active.

#### Goose

In Goose Desktop, open **Extensions**, choose **Add custom extension**, and add a **Remote Extension
(Streamable HTTP)**:

```text theme={null}
Name: Lamina
Endpoint URL: https://app.uselamina.ai/mcp/agent
```

In Goose CLI:

```bash theme={null}
goose configure
```

Choose **Add Extension**, then **Remote Extension (Streamable HTTP)**, and enter the Lamina endpoint.
If your Goose build cannot complete OAuth for remote MCP, add a command-line extension instead:

```text theme={null}
Name: Lamina
Command: npx
Arguments: -y mcp-remote https://app.uselamina.ai/mcp/agent
Environment: LAMINA_API_KEY=YOUR_LAMINA_API_KEY
```

#### Gemini Code Assist

Gemini Code Assist shares MCP configuration with Gemini's MCP settings. Use native HTTP support when
your IDE build supports OAuth-capable remote MCP servers:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "httpUrl": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
```

If your build does not complete OAuth for remote HTTP MCP, use `mcp-remote`:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "command": "npx",
      "args": ["mcp-remote", "https://app.uselamina.ai/mcp/agent"]
    }
  }
}
```

Restart the IDE after updating `~/.gemini/settings.json`, then authenticate when prompted.

#### Gemini CLI

For hosted HTTP MCP:

```bash theme={null}
gemini mcp add --transport http --scope user lamina https://app.uselamina.ai/mcp/agent
gemini mcp list
```

You can also configure `~/.gemini/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "lamina": {
      "httpUrl": "https://app.uselamina.ai/mcp/agent"
    }
  }
}
```

If your Gemini CLI build cannot complete OAuth for remote HTTP MCP, use local stdio:

```bash theme={null}
gemini mcp add --scope user \
  --env LAMINA_API_KEY=YOUR_LAMINA_API_KEY \
  lamina-local npx -y mcp-remote https://app.uselamina.ai/mcp/agent
```

Avoid underscores in Gemini MCP server aliases because Gemini's policy engine parses tool names with
underscores.

## OAuth Discovery

Lamina exposes standard MCP OAuth metadata for HTTP clients:

```text theme={null}
GET /.well-known/oauth-protected-resource/mcp/agent
GET /.well-known/oauth-authorization-server
```

The protected-resource response identifies the MCP resource:

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

## Install Flow

<Steps>
  <Step title="Register the MCP client">
    Clients that support dynamic registration call `POST /mcp/oauth/register` with `client_name` and `redirect_uris`. Public clients use `token_endpoint_auth_method: "none"`.
  </Step>

  <Step title="Start authorization">
    The client opens `/mcp/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`, `resource`, `code_challenge`, and `code_challenge_method=S256`.
  </Step>

  <Step title="Approve workspace access">
    Lamina shows a protected consent page. Choose the workspace the agent should use, then approve the requested scopes.
  </Step>

  <Step title="Exchange the code">
    The client posts to `/mcp/oauth/token` with `grant_type=authorization_code`, the authorization `code`, the same `redirect_uri`, `client_id`, `resource`, and the PKCE `code_verifier`.
  </Step>

  <Step title="Call MCP">
    The client calls `/mcp/agent` with `Authorization: Bearer <access_token>`.
  </Step>

  <Step title="Revoke access when removed">
    The client posts to `/mcp/oauth/revoke` with `client_id`, `token`, and optional
    `token_type_hint` when the user disconnects Lamina.
  </Step>
</Steps>

## Scopes

* `lamina:creative:read` allows discovery and run status.
* `lamina:creative:write` allows creating and batching creative runs.
* `lamina:brand:read` allows reading brand memory and guidance.

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

## Revoke Access

OAuth clients should revoke tokens when a user removes Lamina or rotates client state:

```http theme={null}
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 an access token or refresh token revokes the token pair stored for that grant. A
later call to `/mcp/agent` with that bearer token returns `invalid_token`.

## First Creative Run

After install, the agent runs through discover → describe → run → poll.

Find an app for the user's goal:

```json theme={null}
{
  "tool": "lamina_discover",
  "arguments": {
    "keywords": ["product", "hero", "running shoe", "cinematic"]
  }
}
```

Read the chosen app's parameter contract:

```json theme={null}
{
  "tool": "lamina_describe",
  "arguments": {
    "appId": "<appId-from-discover>"
  }
}
```

Dispatch the run with the required inputs (keyed by parameter `key` from `lamina_describe`):

```json theme={null}
{
  "tool": "lamina_run",
  "arguments": {
    "appId": "<appId-from-describe>",
    "inputs": {
      "<param-key>": "<value>"
    }
  }
}
```

`lamina_run` returns immediately with `{ runId, workflowId, status }`. Poll for completion:

```json theme={null}
{
  "tool": "lamina_status",
  "arguments": {
    "runId": "<runId-from-run>",
    "wait": true
  }
}
```

<Note>
  `lamina_run` is a pure trigger — you pass an `appId` you already have. If you'd rather hand Lamina a free-text brief and let it pick the app for you, call `lamina_create` instead; it returns a plan (with the selected app), which you then dispatch with `lamina_run`.
</Note>

## Stdio-only Clients

If your MCP client can only launch a local stdio command and cannot connect to a remote OAuth MCP server directly, bridge to the hosted server with `mcp-remote` — it runs locally and handles the OAuth flow to Lamina's hosted endpoint:

```bash theme={null}
npx -y mcp-remote https://app.uselamina.ai/mcp/agent
```

No API key to paste — `mcp-remote` opens the OAuth approval in your browser and forwards the hosted tools over stdio.

<Note>
  The old self-hosted `@uselamina/mcp` npm package is retired. Always connect to the hosted MCP (`https://app.uselamina.ai/mcp/agent`), directly for OAuth-capable clients or via `mcp-remote` for stdio-only ones.
</Note>