MODEL CONTEXT PROTOCOL

通过 MCP 接入游戏素材生成与编辑

使用谷灵AI MCP 服务地址与 API Key 接入 AI Agent，查询素材类型、设置积分预算、生成与编辑游戏素材，并获取任务结果和下载地址。

把素材创作融入开发对话：描述角色、场景或 UI 需求，让 Agent 在你的预算内完成创建与编辑，再获取交付素材，继续游戏开发。精灵动作和动画特效可在 request.params.output_duration 指定 1–4 秒导出长度，省略时自动截取。

配置 URL 和 Key

登录后在 API Key 管理创建 Key。只读工具授予目录、账户权限；生成与编辑另授予模型、任务和素材权限，并设置单次与每日积分上限。Key 明文只显示一次，默认永久有效，可选到期时间。

谷灵 MCP 服务地址https://www.gulingai.com/mcp

传输方式：Streamable HTTP
请求头：Authorization: Bearer YOUR_API_KEY

服务由谷灵AI运行，远程接入使用 URL 和 Key。工具列表只展示当前 Key 有权限的工具。各个 Agent 的配置示例统一使用谷灵正式服务地址。

各个 AI Agent 的接入方式

选择你使用的 Agent，展开查看接入步骤和配置示例。所有示例使用上方服务地址；请将 YOUR_API_KEY 替换为你创建的 API Key，并合并到已有配置中。

Cursor.cursor/mcp.json

在项目中打开或创建 .cursor/mcp.json；全局配置可使用 ~/.cursor/mcp.json。
合并下方 guling 条目，将 YOUR_API_KEY 替换为谷灵 API Key。
保存配置并刷新 MCP 服务，确认 guling 工具列表出现；在 Agent 对话中先查询素材类型，再创建或编辑素材。

.cursor/mcp.json

{
  "mcpServers": {
    "guling": {
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor 官方 MCP 文档 ↗

Claude Code终端命令 / 当前项目

在需要接入谷灵的项目目录打开终端。
替换命令中的 YOUR_API_KEY，再运行添加命令。
启动 Claude Code，输入 /mcp 检查 guling 状态；在对话中请求创建或编辑素材。

在项目目录执行

claude mcp add --transport http guling "https://www.gulingai.com/mcp" --header "Authorization: Bearer YOUR_API_KEY"

Claude Code 官方 MCP 文档 ↗

Codex~/.codex/config.toml

在 ~/.codex/config.toml 中添加下方 MCP 配置。
把 GULING_API_KEY 环境变量设为自己的 API Key，确保启动 Codex 的进程能读取它。
重启 Codex；CLI 用 /mcp 查看 guling 连接与工具，然后在对话中调用。

bearer_token_env_var 的值是环境变量名称，不是 Key 本身。桌面应用从系统环境或其启动环境读取变量；设置后需重新启动。

~/.codex/config.toml

[mcp_servers.guling]
url = "https://www.gulingai.com/mcp"
bearer_token_env_var = "GULING_API_KEY"

macOS / Linux 终端环境变量

export GULING_API_KEY="YOUR_API_KEY"

Windows PowerShell 环境变量

$env:GULING_API_KEY = "YOUR_API_KEY"

Codex 官方 MCP 文档 ↗

DeepSeek Harness~/.dsh/cordis.patch.yml

打开 ~/.dsh/cordis.patch.yml；如果设置了 DSH_HOME，则打开 $DSH_HOME/cordis.patch.yml。
合并下方 insert 项，并将 YOUR_API_KEY 替换为自己的谷灵 API Key。
重启 DeepSeek Harness，确认 mcp__guling__list_asset_types 出现，再在对话中查询素材类型。

DeepSeek Harness 使用 Cordis patch，不读取通用的 mcpServers JSON。用户级 patch 会应用到所有 profile；只需单个 profile 时可改用 $DSH_HOME/profiles/desktop/cordis.patch.yml 或 $DSH_HOME/profiles/web/cordis.patch.yml。已有 patch 文件时只合并 insert 项，不要覆盖其他配置。配置文件含明文 Key，请仅保存在自己的设备上。

~/.dsh/cordis.patch.yml

- insert:
    - id: mcp-guling
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: guling
        transport: streamable-http
        url: https://www.gulingai.com/mcp
        headers:
          Authorization: 'Bearer YOUR_API_KEY'

DeepSeek Harness 官方 MCP 文档 ↗

TRAE设置 → MCP → 添加 → 手动添加

打开设置中的 MCP 管理面板，选择手动添加。
粘贴下方 JSON，将 YOUR_API_KEY 替换为谷灵 API Key；已有配置时只合并 guling 条目。
保存配置并刷新 MCP 服务，确认 guling 工具列表出现；在 Agent 对话中先查询素材类型，再创建或编辑素材。

设置 → MCP → 添加 → 手动添加

{
  "mcpServers": {
    "guling": {
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

TRAE 官方 MCP 文档 ↗

GitHub Copilot（VS Code）.vscode/mcp.json

在项目中打开或创建 .vscode/mcp.json。
合并下方 servers 配置；启动服务时在输入框填写谷灵 API Key。
在 MCP 配置编辑器中启动 guling，按提示信任服务；打开 Copilot Agent 模式并启用谷灵工具。

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "guling-api-key",
      "description": "谷灵 API Key",
      "password": true
    }
  ],
  "servers": {
    "guling": {
      "type": "http",
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:guling-api-key}"
      }
    }
  }
}

GitHub Copilot（VS Code）官方 MCP 文档 ↗

CodeBuddyCodeBuddy Code：项目根目录 .mcp.json

使用 CodeBuddy Code，在项目根目录创建或打开 .mcp.json。
合并下方 guling 条目，替换 API Key；CodeBuddy IDE 用户可在 MCP 设置中添加相同的 HTTP 服务。
启动新的 CodeBuddy Code 会话，用 /mcp 查看连接；按提示批准服务后调用素材工具。

CodeBuddy Code：项目根目录 .mcp.json

{
  "mcpServers": {
    "guling": {
      "type": "http",
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

CodeBuddy 官方 MCP 文档 ↗

QoderQoder CLI：~/.qoder/settings.json

打开 ~/.qoder/settings.json，保留已有设置并合并 mcpServers。
填写下方 HTTP 配置与谷灵 API Key。Qoder IDE 用户在设置 → MCP → My Servers 中添加服务地址。
CLI 中执行 /mcp reload，再用 /mcp 查看 guling 状态；IDE 中刷新服务并进入 Agent 对话。

Qoder CLI：~/.qoder/settings.json

{
  "mcpServers": {
    "guling": {
      "type": "http",
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Qoder 官方 MCP 文档 ↗

WorkBuddyWorkBuddy 的 MCP 配置界面

打开 WorkBuddy 的 MCP 配置界面，添加自定义服务。
若提供远程 HTTP 和请求头选项，填写下方连接参数；若提供本地命令选项，按桥接 JSON 中的 command、args、env 填写。
保存并启用服务，确认工具列表加载后，在任务对话中描述素材创建或编辑需求。

WorkBuddy 的 MCP 配置入口和鉴权选项可能随版本变化。支持 HTTP 与自定义请求头时使用连接参数；仅提供本地命令配置时使用 stdio 桥接，需安装 Node.js 20 或更高版本。

远程 HTTP 连接参数（按界面填写）

服务名称：guling
传输方式：Streamable HTTP
服务地址：https://www.gulingai.com/mcp
请求头名称：Authorization
请求头值：Bearer YOUR_API_KEY

本地 stdio 桥接（command / args / env）

{
  "mcpServers": {
    "guling": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.gulingai.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${GULING_AUTH_HEADER}"
      ],
      "env": {
        "GULING_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

桥接方案使用开源 mcp-remote 将远程 HTTP 服务转为本地 stdio。首次启动会通过 npx 获取依赖，桥接服务地址同样使用 https://www.gulingai.com/mcp。

WorkBuddy 官方 MCP 文档 ↗

Kimi CodeKimi Code CLI：~/.kimi-code/mcp.json

使用 Kimi Code CLI，打开或创建 ~/.kimi-code/mcp.json。
合并下方配置，替换 YOUR_API_KEY；不填写 transport 时，url 条目使用 HTTP。
重启 CLI 会话并查看 MCP 服务状态，再让 Agent 查询谷灵素材类型。

Kimi Code CLI：~/.kimi-code/mcp.json

{
  "mcpServers": {
    "guling": {
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Kimi Code 官方 MCP 文档 ↗

通义灵码新版 Qoder CN CLI / 旧版插件 MCP 设置

新版 Qoder CN CLI：在用户 settings.json 中合并下方 HTTP 配置。
旧版灵码插件：在个人设置 → MCP 服务中添加 STDIO 服务，按桥接示例填写 command、args、env。
刷新服务；CLI 用 /mcp 查看状态，插件切换到智能体模式后调用谷灵工具。

通义灵码相关官方文档现使用 Qoder CN 名称。新版 CLI 配置在 ~/.qoder-cn/settings.json；仅支持 stdio/SSE 的旧版插件请使用下方本地桥接方案，需先安装 Node.js 20 或更高版本。

新版 Qoder CN CLI：~/.qoder-cn/settings.json

{
  "mcpServers": {
    "guling": {
      "type": "http",
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

本地 stdio 桥接（command / args / env）

{
  "mcpServers": {
    "guling": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.gulingai.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${GULING_AUTH_HEADER}"
      ],
      "env": {
        "GULING_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

桥接方案使用开源 mcp-remote 将远程 HTTP 服务转为本地 stdio。首次启动会通过 npx 获取依赖，桥接服务地址同样使用 https://www.gulingai.com/mcp。

通义灵码官方 MCP 文档 ↗

WindsurfCascade → MCP / mcp_config.json

在 Cascade 的 MCP 设置中打开原始配置 mcp_config.json。
合并下方 guling 配置，替换 API Key。
刷新 MCP 服务并启用谷灵工具，在 Cascade 对话中描述素材需求。

Cascade → MCP / mcp_config.json

{
  "mcpServers": {
    "guling": {
      "serverUrl": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf 官方 MCP 文档 ↗

OpenCodeopencode.json

在项目中打开或创建 opencode.json。
合并下方 mcp 配置；oauth: false 表示使用谷灵 API Key 鉴权。
重启 OpenCode 会话并检查 MCP 状态，在对话中要求使用 guling 工具。

opencode.json

{
  "mcp": {
    "guling": {
      "type": "remote",
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "oauth": false,
      "enabled": true
    }
  }
}

OpenCode 官方 MCP 文档 ↗

ClineMCP Servers → Configure MCP Servers

打开 Cline 的 MCP Servers 面板，进入服务配置。
合并下方配置，明确设置 type 为 streamableHttp，并替换 API Key。
保存配置并刷新 MCP 服务，确认 guling 工具列表出现；在 Agent 对话中先查询素材类型，再创建或编辑素材。

MCP Servers → Configure MCP Servers

{
  "mcpServers": {
    "guling": {
      "type": "streamableHttp",
      "url": "https://www.gulingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline 官方 MCP 文档 ↗

确认接入成功

先让 Agent “使用谷灵工具查询可制作的素材类型”，确认 list_asset_types 正常返回；再查询模型与报价，按预算创建、编辑素材。能看到工具列表只代表服务连接成功，生成是否开放仍以模型查询结果为准。

可调用工具

工具	用途	权限
`list_asset_types`	素材类型与开放状态	`catalog:read`
`get_account`	账户与可用积分	`account:read`
`list_provider_models`	模型与价格	`models:read`
`quote_generation`	素材生成与编辑报价	`generations:read`
`generate_asset`	生成素材（消耗积分）	`generations:write`
`edit_asset`	编辑原图并保留原文件（消耗积分）	`generations:write`
`repair_animation_frame`	修复动画单帧并创建新版本（5 积分）	`generations:write`
`get_generation / list_generations`	查询任务与交付结果	`generations:read`
`cancel_generation`	取消未完成任务	`generations:write`
`get_asset`	素材信息和下载地址	`assets:read`
`create_asset_download`	创建 5 分钟下载链接，便于 Agent 下载素材	`assets:read`
`upload_reference`	上传参考图	`assets:write`

AI Agent 素材创作流程

接入后可以直接告诉 Agent：“创建一个 256 × 256 的像素风骑士，透明背景；完成后沿用原图，把盔甲改为绿色。”Agent 可按以下流程调用工具，生成与编辑能力以模型开放状态为准。

调用 list_provider_models，确认类型已开放并查看价格。
上传参考图或选择自己的素材，准备类型、描述、风格、画布和专属参数。
在用户授权预算内调用 generate_asset 或 edit_asset，传入创作参数、max_credits 和唯一 idempotency_key。
调用 get_generation 查询状态，完成后使用素材 ID 与受鉴权保护的下载地址。

创建任务先预留积分，成功交付后结算；失败或取消释放未结算积分。网络重试沿用同一幂等键；查询同一任务不会重复扣费。角色配音与游戏音效配置开通后可用。

接入检查

401：Key 无效或失效；403：权限不足；生成工具返回 GL_GENERATION_DISABLED：模型、价格或开关尚未配置。请使用 https://www.gulingai.com/mcp 接入，并确认 API Key 的权限与积分预算。

项目素材生产与引擎导出

在素材项目与套装固定引擎版本、风格、色板、画布、枢轴点及纹理预算。网站、REST、MCP 使用同一套规范、任务、版本和积分记录。

调用 set_project_profile 创建规范；更新时传 project_id 与 expected_version，旧版本保留。
调用 plan_asset_bundle 创建免费计划，保存规范快照；动作可以通过 source_item_key 依赖前序角色，多方向须指定 source_direction。
核对 total / planned 费用，调用 submit_asset_bundle，传入 max_credits 和幂等键。系统逐项预留和结算，不预留整套费用、不自动付费重试。
用 get_bundle_report 查询；失败和暂停不会被查询触发重做。暂停后使用原预算和幂等键显式提交可继续；Key 失效后需用有权限的 Key 重新授权。
预览并用 review_bundle_item 记录人工验收。需要修改时调用原生成、编辑或单帧修复工具，再 select_bundle_item 替换指定项，旧版本保留。
调用 export_engine_bundle 导出当前或指定 revision。默认要求全部项通过技术检查且人工接受；项目测试可显式传 allow_unreviewed: true。

项目权限为 projects:read/write，套装权限为 bundles:read/write。执行套装还需 generations:write，替换需 generations:read，导出需 assets:read。已有 Key 不会自动增加权限，请创建包含所需权限的新 Key。

工具	用途	需要权限
`set_project_profile`	创建项目或追加不可变美术规范版本；更新必须传 expected_version。不会生成或扣费。	projects:write
`list_projects`	列出本人素材项目，最多 50 项，支持游标。	projects:read
`get_project_profile`	读取本人项目及指定的不可变规范版本；省略 version 使用当前版本。	projects:read
`plan_asset_bundle`	免费创建不可变套装计划，最多 64 项。可用 source_item_key 依赖前序角色；多方向角色依赖须指定 source_direction。不会生成或冻结积分。	bundles:write
`list_asset_bundles`	列出本人套装摘要，支持项目筛选和游标；不会推进任务或扣费。	bundles:read
`submit_asset_bundle`	授权执行已规划套装。总费用不得超过 max_credits；逐项冻结和结算，不预留整套费用。仅执行一次，不自动付费重试；重启可恢复，Key 失效停止新任务。	bundles:write、generations:write
`get_bundle_report`	只读套装进度、费用、技术问题、人工验收和源版本；revision 可查看历史快照，不会触发生成。	bundles:read
`cancel_asset_bundle`	停止未提交项并取消未完成子任务，释放相应预留积分；已交付素材与扣费保留。	bundles:write、generations:write
`select_bundle_item`	用本人已完成且规格匹配的任务替换一个套装项，创建新修订并清除该项验收；不调用模型、不扣费。	bundles:write、generations:read
`review_bundle_item`	记录当前所选素材的人工验收（accepted/rejected/pending），创建套装修订。技术检测与美术验收分别记录。	bundles:write
`set_bundle_item_metadata`	设置动作事件、挂点及碰撞框并创建新修订。时间以秒计，坐标归一化且原点在画布左上角；这些数据由开发者定义，不从图片自动推断。修改后重新验收该项。	bundles:write
`export_engine_bundle`	免费导出指定修订的带扩边分页图集、清单、质量报告和 Unity/Cocos 接入源码；默认要求全部项人工接受且技术检查通过。allow_unreviewed=true 显式导出测试包；引擎源码仍须在目标版本编译实测。	bundles:read、assets:read

套装计划示例

{
  "project_id": "prj_替换为本人项目ID",
  "name": "骑士基础动作",
  "items": [
    {
      "key": "hero",
      "request": {
        "kind": "character",
        "prompt": "穿红色披风的骑士，单个全身角色",
        "params": {
          "direction_count": 1,
          "direction": "east",
          "view": "side"
        }
      }
    },
    {
      "key": "idle",
      "source_item_key": "hero",
      "source_direction": "east",
      "request": {
        "kind": "animation",
        "prompt": "原地待机，平稳呼吸",
        "params": {
          "action": "idle",
          "fps": 12,
          "loop": true,
          "output_duration": 2
        }
      }
    }
  ]
}

将示例作为 plan_asset_bundle 参数，或 POST /v1/bundles/plan。project_id 替换为本人项目，规范画布须为不超过 512 的正方形。示例生成一个角色和一个待机动作，共 35 积分；计划本身不生成、不扣费。

局部修复与配置

upload_reference 可上传同尺寸 PNG 蒙版：白色为修改区、黑色为保护区，灰度乘透明度决定混合权重。静态原图编辑传 request.edit_mask_asset_id；repair_animation_frame 传 mask_asset_id。蒙版外保留原 RGBA 像素，蒙版修复动画时保留其他帧和画布，不重新对齐整套帧。工作台也支持画笔绘制修改区域。

set_bundle_item_metadata 设置秒制动作事件、挂点和碰撞框；坐标归一化，原点在画布左上角。这些信息由开发者定义，不根据图片自动推断。验收、替换和配置修改须传 expected_revision，版本冲突时先重新读取。

REST 对应接口

`POST /v1/projects`	set_project_profile
`GET /v1/projects`	list_projects
`GET /v1/projects/:project_id`	get_project_profile
`POST /v1/bundles/plan`	plan_asset_bundle
`GET /v1/bundles`	list_asset_bundles
`POST /v1/bundles/:bundle_id/submit`	submit_asset_bundle
`GET /v1/bundles/:bundle_id`	get_bundle_report
`POST /v1/bundles/:bundle_id/cancel`	cancel_asset_bundle
`POST /v1/bundles/:bundle_id/select`	select_bundle_item
`POST /v1/bundles/:bundle_id/review`	review_bundle_item
`POST /v1/bundles/:bundle_id/metadata`	set_bundle_item_metadata
`POST /v1/bundles/:bundle_id/export`	export_engine_bundle

MCP 导出响应的 download.download_url 可直接供 Agent 下载 ZIP；create_asset_download 可为其他素材创建 5 分钟下载链接，无需读取长效 Key。Key 吊销后链接也失效。

交付与验证边界

ZIP 包含分页扩边图集、稳定帧标识、bundle.json、原交付配置、质量报告、SHA-256 校验清单和所选引擎的接入源码。矩形原点在左上角，pivot 在左下角，无旋转、无透明裁切。Unity 适配器需要 2D Sprite 包；Cocos 适配器提供 Sprite 播放组件。安装步骤见 ZIP 内 README.txt，资源更新时保留引擎生成的 .meta 文件。

技术检查不证明角色身份、动作语义、美术效果和实机性能合格。固定色板会处理可见像素颜色；提示词中的美术要求仍需人工检查。全部资源仍受 30 天有效期约束。下载后请归档，并在目标引擎和手机上完成编译、画面、资源更新与性能测试。