Skip to content

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 ​

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 for key management and REST API permissions for the underlying access rules.

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 ​

SettingValue
Server namearcweave
Server URLhttps://arcweave.com/mcp
TransportStreamable HTTP (often labeled HTTP)
AuthenticationWorkspace API key sent as a bearer token
Header nameAuthorization
Header valueBearer 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 ​

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

bash
read -rsp 'Arcweave API key: ' ARCWEAVE_API_KEY
printf '\n'
export ARCWEAVE_API_KEY
powershell
$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 ​

ClientSetup
Claude CodeClaude Code
Codex CLI, desktop app, and IDE extensionCodex
CursorCursor
Visual Studio Code with GitHub CopilotVS Code
GitHub Copilot CLICopilot CLI
OpenCodeOpenCode
Google AntigravityAntigravity
Muse CodeMuse Code
Gemini CLIGemini CLI
Claude web and DesktopClaude
Windsurf / Devin Desktop (Cascade)Windsurf
ClineCline
ChatGPTChatGPT compatibility
Zed, Kiro, and other clientsOther MCP clients
Clients that only support local serversLocal bridge

Claude Code ​

After setting the environment variable, 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.

Codex ​

After setting the environment variable, 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.

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

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. This portable configuration also works with Copilot CLI.

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 and configuration reference.

GitHub Copilot CLI ​

You can use the portable configuration in the VS Code instructions, 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. 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.

OpenCode ​

After setting the environment variable, 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.

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

Muse Code ​

After setting the environment variable, 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 and settings reference.

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.

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.

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 below. It runs on your computer and is not a workaround for Claude web or mobile.

See Claude's custom connector instructions.

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

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.

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: 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 and local MCP configuration.

Other MCP clients ​

If your client supports remote servers with custom headers, add a server using the 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:

ClientWhere to configureDifferences
ZedSettings → AI → MCP Servers → Add Remote Server, or zed: open settings fileUse context_servers instead of mcpServers. Check for a green Server is active indicator.
KiroKiro: Open user MCP config (JSON), which opens ~/.kiro/settings/mcp.jsonUses the shape above. Enable MCP support in Kiro's settings if it is disabled; saving the file reconnects.

See the Zed MCP guide and Kiro MCP configuration guide.

Web apps that connect to MCP servers from their own servers, such as Claude's custom connectors, 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.

Clients that only support local servers ​

A local client that supports stdio can use the third-party 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 ​

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, 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 and Exports for how transfers work.

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 for every tool, its arguments, and the permission it needs.

Style Play Mode ​

The MCP CSS tools edit the same custom stylesheet as Arcweave's Style Editor. Use the 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. 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.

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 for presentation URLs and authenticated download limitations.

Limits and security ​

  • Rate limits: MCP requests share the workspace's REST API quotas 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 ​

ProblemWhat to check
401 UnauthorizedCheck 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 connectingThe 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 ForbiddenCheck 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 endpointCheck 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” errorUse 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 errorChoose Streamable HTTP and the field spelling shown for your client. Do not change the endpoint to /sse.
Tools do not appear, or only some appearReconnect 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 RequestsWait for the server's Retry-After period. MCP shares the workspace's REST API quotas; 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.
An upload or download URL failsAsk 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 in Arcweave. Changing a key's permissions takes effect immediately; if you replace a key, update every client that used it.