# Arcweave MCP server

> For the complete documentation index, see [llms.txt](https://docs.arcweave.com/llms.txt). All pages are also available in one file, [llms-full.txt](https://docs.arcweave.com/llms-full.txt).

Source: https://docs.arcweave.com/integrations/mcp
Section: Integrations
Description: Connect Arcweave to Claude, Codex, Cursor, Copilot, OpenCode, Antigravity, Muse Code, and other AI assistants with the Arcweave MCP server

The Arcweave **Model Context Protocol (MCP)** server lets an AI assistant work with your Arcweave projects. You can ask it to summarize a story, inspect branching logic, create elements and connections, manage components and assets, or export a project for your game engine.

Arcweave hosts the server. To connect, create a workspace API key and add the server to your AI app using the instructions below.

## Before you connect

Context: Arcweave docs > Integrations > Arcweave MCP server > Before you connect

You need a **Team workspace**, the **Create API key** workspace permission, and an MCP client that supports **Streamable HTTP** with an `Authorization` header. Your AI app may also require its own subscription or administrator approval for custom MCP servers.

1. Open your Arcweave workspace's **API** section.
2. Click **Create new key** and give it a recognizable name, such as `Claude — story review`.
3. Select **Read projects** to let the assistant inspect project data. Also select **Write projects** if you want it to create, edit, or delete content, including entire projects. Write permission alone does not include read access.
4. Click **Create**, then click **Copy** in the **Copy your new key** dialog and paste the key into your client's settings or a password manager. The full key is shown only once; if you lose it, create a new key.

The key acts as the member who created it, within that workspace. If that member leaves or is removed from the workspace, the key is deleted and your client stops working until you add a new key. It cannot access projects or perform actions that member cannot access. See [Workspace API](https://docs.arcweave.com/workspaces/api) for key management and [REST API permissions](https://docs.arcweave.com/rest-api/overview#permissions) for the underlying access rules.

**Tip: Start with read access**
A key with **Read projects** is enough to connect and try the first example. Enable **Write projects** when you are ready to let the assistant change your project. Keep the client's tool approval prompts enabled so you can review proposed changes.

### Connection details

Context: Arcweave docs > Integrations > Arcweave MCP server > Before you connect > Connection details

| Setting        | Value                                        |
| -------------- | -------------------------------------------- |
| Server name    | `arcweave`                                   |
| Server URL     | `https://arcweave.com/mcp`                   |
| Transport      | **Streamable HTTP** (often labeled **HTTP**) |
| Authentication | Workspace API key sent as a bearer token     |
| Header name    | `Authorization`                              |
| Header value   | `Bearer YOUR_API_KEY`                        |

Replace `YOUR_API_KEY` with the key you copied. Include the word `Bearer` followed by one space when setting the header. A dedicated bearer-token field expects only the key.

Arcweave's MCP server currently uses API keys, not OAuth. You do not need an OAuth client ID, client secret, or browser sign-in. Use the `/mcp` URL exactly; `/api/v1` is the REST API, and `/sse` is not the MCP endpoint.

Keep keys in your client's private settings or environment. Do not paste them into chat messages, screenshots, or files committed to source control. When adding a JSON example to an existing configuration, merge the `arcweave` entry into the existing server object instead of replacing your other settings.

### Environment variables for local clients

Context: Arcweave docs > Integrations > Arcweave MCP server > Before you connect > Environment variables for local clients

Some examples reference an `ARCWEAVE_API_KEY` environment variable. Set it before launching the client from that terminal:

```bash title="Bash"
read -rsp 'Arcweave API key: ' ARCWEAVE_API_KEY
printf '\n'
export ARCWEAVE_API_KEY
```

```powershell title="PowerShell 7.1+"
$env:ARCWEAVE_API_KEY = Read-Host 'Arcweave API key' -MaskInput
```

These commands set the key for the current terminal session. Set it again in a new terminal. Desktop apps opened from a dock or Start menu may not inherit it: fully quit the app and launch it from the configured terminal, or use its private credential settings. For SSH, containers, or remote development, set the variable in the environment where the MCP client runs.

## Choose your client

Context: Arcweave docs > Integrations > Arcweave MCP server > Choose your client

| Client                                    | Setup                                                    |
| ----------------------------------------- | -------------------------------------------------------- |
| Claude Code                               | [Claude Code](https://docs.arcweave.com/integrations/mcp#claude-code)                              |
| Codex CLI, desktop app, and IDE extension | [Codex](https://docs.arcweave.com/integrations/mcp#codex)                                          |
| Cursor                                    | [Cursor](https://docs.arcweave.com/integrations/mcp#cursor)                                        |
| Visual Studio Code with GitHub Copilot    | [VS Code](https://docs.arcweave.com/integrations/mcp#vs-code-with-github-copilot)                  |
| GitHub Copilot CLI                        | [Copilot CLI](https://docs.arcweave.com/integrations/mcp#github-copilot-cli)                       |
| OpenCode                                  | [OpenCode](https://docs.arcweave.com/integrations/mcp#opencode)                                    |
| Google Antigravity                        | [Antigravity](https://docs.arcweave.com/integrations/mcp#google-antigravity)                       |
| Muse Code                                 | [Muse Code](https://docs.arcweave.com/integrations/mcp#muse-code)                                  |
| Gemini CLI                                | [Gemini CLI](https://docs.arcweave.com/integrations/mcp#gemini-cli)                                |
| Claude web and Desktop                    | [Claude](https://docs.arcweave.com/integrations/mcp#claude-web-and-desktop)                        |
| Windsurf / Devin Desktop (Cascade)        | [Windsurf](https://docs.arcweave.com/integrations/mcp#windsurf-cascade)                            |
| Cline                                     | [Cline](https://docs.arcweave.com/integrations/mcp#cline)                                          |
| ChatGPT                                   | [ChatGPT compatibility](https://docs.arcweave.com/integrations/mcp#chatgpt)                        |
| Zed, Kiro, and other clients              | [Other MCP clients](https://docs.arcweave.com/integrations/mcp#other-mcp-clients)                  |
| Clients that only support local servers   | [Local bridge](https://docs.arcweave.com/integrations/mcp#clients-that-only-support-local-servers) |

## Claude Code

Context: Arcweave docs > Integrations > Arcweave MCP server > Claude Code

After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), run this in Bash:

```bash
claude mcp add --transport http --scope user \
  arcweave https://arcweave.com/mcp \
  --header 'Authorization: Bearer ${ARCWEAVE_API_KEY}'
claude
```

The single quotes preserve `${ARCWEAVE_API_KEY}` in the saved configuration; Claude Code expands it when connecting. User scope makes the server available across your projects. In PowerShell, use the command on one line and keep the single quotes.

For a project-specific setup, add this to `.mcp.json` at the project root instead:

```json
{
  "mcpServers": {
    "arcweave": {
      "type": "http",
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ARCWEAVE_API_KEY}"
      }
    }
  }
}
```

Start Claude Code, approve the project MCP configuration if prompted, and use `/mcp` to check that `arcweave` connects. You can also run `claude mcp list` from your terminal. No OAuth login is required.

See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).

## Codex

Context: Arcweave docs > Integrations > Arcweave MCP server > Codex

After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), run:

```bash
codex mcp add arcweave \
  --url https://arcweave.com/mcp \
  --bearer-token-env-var ARCWEAVE_API_KEY
codex
```

In PowerShell, run the `codex mcp add` command on one line without the backslashes.

Alternatively, add this to `~/.codex/config.toml`:

```toml
[mcp_servers.arcweave]
url = "https://arcweave.com/mcp"
bearer_token_env_var = "ARCWEAVE_API_KEY"
```

The CLI, desktop app, and IDE extension share MCP configuration on the same Codex host. Restart the client after changing it, and make sure that client can read `ARCWEAVE_API_KEY`. In an app's MCP settings, the equivalent setup is a Streamable HTTP server with the URL above and the bearer token or `Authorization` header.

Run `codex mcp list` to check the saved configuration, then use `/mcp` in a Codex session to check the connection. Do not run `codex mcp login arcweave`; that command is for OAuth servers.

See the [official Codex MCP guide](https://developers.openai.com/codex/mcp/).

## Cursor

Context: Arcweave docs > Integrations > Arcweave MCP server > Cursor

Add this to your user configuration at `~/.cursor/mcp.json`, or to `.cursor/mcp.json` for a single project:

```json
{
  "mcpServers": {
    "arcweave": {
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ARCWEAVE_API_KEY}"
      }
    }
  }
}
```

Make sure Cursor inherits the [environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), then restart it. Check that Arcweave is enabled in Cursor's MCP settings and use **Agent** to try a tool call.

See the [official Cursor MCP guide](https://cursor.com/docs/mcp).

## VS Code with GitHub Copilot

Context: Arcweave docs > Integrations > Arcweave MCP server > VS Code with GitHub Copilot

1. Open the Command Palette and run **MCP: Add Server**.
2. Choose **HTTP**, enter `https://arcweave.com/mcp`, and name the server `arcweave`.
3. Choose **Copilot Global** to save the configuration for your user. Open the resulting `~/.copilot/mcp-config.json` file, or the equivalent under your configured `COPILOT_HOME`.
4. Add the authentication header so the entry looks like this:

```json
{
  "mcpServers": {
    "arcweave": {
      "type": "http",
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "tools": ["*"]
    }
  }
}
```

Replace `YOUR_API_KEY` in this private user file. Save it, restart the server from **MCP: List Servers**, and enable Arcweave in the chat tool picker. Use an agent session to try the [connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). This portable configuration also works with Copilot CLI.

### VS Code user-profile configuration

Context: Arcweave docs > Integrations > Arcweave MCP server > VS Code with GitHub Copilot > VS Code user-profile configuration

If your VS Code version does not offer **Copilot Global**, run **MCP: Open User Configuration** and use this format instead. VS Code asks for the key through a password input and stores it securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "arcweave-api-key",
      "description": "Arcweave workspace API key",
      "password": true
    }
  ],
  "servers": {
    "arcweave": {
      "type": "http",
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:arcweave-api-key}"
      }
    }
  }
}
```

This format uses `servers`, not `mcpServers`. It is intended for VS Code's local extension-host sessions: servers that require interactive input are not forwarded to Agent Host sessions. Use the portable configuration above for those sessions.

See the [VS Code MCP guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers) and [configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

## GitHub Copilot CLI

Context: Arcweave docs > Integrations > Arcweave MCP server > GitHub Copilot CLI

You can use the portable configuration in the [VS Code instructions](https://docs.arcweave.com/integrations/mcp#vs-code-with-github-copilot), or configure the server interactively:

1. Start `copilot` and enter `/mcp add`.
2. Set **Server Name** to `arcweave` and **Server Type** to **HTTP**.
3. Set **URL** to `https://arcweave.com/mcp`.
4. In **HTTP Headers**, enter `{"Authorization":"Bearer YOUR_API_KEY"}`, replacing the placeholder with your key.
5. Leave **Tools** as `*` to make the server's tools available, then press **Ctrl+S** to save.

The server is available immediately. Use `/mcp` to inspect it, then try the [connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). The key is saved in your private Copilot user configuration; do not copy that file into a repository.

See the [official Copilot CLI MCP guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).

## OpenCode

Context: Arcweave docs > Integrations > Arcweave MCP server > OpenCode

After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), add this to your project's `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arcweave": {
      "type": "remote",
      "url": "https://arcweave.com/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:ARCWEAVE_API_KEY}"
      }
    }
  }
}
```

OpenCode uses `mcp`, `type: "remote"`, and `{env:VARIABLE}` syntax. Setting `oauth` to `false` prevents it from attempting an OAuth flow for this API-key server.

Run `opencode mcp list` to check the connection, then launch `opencode` from the same terminal.

See the [official OpenCode MCP guide](https://opencode.ai/docs/mcp-servers/).

## Google Antigravity

Context: Arcweave docs > Integrations > Arcweave MCP server > Google Antigravity

In the IDE's agent side panel, open **… → MCP Servers → Manage MCP Servers → View raw config**. Add this to the global `mcp_config.json` shown by the app, replacing `YOUR_API_KEY`:

```json
{
  "mcpServers": {
    "arcweave": {
      "serverUrl": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Antigravity requires **`serverUrl`** for a remote server. Save the configuration and refresh the MCP server list, then try the [connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). In Antigravity CLI, the global file is `~/.gemini/config/mcp_config.json`; use `/mcp` to reload it and inspect the connection.

See the [official Antigravity MCP guide](https://antigravity.google/docs/mcp).

## Muse Code

Context: Arcweave docs > Integrations > Arcweave MCP server > Muse Code

After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), add this to your user settings at `~/.config/muse/settings.json`:

```json
{
  "schema_version": 1,
  "mcp_servers": {
    "arcweave": {
      "transport": "streamable_http",
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ARCWEAVE_API_KEY}"
      },
      "mode": "optional"
    }
  }
}
```

The settings file must contain `"schema_version": 1`; if the file already exists, add only the `arcweave` entry to its `mcp_servers` block. Muse Code expands `${ARCWEAVE_API_KEY}` when connecting, so the key stays out of the file. With `mode` set to `optional`, Muse Code starts with a warning if Arcweave is unreachable; the default, `required`, stops the run instead.

Launch `muse` from the same terminal and run `/mcp` to check that `arcweave` connects and lists its tools. Do not run `muse mcp login arcweave`; that command is for OAuth servers.

See the [official Muse Code extension guide](https://dev.meta.ai/docs/muse-code/extending) and [settings reference](https://dev.meta.ai/docs/muse-code/configuration#settings-file).

## Gemini CLI

Context: Arcweave docs > Integrations > Arcweave MCP server > Gemini CLI

Add this to your private user settings at `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "arcweave": {
      "httpUrl": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` in that private file. Gemini CLI uses **`httpUrl`** for Streamable HTTP; `url` selects the legacy SSE transport.

Restart Gemini CLI, then use `/mcp` to inspect the connection and tools. You can also run `gemini mcp list` from the terminal. Leave tool confirmations enabled.

See the [official Gemini CLI MCP guide](https://geminicli.com/docs/tools/mcp-server/).

## Claude web and Desktop

Context: Arcweave docs > Integrations > Arcweave MCP server > Claude web and Desktop

Use a **custom connector** with a request header. Claude connects to Arcweave from Anthropic's servers, so a custom connector works in Claude on the web as well as in Desktop. Availability depends on your Claude plan; Team and Enterprise connectors may need to be added by an organization owner.

1. Open **Customize → Connectors**. For an organization-wide connector, the owner uses **Organization settings → Connectors**.
2. Select **Add → Add custom connector**.
3. Name it `Arcweave` and enter `https://arcweave.com/mcp` as the remote MCP server URL.
4. Continue to the authentication settings. Choose **No sign in**, since Arcweave uses a fixed API key rather than OAuth.
5. Under **Request headers**, add `Authorization` with the value `Bearer YOUR_API_KEY`, replacing the placeholder with your key.
6. Save the connector. In a conversation, open **+ → Connectors**, enable Arcweave, and try the [first connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection).

**No sign in** only disables the OAuth flow; the request header still authenticates every request to Arcweave. For a Team or Enterprise connector, everyone using that connector accesses Arcweave through the same configured key. Choose a key whose access is appropriate for those members.

If your Desktop version does not offer custom request headers, use the [local bridge](https://docs.arcweave.com/integrations/mcp#clients-that-only-support-local-servers) below. It runs on your computer and is not a workaround for Claude web or mobile.

See Claude's [custom connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## Windsurf / Devin Desktop (Cascade)

Context: Arcweave docs > Integrations > Arcweave MCP server > Windsurf / Devin Desktop (Cascade)

Open Cascade's MCP configuration from its MCP settings or **… → Open MCP config file**. Add this entry to `mcp_config.json`:

```json
{
  "mcpServers": {
    "arcweave": {
      "serverUrl": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ARCWEAVE_API_KEY}"
      }
    }
  }
}
```

Make sure the app inherits the [environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), then reload the MCP configuration or restart the app. Enable the Arcweave tools you want to use. If the client reaches its enabled-tool limit, select a smaller set of Arcweave tools and disable unused tools from other servers.

Windsurf's documentation now redirects to **Devin Desktop**, which uses the same Cascade configuration with the `serverUrl` and `headers` fields. Open the configuration through the app to find the correct file for your installed version.

See the [Cascade MCP guide](https://docs.devin.ai/desktop/cascade/mcp).

## Cline

Context: Arcweave docs > Integrations > Arcweave MCP server > Cline

In the Cline extension, open **MCP Servers → Configure → Configure MCP Servers**. For Cline CLI, edit `~/.cline/mcp.json` or use the `cline mcp` wizard.

Add the following to the client's private MCP settings, replacing `YOUR_API_KEY`:

```json
{
  "mcpServers": {
    "arcweave": {
      "type": "streamableHttp",
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Save the file and check the Arcweave server's connection and tools in Cline's MCP panel. Cline's transport spelling is **`streamableHttp`**; omitting it can select legacy SSE. The empty `autoApprove` list keeps tool approvals under your control.

See the [official Cline MCP guide](https://docs.cline.bot/mcp/mcp-overview).

## ChatGPT

Context: Arcweave docs > Integrations > Arcweave MCP server > ChatGPT

**ChatGPT web's developer-mode apps do not currently offer the fixed bearer-token authentication this server requires.** They support OAuth, no authentication, or a mix of both, and cannot send a custom API key. Adding the Arcweave URL with **No Authentication** will not connect, because Arcweave requires a workspace API key even for tool discovery.

Use one of the clients above for direct access. If you use the ChatGPT desktop app's local Codex-host MCP support, follow the [Codex configuration](https://docs.arcweave.com/integrations/mcp#codex): its local MCP configuration supports bearer tokens. A local configuration does not automatically make the server available in ChatGPT web or mobile.

See OpenAI's [ChatGPT authentication documentation](https://developers.openai.com/plugins/build/auth) and [local MCP configuration](https://developers.openai.com/codex/mcp/).

## Other MCP clients

Context: Arcweave docs > Integrations > Arcweave MCP server > Other MCP clients

If your client supports remote servers with custom headers, add a server using the [connection details](https://docs.arcweave.com/integrations/mcp#connection-details). Select **Streamable HTTP**, enter the server URL, and configure the `Authorization` header. Many clients accept this shape in their private user configuration:

```json
{
  "mcpServers": {
    "arcweave": {
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Field names differ between clients, so check each client's own configuration format. For example:

| Client | Where to configure                                                                  | Differences                                                                                                |
| ------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Zed    | **Settings → AI → MCP Servers → Add Remote Server**, or **zed: open settings file** | Use `context_servers` instead of `mcpServers`. Check for a green **Server is active** indicator.           |
| Kiro   | **Kiro: Open user MCP config (JSON)**, which opens `~/.kiro/settings/mcp.json`      | Uses the shape above. Enable MCP support in Kiro's settings if it is disabled; saving the file reconnects. |

See the [Zed MCP guide](https://zed.dev/docs/ai/mcp) and [Kiro MCP configuration guide](https://kiro.dev/docs/mcp/configuration/).

Web apps that connect to MCP servers from their own servers, such as [Claude's custom connectors](https://docs.arcweave.com/integrations/mcp#claude-web-and-desktop), work like desktop clients as long as they can send the `Authorization` header. Clients that call the server directly from a browser tab are rejected unless Arcweave allows their origin; see [Troubleshooting](https://docs.arcweave.com/integrations/mcp#troubleshooting).

### Clients that only support local servers

Context: Arcweave docs > Integrations > Arcweave MCP server > Other MCP clients > Clients that only support local servers

A local client that supports **stdio** can use the third-party [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge. The bridge runs on your computer and forwards requests to Arcweave's hosted server. Install a current Node.js LTS release with npm first.

For Claude Desktop, open **Settings → Developer → Edit Config** and add the following to `claude_desktop_config.json`. For another stdio client, add the equivalent command, arguments, and environment in its local server settings:

```json
{
  "mcpServers": {
    "arcweave": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://arcweave.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${ARCWEAVE_AUTH_HEADER}"
      ],
      "env": {
        "ARCWEAVE_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` in this private configuration. Keep the header argument exactly as shown: the bridge expands `ARCWEAVE_AUTH_HEADER`, and putting the space inside its value avoids argument-quoting problems on Windows.

Fully quit and reopen the client. If Windows cannot launch `npx`, set `command` to `cmd` and prepend `"/c", "npx"` to `args`. If Node.js was just installed, restart the app so it picks up the updated `PATH`.

This bridge requires a client that can run local processes. It cannot be added to a web app that only accepts a remote URL.

## Check your connection

Context: Arcweave docs > Integrations > Arcweave MCP server > Check your connection

After connecting, start a conversation and ask:

> Use Arcweave to list the projects I can access. Show their names and project IDs without changing anything.

The assistant should call `arcweave_list_projects` and return projects from your key's workspace. A successful server connection or tool list alone does not confirm that the key has permission to read project data.

Then choose a project:

> In the project with ID PROJECT_HASH, list its boards and summarize the opening scene. Do not make changes.

Replace `PROJECT_HASH` with the returned `projectId`. It is the project's [URL hash](https://docs.arcweave.com/project-tools/settings#project-hash), not a numeric database ID. You can copy it from Project settings if your role allows access to a specific project but not the workspace project list.

If you enabled **Read projects** and **Write projects**, try an edit in a test project:

> In my test project PROJECT_HASH, find the board named “MCP test” and create one element titled “Hello from MCP” with the content “This element was created by my assistant.” Ask before making the change.

Create or choose that test board first, then review the tool call. Open the same project in Arcweave and check the new element and project history. Further tasks can build connected scenes, inspect conditions, organize components, or prepare exports.

Asset uploads and export downloads return temporary transfer URLs. The assistant also needs an HTTP or file-transfer capability to upload or save the actual files. A tool result containing a URL does not mean the file has already transferred. See [Upload a media file](https://docs.arcweave.com/integrations/mcp-tools#upload-a-media-file) and [Exports](https://docs.arcweave.com/integrations/mcp-tools#exports) for how transfers work.

## Available tools

Context: Arcweave docs > Integrations > Arcweave MCP server > Available tools

The server provides 105 tools for projects, comments, Play Mode CSS, exports, boards, starting elements, elements, notes, connections, branches, variables, jumpers, components, attributes, assets, covers, and element audio. Tools that read data need **Read projects**; tools that change data or prepare uploads need **Write projects**.

See the [MCP tool reference](https://docs.arcweave.com/integrations/mcp-tools) for every tool, its arguments, and the permission it needs.

## Style Play Mode

Context: Arcweave docs > Integrations > Arcweave MCP server > Style Play Mode

The MCP CSS tools edit the same custom stylesheet as Arcweave's [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor). Use the [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference) for DOM structure, selectors, default styles, and element UUID targeting. You do not need to inspect the browser to construct these selectors.

Reading requires **Read projects** and project read access. Updating or clearing requires **Write projects** and project edit access. For an editing workflow, enable both permissions.

1. Call `arcweave_get_project_css` with:

   ```json
   { "projectId": "PROJECT_HASH" }
   ```

   The response is `{"css":"..."}`, or `{"css":""}` when no custom CSS exists. It does not include Arcweave's built-in styles. Retain the original string for rollback.

2. Modify that string, preserving rules unrelated to the requested change. Re-read the saved CSS just before updating; if it changed, reapply your edits to the latest value. Call `arcweave_update_project_css` with the **complete resulting stylesheet**. For a project with no existing custom CSS, a text-color change could use:

   ```json
   {
     "projectId": "PROJECT_HASH",
     "css": ".prototype__text .editor .editor-content { color: #e2e8f0; }"
   }
   ```

   This replaces all custom CSS; it does not append a rule. The tool returns the saved stylesheet. To clear custom styling, use `{"projectId":"PROJECT_HASH","css":""}`. The `css` field is required; `null` does not clear it.

3. Call `arcweave_get_project_css` again and compare the saved value with your intended stylesheet. Surrounding whitespace may be trimmed.
4. **Reload an already-open Play Mode tab**, or click Play in the editor to open a new tab with fresh settings. Then check the appearance. Restarting the story or returning through same-tab navigation does not fetch fresh settings. External CSS updates are not broadcast to already-open players.

A successful tool response confirms storage, not valid CSS syntax, matching selectors, or a usable layout. Follow the reference's [verification steps](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles). If the assistant cannot use a browser, it should state that visual verification is outstanding.

Saves have no conflict detection: the latest save replaces the stylesheet. Coordinate with anyone editing CSS manually. Retain unsaved local edits before reloading an old Style Editor tab, then reapply them to the fresh CSS before saving there. See [Save and verify styles](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles).

CSS writes do not create project command-history entries. To roll back, send the original stylesheet through `arcweave_update_project_css`, then reload the player.

For example, ask:

> In project PROJECT_HASH, read the existing Play Mode CSS and retain a rollback copy. Use the Play Mode styling reference to change the story text color to light gray while preserving other rules. Save the complete stylesheet, read it back, and fully reload Play Mode to check the result if browser access is available. Report what you verified.

For images, prefer styling the project's existing element or component covers. Upload and download transfer URLs expire; do not save them in CSS. See [Asset URLs](https://docs.arcweave.com/project-tools/play-mode/styling-reference#asset-urls) for presentation URLs and authenticated download limitations.

## Limits and security

Context: Arcweave docs > Integrations > Arcweave MCP server > Limits and security

- **Rate limits:** MCP requests share the workspace's [REST API quotas](https://docs.arcweave.com/rest-api/overview#rate-limits) with REST requests from all keys in the workspace, including requests to the signed upload and download URLs. Calls to `arcweave_import_project` and downloads from export URLs also count toward the smaller import/export quota. Preparing an export URL counts only toward the overall quota.
- **IP limit:** each IP address can make up to **300 requests per minute** to the MCP server and its transfer URLs, across all keys and workspaces. Clients sharing one address, such as on a company network, share this limit.
- **Transfer URLs:** upload and download URLs are signed, expire after 10 minutes, and don't need an `Authorization` header. Upload URLs work once. Treat a transfer URL like a short-lived password: anyone who has it can use it until it expires. When it's used, Arcweave checks that the key still exists and has the permission the transfer needs.
- **Keys:** a key can't do more than its permissions and its creator's workspace and project permissions allow. Removing the key, or its creator leaving the workspace, ends access immediately.

## Troubleshooting

Context: Arcweave docs > Integrations > Arcweave MCP server > Troubleshooting

| Problem                                              | What to check                                                                                                                                                                                                                                                                                   |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                                   | Check that the key is current and the header is `Authorization: Bearer YOUR_API_KEY`. Remove accidental whitespace. Keys are deleted when their creator leaves the workspace. For environment-based setups, fully restart the client from the terminal containing the variable.                 |
| `403 Forbidden` when connecting                      | The key's workspace must have API access, which requires a Team workspace. A browser-based client also needs Arcweave to allow its origin; contact support with the client name and origin. Do not send your API key.                                                                           |
| Connection works, but a tool returns `403 Forbidden` | Check the key's **Read projects** / **Write projects** permissions and the creator's workspace and project permissions. Listing projects requires the creator to have the workspace-level **View projects list** permission.                                                                    |
| `404 Not Found` at the MCP endpoint                  | Check the exact URL `https://arcweave.com/mcp`. The endpoint must be enabled for the release; if the correct URL still returns `404` during setup, contact Arcweave support.                                                                                                                    |
| OAuth or “sign in” error                             | Use the API-key header, not OAuth. In OpenCode, set `oauth` to `false`. In Claude's custom connector, use **No sign in** with the request header.                                                                                                                                               |
| SSE or transport error                               | Choose Streamable HTTP and the field spelling shown for your client. Do not change the endpoint to `/sse`.                                                                                                                                                                                      |
| Tools do not appear, or only some appear             | Reconnect or restart the client to refresh its tool catalog. Check server enablement, tool selection, client tool limits, and organization policies. Use an agent mode that can call tools.                                                                                                     |
| `429 Too Many Requests`                              | Wait for the server's `Retry-After` period. MCP shares the workspace's [REST API quotas](https://docs.arcweave.com/rest-api/overview#rate-limits); imports and exports have a smaller shared quota, and MCP also has a limit of 300 requests per minute per IP address. See [Limits and security](https://docs.arcweave.com/integrations/mcp#limits-and-security). |
| An upload or download URL fails                      | Ask the assistant to request a fresh URL. Transfer URLs expire after 10 minutes, and upload URLs are single-use. If an upload's response was lost, check the asset library before retrying.                                                                                                     |

Opening the endpoint in an ordinary browser tab is not a connection test: the address bar does not send your API-key header or an MCP request. Use your client's server status and the read-only project-list prompt above.

To disconnect, disable or remove `arcweave` in the client. To revoke access, [remove the API key](https://docs.arcweave.com/workspaces/api#remove-api-keys) in Arcweave. Changing a key's permissions takes effect immediately; if you replace a key, update every client that used it.
