将外部 MCP 客户端连接至 Griptape Nodes

Griptape Nodes 内置启动了专属的原生 MCP 服务端，使得各类外部智能体宿主（Claude Desktop、Claude Code、Cursor、VS Code 等）能够直接程序化反向驱动引擎主核。本篇文档与本章节其他页面逻辑互为逆向：其他页面主要介绍 Griptape Nodes 如何作为客户端消费外部 MCP 服务，而本页重点阐述如何将 Griptape Nodes 本身作为服务端暴露给外部 AI 工具调用。

服务监听地址 (URL)

引擎在默认配置下会监听以下地址：

http://localhost:8125/mcp/

其通信传输协议为 Streamable HTTP。强烈建议保留末尾的正斜杠 /；对于会自动剥离末尾斜杠的特殊客户端，服务端亦内置了将 /mcp 自动重定向至 /mcp/ 的容错机制。

当引擎冷启动时，终端控制台会打印实际绑定的物理监听地址，例如：

INFO MCP server listening at http://127.0.0.1:8125/mcp/

环境变量覆盖与参数定制 (Overrides)

服务绑定的网络主机接口与端口号可通过环境变量进行完全覆写：

环境变量名称	默认值	详细功能说明与适用场景
`GTN_MCP_SERVER_HOST`	`localhost`	绑定的网络监听网卡接口。显式本地回环填 `127.0.0.1`；开放给局域网其他机器填 `0.0.0.0`。
`GTN_MCP_SERVER_PORT`	`8125`	TCP 物理端口号。设为 `0` 表示允许操作系统随机分配空闲可用端口。
`GTN_MCP_SERVER_LOG_LEVEL`	`ERROR`	驱动 MCP 服务的底层 uvicorn 运行时日志级别。

若所配置的端口已被其他系统进程占用，引擎会自动平稳回退并申请一个由操作系统分配的空闲临时端口。请始终查阅引擎启动日志确认真实的 URL。

出厂默认仅限本地环回访问 (Local-only by default)

引擎默认严格绑定至 localhost，这意味着物理上只有同一台宿主机内的本地进程能够发起网络请求。该 MCP 服务端未内置密码鉴权机制。除非你百分之百完全信任所在局域网内的所有网络设备，否则严禁盲目将其绑定至 0.0.0.0 或将其暴露到公网。

常见客户端集成配置 (Client configuration)

1. Claude Code

在 ~/.claude.json 配置文件中添加如下条目（或通过系统终端运行 claude mcp add）：

{
  "mcpServers": {
    "griptape-nodes": {
      "type": "streamable-http",
      "url": "http://localhost:8125/mcp/"
    }
  }
}

2. Cursor

创建全局访问配置 ~/.cursor/mcp.json，或在具体项目根目录下创建专属 .cursor/mcp.json：

{
  "mcpServers": {
    "griptape-nodes": {
      "url": "http://localhost:8125/mcp/"
    }
  }
}

3. VS Code

在当前工作区根目录下创建 .vscode/mcp.json，或通过命令面板执行 MCP: Open User Configuration：

{
  "servers": {
    "griptape-nodes": {
      "type": "http",
      "url": "http://localhost:8125/mcp/"
    }
  }
}

注意：VS Code 规范采用 servers（而非 mcpServers），且协议类型字段指定为 "type": "http"。

4. Claude Desktop

Claude Desktop 本地桌面版的 claude_desktop_config.json 规范原生仅支持 stdio 标准输入输出进程。若要连接远程/HTTP MCP 服务，有两种主流途径：

方案 A（图形化）：在桌面客户端依次打开 Settings → Connectors → Add custom connector，并直接粘贴服务地址 http://localhost:8125/mcp/；
方案 B（适配代理）：在配置文件中借助 mcp-remote 桥接网关包裹该 HTTP URL：

{
  "mcpServers": {
    "griptape-nodes": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8125/mcp/"]
    }
  }
}

验证连接连通性 (Verifying the connection)

验证通信最简明且无交互干扰的手段是使用官方的 MCP Inspector 命令行工具。由于引擎采用 Streamable HTTP 协议，请显式附带 --transport http 参数：

npx -y @modelcontextprotocol/inspector --cli http://localhost:8125/mcp/ \
  --transport http --method tools/list

提示：若未传递 --transport http，Inspector 会默认走 SSE 协议，此时控制台会捕获到 SSE error: Non-200 status code (400) 报错——这是引擎在没有建立合法 MCP 会话时按规范主动拒绝 SSE 式 GET 请求的正常防御机制。

Inspector 同时支持图形化浏览器视窗：

npx -y @modelcontextprotocol/inspector

在打开的网页中将 http://localhost:8125/mcp/ 填入 URL 字段，并选定 Streamable HTTP 作为 Transport。若页面提示 TypeError: NetworkError when attempting to fetch resource，这通常是由浏览器的跨域资源共享 (CORS) 拦截引起的（引擎当前未对外广播 Access-Control-Allow-Origin 响应头）。此时请直接改用上述第一种 CLI 命令行探测方式，或在关闭了安全跨域限制的浏览器环境中进行探测。

安装工作流编排技能库 (Workflow-construction skill)

引擎官方维护了一套 griptape-nodes-workflows 技能集 (Skill)，该文档能教会外部大语言模型智能体如何熟练调度上述暴露出的 MCP 工具链（包含冷启动流程设计、EventRequestBatch 批量事件批处理技巧以及常见排坑指南）。Claude Code、Cursor 与 VS Code 原生支持遵循 agentskills.io 规范的 name + description 元数据格式，只需将其下载至对应目录即可即刻加载。

官方发布的完整 Markdown 规范源文件地址：

https://docs.griptapenodes.com/en/stable/skills/griptape-nodes-workflows/SKILL/index.md

无论选择哪种作用域，目标文件夹名称必须且只能命名为 griptape-nodes-workflows（必须与文档元数据中的 name 字段严格一致），且文件本身必须命名为 SKILL.md。

各客户端支持的安装目录矩阵

目标客户端	项目专属作用域 (Project scope)	全局用户作用域 (User scope)
Claude Code	`.claude/skills/griptape-nodes-workflows/SKILL.md`	`~/.claude/skills/griptape-nodes-workflows/SKILL.md`
Cursor	`.cursor/skills/griptape-nodes-workflows/SKILL.md`	`~/.cursor/skills/griptape-nodes-workflows/SKILL.md`
VS Code (Copilot)	`.github/skills/griptape-nodes-workflows/SKILL.md`	`~/.copilot/skills/griptape-nodes-workflows/SKILL.md`

注：Cursor 与 VS Code 同样会自动探测 .agents/skills/（项目根目录）与 ~/.agents/skills/（用户主目录）；此外 VS Code 还能自动识别 .claude/skills/。若希望一个通用路径服务于本机安装的所有编辑器客户端，建议统一将其放置于 ~/.agents/skills/griptape-nodes-workflows/SKILL.md。

一键极速下载脚本

参照上表设定对应的 DEST 目录并运行以下命令：

DEST="$HOME/.claude/skills/griptape-nodes-workflows"
mkdir -p "$DEST" \
  && curl -fsSL https://docs.griptapenodes.com/en/stable/skills/griptape-nodes-workflows/SKILL/index.md \
       -o "$DEST/SKILL.md"

安装完成后，在聊天窗口中输入 /skills（适用于 Claude Code 或 VS Code）或在 Cursor 的 Customization 面板中查看 Skills 标签页，即可确认该能力已被外部智能体成功识别并装载！