Arcweave Documentation

Appearance

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, permission to create an API key, 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 or edit content. Write permission alone does not include read access.
  4. Click Create, then copy the key using the clipboard icon in the Key column.

The key acts as the member who created it, within that workspace. 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
Codex CLI, desktop app, and IDE extensionCodex
Claude CodeClaude Code
Claude web and DesktopClaude
OpenCodeOpenCode
CursorCursor
Visual Studio Code with GitHub CopilotVS Code
GitHub Copilot CLICopilot CLI
Windsurf / CascadeWindsurf
Gemini CLIGemini CLI
ClineCline
Roo CodeRoo Code
ZedZed
KiroKiro
Google AntigravityAntigravity
ContinueContinue
ChatGPTChatGPT compatibility
Other clients, including local-only clientsOther MCP clients

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.

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.

Claude web and Desktop ​

Use a custom connector with a request header. 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.

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.

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.

Windsurf / 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 current documentation redirects to Devin Desktop; the Cascade configuration above uses the documented serverUrl and headers fields. Open the configuration through the app to find the correct file for your installed version.

See the Cascade MCP guide.

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.

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.

Roo Code ​

Open Roo Code's MCP Servers panel and select Edit Global MCP. Add this to the global mcp_settings.json, replacing YOUR_API_KEY:

json
{
  "mcpServers": {
    "arcweave": {
      "type": "streamable-http",
      "url": "https://arcweave.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Save the file and restart the Arcweave connection in the MCP panel. Roo Code uses streamable-http, with a hyphen. Keep this key in the global settings rather than a shared .roo/mcp.json file.

See the Roo Code MCP guide.

Zed ​

Open Settings → AI → MCP Servers → Add Remote Server, or run zed: open settings file from the command palette and add this to your user settings:

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

Replace YOUR_API_KEY in the private user settings. Zed uses context_servers, not mcpServers. Check for a green Server is active indicator in MCP settings, then use the Agent Panel to try the connection check.

See the official Zed MCP guide.

Kiro ​

In the command palette, run Kiro: Open user MCP config (JSON) to open ~/.kiro/settings/mcp.json. Add this entry, replacing YOUR_API_KEY:

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

Enable MCP support in Kiro's settings if it is disabled. Saving the file reconnects the servers automatically. Check Arcweave in the MCP panel and try the connection check.

See the official Kiro MCP configuration 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.

Continue ​

Continue can import the JSON configuration used by local MCP clients. To use the local bridge:

  1. Install Node.js LTS with npm.
  2. Create .continue/mcpServers/arcweave.json in your workspace. Before adding a key, exclude this private file from source control, for example with /.continue/mcpServers/arcweave.json in .gitignore.
  3. Copy the complete JSON example from the local bridge instructions into that file and replace YOUR_API_KEY.
  4. Reload Continue and select Agent mode. Check that Arcweave tools appear, then try the connection check.

Continue also supports native remote MCP configuration; the bridge example provides a setup with an explicit bearer header using its documented JSON import support.

See the official Continue MCP guide.

ChatGPT ​

ChatGPT web's developer-mode apps do not currently offer the fixed bearer-token authentication this server requires. Their documented authentication choices are OAuth, no authentication, or mixed authentication. 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 developer-mode 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. Each client's JSON field names differ, so use its own configuration format.

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.

Troubleshooting ​

ProblemWhat to check
401 UnauthorizedCheck that the key is current and the header is Authorization: Bearer YOUR_API_KEY. Remove accidental whitespace. For environment-based setups, fully restart the client from the terminal containing the variable.
Connection works, but a tool returns 403 ForbiddenCheck the key's Read projects / Write projects permissions, the creator's workspace and project permissions, and the workspace's API access. Listing projects requires workspace-level View projects permission.
A browser client gets 403 before connectingThe server must allow that browser's origin. Contact Arcweave support with the client name and origin; do not send your API key.
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 an IP request limit.
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.