MCP Server

最后更新：28.01.2026版本2.0

概述

Arrival Space MCP（Model Context Protocol）服务器允许 Claude 等 AI 助手直接与您的 Arrival Space 账户交互。您可以通过自然语言对话创建空间、管理实体并控制您的 3D 环境。

什么是 MCP？

Model Context Protocol 是一个开放标准，使 AI 助手能够安全地连接到外部服务。当您通过 MCP 将 Claude 连接到 Arrival Space 时，Claude 可以代表您执行操作 — 例如创建新空间或添加 3D 内容。

---

连接到 Claude

设置

1. 在 Claude 中，前往 Settings → Connectors → Add custom connector
2. 输入 URL：

   https://api-staging.arrival.space/api/v1/mcp

3. 使用您的 Arrival Space 账户登录
4. 完成！

---

连接到 OpenAI Codex

设置

1. 在 Codex 中，前往 Settings → MCP servers → Add server
2. 配置连接：
   • Name: arrival.space
   • Transport: Streamable HTTP
   • URL: https://api-staging.arrival.space/api/v1/mcp
3. 点击 Save，然后点击 Authenticate
4. 浏览器窗口将打开 — 使用您的 Arrival Space 账户登录
5. 完成！

---

可用工具

连接后，AI 助手可以使用以下工具与您的 Arrival Space 账户交互：

空间管理

工具	描述
list_spaces	列出您拥有的所有空间。支持搜索和分页
get_space	获取特定空间的详细信息
create_space	创建新空间（Hub 或 Infinite）
update_space	更新空间标题、描述或隐私设置
delete_space	删除空间及其所有实体
update_space_privacy	更改空间隐私设置（公开/关闭）
get_space_screenshot	获取空间的截图（JPEG）

实体管理

工具	描述
list_entities	列出空间中的所有实体。支持分页
get_entity	获取单个实体的详细信息
create_entity	创建新实体（3D 模型、插件、Splat、图片等）
update_entity	更新实体属性（合并语义）
delete_entity	从空间中删除实体

实体数据字段

entity_data 对象支持以下字段：

字段	类型	描述
position	{x, y, z}	世界位置。示例：{x: 0, y: 1.5, z: -3}
rotation	{x, y, z}	欧拉旋转（度）。示例：{x: 0, y: 90, z: 0}
scale	number	统一缩放倍数。默认：1.0。示例：2.0 = 双倍大小
params	object	插件属性值 — 键名匹配插件的静态属性名称
glbUrl	string	实体资源的 CDN URL — 3D 模型、图片、Splat 或插件脚本（.mjs）。名称为历史遗留；使用 resource_key 时自动设置

提示

更新实体时，只需包含要更改的字段。省略的字段保持当前值（合并语义）。

头像管理

工具	描述
list_avatars	列出您的头像，包含 ID、部件、色调和缩略图 URL
get_avatar_catalog	获取可用的头像部件和类别及外观描述
create_avatar	从部件创建头像。返回 jobSeq — 用 get_avatar_status 轮询结果
generate_avatar_from_description	通过自然语言描述创建头像（例如"短红发、蓝色夹克"）
update_avatar	更新现有头像的部件或色调
assign_avatar	将头像设为当前使用的头像
get_avatar_status	检查头像生成状态，完成后获取 GLB 模型 URL
delete_avatar	删除头像

文件上传

工具	描述
upload_text_file	将 UTF-8 文本文件（插件、JSON 等）上传到 CDN。返回 resource_key
upload_file_from_url	从外部 URL 上传文件到 CDN。返回 resource_key
upload_binary_file	将 Base64 编码的二进制文件（GLB、图片等）上传到 CDN。返回 resource_key

提示

使用文件上传返回的 resource_key 配合 create_entity，将上传的内容放置到空间中。

插件

工具	描述
get_plugin_docs	从 Arrival 插件仓库获取插件文档和示例

用户信息

工具	描述
get_user_info	获取您的个人资料信息

---

对话示例

以下是连接后您可以向 Claude 提出的一些请求：

列出您的空间：

"显示我所有的 Arrival Space 空间"

创建新空间：

"创建一个名为'My Gallery'的新空间，描述为'A showcase of my 3D art'"

管理实体：

"列出我的空间 45637586_1234 中的所有实体"

更新隐私设置：

"将我的空间 45637586_1234 设为私有"

---

技术详情

服务器端点

https://api-staging.arrival.space/api/v1/mcp

认证

MCP 服务器使用带 PKCE 的 OAuth 2.0 进行安全认证。当您授权连接时，您现有的 API 密钥将作为访问令牌使用 — 与您在 Arrival Space 账户设置中看到的密钥相同。

支持的传输方式

• Streamable HTTP（推荐用于 Claude Desktop）
• SSE (Server-Sent Events) 用于旧版客户端

OAuth 发现

MCP 客户端可以通过以下方式自动发现 OAuth 端点：

GET /.well-known/oauth-authorization-server

---

故障排除

连接问题

如果 Claude 无法连接到 Arrival Space：

1. 检查服务器 URL — 确保它是 https://api-staging.arrival.space/api/v1/mcp
2. 重启 Claude Desktop — 在编辑配置后重启
3. 重新认证 — 尝试删除并重新添加连接

认证弹窗未出现

• 确保浏览器未阻止弹出窗口
• 如果 Claude 提供了 OAuth URL，尝试手动打开

"Invalid API key" 错误

• 您的会话可能已过期 — 通过触发任何 Arrival Space 操作来重新认证
• 检查您的 Arrival Space 账户是否已验证且处于活跃状态

---

安全性

• 您的密码绝不会与 Claude 共享
• 认证使用行业标准的带 PKCE 的 OAuth 2.0
• 访问令牌就是您的 API 密钥，您可以随时从 Arrival Space 账户设置中撤销
• 所有通信均通过 HTTPS 加密

警告

只连接您信任的 MCP 服务器。位于 api-staging.arrival.space 的 Arrival Space MCP 服务器由 Arrival Space 团队官方维护。