> ## Documentation Index > Fetch the complete documentation index at: https://docs.layer.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP server > Use Layer's AI models directly from Claude and other MCP-compatible clients Layer provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets you generate images, 3D assets, video, and audio directly from AI conversations — no code required. ## Connect to Layer Connect using your Layer account — recommended for most agents. The simplest way is to add Layer as a **custom connector** through the UI — no config files or Node.js required. * **Pro / Max (single seat):** Open **Settings > Connectors**, click **+ Add custom connector**, enter `https://mcp.app.layer.ai/mcp`, and click **Add**. * **Team / Enterprise:** Only an Owner can add a connector for the organization, via **Organization settings > Connectors > Add > Custom > Web**. Members then authenticate individually under **Settings > Connectors**. OAuth triggers on first use — log in with your Layer account when prompted. Custom connectors are currently in beta. The connection runs from Anthropic's cloud, not your machine, so Layer must be reachable over the public internet (it is by default). If your version doesn't support custom connectors, add Layer as a local server via `mcp-remote` (requires Node.js): 1. Open **Settings > Developer > MCP Servers**. 2. Add this config: ```json theme={null} { "mcpServers": { "Layer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.app.layer.ai/mcp" ] } } } ``` 3. `mcp-remote` is installed automatically via npx. 1. Open your terminal to access the CLI. 2. Run this command: ```bash theme={null} claude mcp add --transport http Layer https://mcp.app.layer.ai/mcp ``` 3. Launch Claude Code and run `/mcp` to open the MCP management panel. 4. Select **Layer** and choose **Authenticate** — log in with your Layer account in the browser window that opens. If this fails with a transport error, try `--transport sse` instead — the correct flag depends on your Claude Code version. 1. Open your terminal to access the CLI. 2. Run this command: ```bash theme={null} codex mcp add layer -- npx -y mcp-remote@latest https://mcp.app.layer.ai/mcp ``` 3. Or add to `~/.codex/config.toml` manually. 4. OAuth triggers on first use. Manus does not have a built-in OAuth flow. We recommend using the **API Key** tab above for the most reliable Manus setup. Install with Cursor Or manually: 1. Open Cursor Settings (**Cmd + ,**) and navigate to **Features > MCP** 2. Click **+ Add New MCP Server**, select **Streamable HTTP** 3. Enter **Name:** `Layer` and **URL:** `https://mcp.app.layer.ai/mcp` 4. OAuth triggers automatically — log in with your Layer account when prompted ### Step 1 — Add the Layer MCP server Open the Command Palette (**Cmd + Shift + P**), search for **MCP: Add Server**, and select **HTTP**. Or add to `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "mcpServers": { "Layer": { "serverUrl": "https://mcp.app.layer.ai/mcp" } } } ``` ### Step 2 — Authenticate The OAuth flow will trigger automatically — log in with your Layer account when prompted. ### Step 3 — Verify it works Ask: *"What can I do with Layer?"* 1. Open your terminal to access the CLI. 2. Run this command: ```bash theme={null} gemini mcp add --transport http Layer https://mcp.app.layer.ai/mcp ``` 3. Or add to `~/.gemini/settings.json` manually. 4. OAuth triggers on first use. Install with VS Code Or manually add to `.vscode/mcp.json`: ```json theme={null} { "servers": { "Layer": { "type": "http", "url": "https://mcp.app.layer.ai/mcp" } } } ``` OAuth triggers on first use — log in with your Layer account when prompted. 1. Open your terminal to access the CLI. 2. Run this command: ```bash theme={null} amp mcp add layer https://mcp.app.layer.ai/mcp ``` 3. OAuth authentication via Dynamic Client Registration. Edit `~/.config/opencode/opencode.json`: ```json theme={null} { "mcp": { "Layer": { "type": "remote", "url": "https://mcp.app.layer.ai/mcp" } } } ``` OAuth triggers automatically on first use — log in with your Layer account when prompted. 1. Open **Settings > AI > Manage MCP servers > + Add > CLI Server**. 2. Enter this command: ```bash theme={null} npx -y mcp-remote@latest https://mcp.app.layer.ai/mcp ``` 3. OAuth triggers on first use. Zed only supports stdio transport. Use `mcp-remote` as a bridge. Add to `~/.config/zed/settings.json`: ```json theme={null} { "context_servers": { "Layer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.app.layer.ai/mcp" ] } } } ``` OAuth triggers automatically on first use — log in with your Layer account when prompted. Connect using a Personal Access Token (PAT) — works with any MCP client. First, generate a PAT in Layer: go to [**User Settings > New Token**](https://app.layer.ai/settings) and copy the token (starts with `pat_`). 1. Open **Settings > Developer > MCP Servers**. 2. Add this config (replace `YOUR_PAT` with your token): ```json theme={null} { "mcpServers": { "Layer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.app.layer.ai/mcp", "--header", "Authorization: Bearer YOUR_PAT" ] } } } ``` 3. Requires Node.js. `mcp-remote` is installed automatically via npx. 1. Open your terminal to access the CLI. 2. Run this command, replacing `YOUR_PAT` with your token: ```bash theme={null} claude mcp add --transport http Layer https://mcp.app.layer.ai/mcp --header "Authorization: Bearer YOUR_PAT" ``` 3. Verify by asking: *"What can I do with Layer?"* 1. Open your terminal to access the CLI. 2. Replace `YOUR_PAT` with your token, then run: ```bash theme={null} codex mcp add layer -- npx -y mcp-remote@latest https://mcp.app.layer.ai/mcp \ --header "Authorization: Bearer YOUR_PAT" ``` 3. Verify by asking: *"What can I do with Layer?"* ### Step 1 — Add the Layer connector In Manus, go to **Personalization > Connectors**, click **Add connector**, then select **Custom MCP > Import by JSON** and paste: ```json theme={null} { "mcpServers": { "Layer": { "type": "streamableHttp", "url": "https://mcp.app.layer.ai/mcp", "headers": { "Authorization": "Bearer YOUR_PAT" } } } } ``` Replace `YOUR_PAT` with your token and click **Save**. ### Step 2 — Verify it works Click the **Try it out** button — Manus will open a prompt to test the connection and show you Layer's capabilities. ### Step 1 — Add the Layer MCP server Add to `.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "Layer": { "url": "https://mcp.app.layer.ai/mcp", "headers": { "Authorization": "Bearer YOUR_PAT" } } } } ``` Replace `YOUR_PAT` with your token. ### Step 2 — Verify it works Ask: *"What can I do with Layer?"* ### Step 1 — Add the Layer MCP server Add to `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "mcpServers": { "Layer": { "serverUrl": "https://mcp.app.layer.ai/mcp", "headers": { "Authorization": "Bearer YOUR_PAT" } } } } ``` Replace `YOUR_PAT` with your token. ### Step 2 — Verify it works Ask: *"What can I do with Layer?"* 1. Open your terminal to access the CLI. 2. Run this command, replacing `YOUR_PAT` with your token: ```bash theme={null} gemini mcp add --transport http --header "Authorization: Bearer YOUR_PAT" Layer https://mcp.app.layer.ai/mcp ``` 3. Or add to `~/.gemini/settings.json` manually with the `Authorization` header. 4. Verify by asking: *"What can I do with Layer?"* ### Step 1 — Add the Layer MCP server Add to `.vscode/mcp.json`: ```json theme={null} { "servers": { "Layer": { "type": "http", "url": "https://mcp.app.layer.ai/mcp", "headers": { "Authorization": "Bearer YOUR_PAT" } } } } ``` Replace `YOUR_PAT` with your token. ### Step 2 — Verify it works Ask: *"What can I do with Layer?"* Amp handles authentication internally via Dynamic Client Registration. API key authentication is not supported for Amp. Edit `~/.config/opencode/opencode.json`: ```json theme={null} { "mcp": { "Layer": { "type": "remote", "url": "https://mcp.app.layer.ai/mcp", "headers": { "Authorization": "Bearer YOUR_PAT" } } } } ``` Replace `YOUR_PAT` with your token. Warp handles authentication through its Settings UI. API key authentication is not directly supported. Use the OAuth flow instead. ### Step 1 — Add the Layer MCP server Add to `~/.config/zed/settings.json`: ```json theme={null} { "context_servers": { "Layer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.app.layer.ai/mcp", "--header", "Authorization: Bearer YOUR_PAT" ] } } } ``` Replace `YOUR_PAT` with your token. ### Step 2 — Verify it works Ask: *"What can I do with Layer?"* ## Available tools The MCP server exposes the following tools. Your AI agent selects and calls them automatically based on your prompts. ### Instructions | Tool | Description | | --------------------------- | ------------------------------------------------------------------------------- | | `get_instructions` | Returns platform guidance, Creative Unit pricing info, and error codes | | `get_workflow_instructions` | Returns the full workflow lifecycle: discover, estimate, execute, poll, display | | `get_forge_instructions` | Returns the forge (direct model execution) lifecycle | These are called automatically to understand how to use the platform. You don't need to invoke them directly. ### Workspaces | Tool | Description | | ----------------- | ------------------------------------------------------------------------- | | `list_workspaces` | List the workspaces you belong to (id, slug, name, and last activity) | | `get_workspace` | Get details for a specific workspace, including its Creative Unit balance | ### Models | Tool | Description | | --------------------------- | --------------------------------------------------------------------- | | `get_model_recommendations` | Get curated model recommendations by category | | `list_models` | Search and filter models by modality, capabilities, or text query | | `get_model` | Get full details for a model including capabilities and prompt format | Models can be filtered by modality (`image`, `video`, `three_d`, `audio`) and by capabilities like `inpainting`, `style_reference`, `text_to_3d`, `lipsync`, and more. ### Workflows Workflows are multi-step pipelines built in the Layer app's Blueprint editor. | Tool | Description | | ------------------------- | ------------------------------------------------------ | | `list_workflows` | List available workflows with their inputs and outputs | | `estimate_workflow_price` | Check the Creative Unit cost before running | | `execute_workflow` | Run a workflow (async — returns a `run_id`) | | `get_workflow_run` | Poll for workflow run status and results | | `cancel_workflow_run` | Cancel a running workflow and release reserved CUs | ### Forge (direct model execution) Forge runs a single model directly, giving you full control over parameters. | Tool | Description | | ---------------------- | ------------------------------------------------------------ | | `estimate_forge_price` | Check the Creative Unit cost for a generation | | `execute_forge` | Run inference on a model (async — returns an `inference_id`) | | `get_forge_run` | Poll for forge run status and generated assets | Forge supports the full range of generation parameters: prompts, dimensions, batch size, guidance files (reference images, masks, poses, depth maps), video effects, 3D options, audio settings, and post-processing (upscale, vectorize, remove background). ### Files | Tool | Description | | ------------------------- | ---------------------------------------------------------------------- | | `request_file_upload_url` | Get a signed upload URL for a local file (image, video, or audio) | | `upload_file` | Upload a file from a public URL for use as input in workflows or forge | `request_file_upload_url` supports PNG, JPEG, WebP (up to 100 MB), MP4 (up to 5 GB), and WAV/MP3 (up to 64 MB). `upload_file` supports PNG, JPEG, WebP, and MP4 (up to 64 MB). `request_file_upload_url` is available in Claude Code CLI and similar clients. It does not work in Claude.ai or Claude Desktop due to URL allowlisting restrictions. ## Example prompts Once connected, try prompts like: * *"Generate 4 variations of a crystal sword icon on a transparent background"* * *"Show me what image models are available for my workspace"* * *"Create a 3D model of a treasure chest from this reference image"* * *"Run the product shot workflow with a photo of my item"* * *"How many Creative Units do I have left?"* Your AI agent will pick the right tools, estimate costs, run the generation, and show you the results. ## Error codes | Code | Status | Meaning | | ---------------------- | ------ | ---------------------------------------------------------------------- | | `UNAUTHENTICATED` | 401 | OAuth connection not completed — reconnect in your Connectors settings | | `FORBIDDEN` | 403 | You don't have permission for this action | | `INSUFFICIENT_BALANCE` | 402 | Not enough Creative Units — top up in **Settings > Billing** | | `RATE_LIMITED` | 429 | Max 5 concurrent runs per user per workspace | | `WORKSPACE_NOT_FOUND` | 404 | Workspace doesn't exist or you're not a member | | `MODEL_NOT_FOUND` | 404 | Model not found or not available in this workspace | | `WORKFLOW_NOT_FOUND` | 404 | Workflow not found or not linked to this workspace | | `RUN_NOT_FOUND` | 404 | Workflow or forge run doesn't exist | | `INVALID_INPUTS` | 400 | Malformed parameters or UUIDs | | `UPLOAD_FAILED` | 400 | File could not be downloaded or stored | ## Troubleshooting **Layer doesn't appear in my Connectors list (Claude)** On a personal **Pro / Max** account, add it yourself under **Settings > Connectors > + Add custom connector**. On **Team / Enterprise**, an Owner must add it org-wide first (**Organization settings > Connectors**) — after that, authenticate it individually under **Settings > Connectors**. **Authorization fails or times out** Make sure you have an active Layer account at [layer.ai](https://www.layer.ai). If you're behind a VPN or corporate firewall, the OAuth redirect may be blocked — try on a direct connection. **Agent doesn't seem to use Layer tools** Start a new conversation after connecting — existing conversations may not pick up new MCP servers. Check that the connector status shows as connected. **Claude Code: "unknown transport" error** Try `--transport sse` instead of `--transport http` — the correct flag depends on your Claude Code version. **Codex: MCP server not loading** Make sure `mcp-remote` is installed correctly. Try running `npx -y mcp-remote@latest` to verify. If using API Key, ensure the `LAYER_PAT` environment variable is set in your shell profile and you've restarted Codex. **Cursor / VS Code / Windsurf: connection fails** Verify the MCP server URL is exactly `https://mcp.app.layer.ai/mcp`. If using API Key, check that the `Authorization` header value starts with `Bearer ` (with a space) followed by your token. **Manus: tools not working** Verify that your Personal Access Token is valid and the `Authorization` header value starts with `Bearer ` (with a space) followed by your token. Make sure the transport type is `streamableHttp` in the JSON config. **Gemini CLI: authentication error** If using API Key, ensure the header flag is formatted correctly: `--header "Authorization: Bearer YOUR_PAT"`. If using OAuth, the flow should trigger automatically on first tool use.