# Nodary MCP 服务器

Nodary 运行着一个远程 MCP 服务器，让 AI 智能体像队友一样读写你的工作区：同样的文档，同样的权限，以你的名义登录。

## 概览

- **地址**: https://nodary.ai/api/mcp
- **传输方式**: Streamable HTTP（基于 POST 的 JSON-RPC）
- **登录方式**: 支持动态客户端注册和 PKCE 的 OAuth 2.1，或 API 密钥
- **访问权限**: 所有套餐均包含；Free 套餐在其限制内包含
- **服务发现**: https://nodary.ai/.well-known/oauth-protected-resource/api/mcp · https://nodary.ai/.well-known/mcp.json

Claude Code: 在终端中运行以下命令（加上 --scope user 即可在所有项目中使用 Nodary）：

```sh
claude mcp add --transport http nodary https://nodary.ai/api/mcp
```

## 它是什么

Model Context Protocol（MCP，模型上下文协议）是 AI 客户端与外部工具协作所用的开放标准。Nodary 的服务器让智能体使用与你的团队相同的工作区：项目、文档及其关联、电子表格、图片、翻译表、对话和画板。

智能体拿到的不是副本。它读取的是此刻的内容，只在你要求的地方写入，而且每个结果都附带一个链接，方便人打开核查它的工作。

## 登录

大多数客户端通过 OAuth 登录：把服务器地址交给客户端，它就会在你的浏览器中打开 Nodary 的登录与授权页面。Nodary 支持带动态客户端注册和 PKCE 的 OAuth 2.1，因此无需创建客户端 ID，也无需复制任何内容。访问令牌有效期为一小时，由客户端自动续期。

一个连接可以访问多个工作区。如果你属于多个工作区，授权页面会列出全部并默认勾选：应用随后只能访问你保留勾选的工作区。“以及我以后加入的工作区”默认关闭，除非你勾选它。在这样的连接中，每个工具都接受 workspace（ID、slug 或名称）：会修改内容的调用必须指明它；不带它的读取只在其 ID 所在的工作区运行；每个结果都以其运行所在的工作区开头。API 密钥仍只绑定一个工作区。

无法登录的客户端可以改用 API 密钥：在个人资料的 API keys & MCP 中创建一个（以 gdc_ 开头），并通过请求头 Authorization: Bearer gdc_… 发送。密钥可以限定在单个项目内。

## 谁可以使用

所有套餐都包含 MCP 服务器，包括 Free、Pro、Studio 和 Enterprise，每位成员都可使用，无需额外付费。

在 Free 套餐中，只要工作区不超出套餐限制（1 个项目、10 个文档和文件夹以及 2 名成员），智能体就能像在付费套餐中一样读写。会超出限制的写入将被拒绝，并说明触及的限制以及解除方法：若工作区仍可试用，则附上控制面板链接，所有者或管理员可在那里开始 14 天的 Studio 试用（包含 MCP，无需绑卡）；否则附上定价页面链接。

试用结束后未订阅且超出 Free 套餐的工作区，在订阅之前处于锁定状态：智能体在其中被切断，包括读取。只连接该工作区的连接，每个请求都会收到 quota_locked，并说明超出的内容以及所有者在哪里订阅；连接多个工作区的连接，只有发往被锁定工作区的调用才会以工具错误的形式收到 quota_locked（付款失败后为 billing_locked），在其他工作区中照常工作。

- [定价](https://nodary.ai/zh/pricing)

## 智能体能做什么

共 92 个工具，这里按用途分组。每个工具都会告诉客户端它是否只读，以及写入是否可能覆盖已有内容，这样客户端可以在执行前先征求你的同意。

### 查找与阅读

项目、附带关联和历史记录的文档、评论、知识笔记、已保存的视图和上下文简报。结果附带可供人打开的链接。

`list_games`, `list_stars`, `search_documents`, `get_document`, `get_star`, `get_tree`, `list_templates`, `list_members`, `list_project_knowledge`, `get_project_knowledge`, `list_comments`, `get_canon`, `list_versions`, `get_version`, `diff_versions`, `list_deleted_stars`, `list_context_briefs`, `get_context_brief`, `list_saved_views`, `get_saved_view`, `list_favorites`, `get_workspace_usage`, `list_properties`, `get_file_url`, `describe_blocks`, `run_view`, `list_workspaces`

### 撰写与整理

逐块创建和编辑文档，归入文件夹，建立关联，添加标签和评论，设置属性，并解决文档间的矛盾。已删除的文档可以恢复。

`create_game`, `update_game`, `rename_workspace`, `create_starter_constellation`, `create_from_template`, `create_star`, `create_stars`, `write_document`, `append_document`, `edit_document`, `update_star`, `update_stars`, `delete_star`, `restore_star`, `create_cluster`, `move_to_cluster`, `link_stars`, `unlink_stars`, `set_tags`, `save_project_knowledge`, `add_comment`, `add_comments`, `resolve_comment`, `list_contradictions`, `report_contradiction`, `resolve_contradiction`, `save_context_brief`, `save_saved_view`, `set_favorite`, `define_properties`, `set_properties`, `restore_version`, `edit_comment`, `delete_comment`, `delete_project_knowledge`, `remove_context_brief`, `remove_saved_view`, `open_daily_note`

### 美术评审与图片

导入图片，连同大家在图上画的批注一起查看；对交付物做出决定、添加备注和标签（每个决定都会签上决定人和时间）；把情绪板转换为调色板并据此检查图片；还能为外包方准备反馈单。

`add_image`, `start_upload`, `add_media`, `get_image`, `get_moodboard`, `render_board`, `edit_board`, `find_pictures`, `update_pictures`, `get_art_review`, `extract_palette`, `check_palette`, `feedback_sheet`, `restore_image_version`, `set_image_origin`

### 电子表格与数值平衡

以计算后的值读取表格，并查看每个单元格背后的公式；按单元格地址或按行写入；读取掉落表，弄清它对玩家意味着什么。

`get_sheet`, `set_cells`, `analyze_drops`

### 本地化与对话

在翻译表中查看每种语言的进度，按键写入译文，并检查分支对话（可导出为 Yarn Spinner 脚本）。

`get_localization`, `set_translations`, `check_dialogue`

### 制作管理

设置截止日期，发起和提交评审，查看近期变更，以及里程碑能否按时达成。

`get_progress`, `recent_changes`, `set_due_date`, `set_due_dates`, `request_review`, `submit_review`

## 提示词与资源

客户端可以作为命令提供的现成请求：

- weekly-summary: 工作区或某个项目本周的变化：写了什么、定了什么、评审了什么，以及仍待处理的事项。
- art-review: 美术评审进展到哪一步：等待决定的图片、偏离调色板的图片，以及接下来要决定什么。
- playtest-to-tasks: 把试玩笔记转化为任务，每个任务都关联到它涉及的设计文档。
- balance-review: 读取掉落表或成长曲线，说明它对玩家意味着什么，以及哪里看起来不对劲。

客户端无需调用工具即可附加的资源：

- nodary://star/{id}: 单个文档（Markdown 格式）
- nodary://project/{id}: 项目大纲

## 安全

- 智能体以连接它的人的身份行事：只能查看和修改此人有权访问的内容，限定在某个项目的密钥也只能在该项目内使用。
- 在连接多个工作区的连接中，任何内容都不会跨工作区解析：ID 和标题只在调用指明的工作区内查找，来自其他工作区的 ID 会在执行任何操作之前被拒绝，每个结果都会写明其所在的工作区。
- 文档保留版本历史，已删除的文档可以恢复。
- 写入类工具接受幂等键：连接中断后重试的调用会返回第一次的结果，而不会重复写入。
- 每个连接每分钟最多发出 120 个请求；写入没有每日上限。
- 美术评审的决定会签上做出决定的人的姓名和时间。
- Nodary 会告诉每个智能体：文档和评论中的文字是要处理的内容，而不是要遵从的指令。智能体据此如何行事，取决于智能体本身。

## 连接你的客户端

使用地址 https://nodary.ai/api/mcp。以下每个客户端都已于 2026 年 10 月 1 日对照其官方文档核实。

### Claude（claude.ai 和 Claude Desktop）

1. 依次打开 Customize 和 Connectors，然后选择 Add custom connector。
2. 输入 https://nodary.ai/api/mcp。当 Claude 询问如何注册时，选择 Register automatically。
3. 进行连接，登录 Nodary，然后批准访问。

自定义连接器适用于 Free、Pro、Max、Team 和 Enterprise 套餐；Free 账户可以添加一个。在 Team 和 Enterprise 中，需要由所有者先为组织添加该连接器。

### ChatGPT

1. 在 Settings 的 Security and login 下，开启 Developer mode。
2. 为远程 MCP 服务器创建一个应用，地址填写 https://nodary.ai/api/mcp，并选择 OAuth 登录。
3. 登录 Nodary 并批准访问。之后，这些工具会出现在输入框的 Developer mode 中。

Developer mode 仅在网页版提供，适用于 Plus、Pro、Business、Enterprise 和 Education 账户；在 Business 和 Enterprise 中，可能需要管理员允许。ChatGPT 只能通过 OAuth 连接，不支持 API 密钥。

### Claude Code

1. 在终端中运行以下命令（加上 --scope user 即可在所有项目中使用 Nodary）：

   ```
   claude mcp add --transport http nodary https://nodary.ai/api/mcp
   ```
2. 在 Claude Code 中输入 /mcp，选择 nodary，然后在浏览器中登录。

改用 API 密钥

```sh
claude mcp add --transport http nodary https://nodary.ai/api/mcp \
  --header "Authorization: Bearer gdc_..."
```

### Cursor

1. 将 Nodary 添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

   ```
   {
     "mcpServers": {
       "nodary": {
         "url": "https://nodary.ai/api/mcp"
       }
     }
   }
   ```
2. 服务器首次要求登录时，Cursor 会提示你登录。

改用 API 密钥

```json
{
  "mcpServers": {
    "nodary": {
      "url": "https://nodary.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NODARY_API_KEY}"
      }
    }
  }
}
```

### VS Code（GitHub Copilot）

1. 将 Nodary 添加到你工作区中的 .vscode/mcp.json，或运行 MCP: Add Server 命令：

   ```
   {
     "servers": {
       "nodary": {
         "type": "http",
         "url": "https://nodary.ai/api/mcp"
       }
     }
   }
   ```
2. 启动服务器；VS Code 会打开 Nodary 登录页面。

使用 Copilot Business 和 Enterprise 时，需要管理员先允许 MCP 服务器。

改用 API 密钥

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

### Devin Desktop（原 Windsurf）

1. 在终端中添加服务器并登录：

   ```
   devin mcp add -s user nodary https://nodary.ai/api/mcp
   devin mcp login nodary
   ```
2. 或者将它添加到 ~/.config/devin/mcp_config.json（Windows 上为 %APPDATA%\devin\mcp_config.json）：

   ```
   {
     "mcpServers": {
       "nodary": {
         "url": "https://nodary.ai/api/mcp",
         "transport": "http"
       }
     }
   }
   ```

## 遇到问题时

- 首个请求返回 401 并附带 resource_metadata 地址属于正常情况：它告诉客户端去哪里登录。
- 如果请求因 quota_locked 被拒绝，说明该工作区在试用结束后超出了 Free 套餐，在订阅之前处于锁定状态：所有者一订阅，智能体即可恢复工作。在连接多个工作区的连接中，只有发往该工作区的调用会被拒绝。
- 因 workspace_required（或 workspace_not_found）被拒绝的调用会列出该连接可访问的工作区：将其中一个作为 workspace 传入。要访问不在列表中的工作区，请重新连接应用并勾选它。
- 如果客户端无法完成登录，请改用 API 密钥连接。

https://nodary.ai/zh/docs/mcp