MCP 协议

通过 MCP 协议，让 AI Agent 直接访问你在 PuppyOne 中的数据。

什么是 MCP

MCP（Model Context Protocol） 是 Anthropic 提出的开放协议，定义了 AI 模型如何与外部工具和数据源交互。它是 Agent 生态中正在成为标准的「连接器协议」。

PuppyOne 提供托管的 MCP Server——你只需创建一个 MCP 端点，就能获得一个独立的 URL 和 API Key。任何支持 MCP 的客户端都可以通过这个端点读写你的数据。

工作原理

┌─────────────────┐     MCP 协议      ┌──────────────────┐
│    AI Agent      │ ◄──────────────► │    PuppyOne      │
│  (Cursor 等)     │   工具调用 / 响应  │   MCP Server     │
└─────────────────┘                   └──────────────────┘
                                             │
                                     读写 Content Node
                                             │
                                      ┌──────▼──────┐
                                      │   Project    │
                                      │  数据文件树   │
                                      └─────────────┘

你在 PuppyOne 中创建一个 MCP 端点，获得 Server URL
在客户端（Cursor、Claude Desktop 等）中配置这个 URL
客户端自动发现可用的工具（查询、创建、修改、删除等）
Agent 通过工具调用读写你的 Content Node 数据

MCP Server URL

每个 MCP 端点有一个独立的 URL，格式为：

https://api.puppyone.ai/api/v1/mcp/server/{API_KEY}

API Key 嵌入在 URL 中，客户端连接时无需额外配置认证。

兼容客户端

PuppyOne 的 MCP Server 兼容所有支持 MCP 协议的客户端：

客户端	说明
Cursor	AI 编程 IDE，在设置中配置 MCP Server
Claude Desktop	Anthropic 官方桌面应用
Claude Code	命令行 AI 编程工具
Cline	VS Code 中的 AI 编程助手
Continue	开源 AI 编程助手
Zed	高性能代码编辑器

以及任何其他支持 MCP 协议的客户端。

可用工具

连接 MCP 端点后，Agent 可以调用以下工具操作你的数据：

工具	类型	说明
`get_data_schema`	读取	获取数据结构（Schema）
`get_all_data`	读取	获取全部数据
`query_data`	读取	按条件查询数据
`preview`	读取	预览数据内容
`select`	读取	选取指定路径的数据
`create`	写入	创建新内容
`update`	写入	修改已有内容
`delete`	写入	删除内容

创建 MCP 端点

通过 Dashboard

进入项目页面 → 点击侧边栏「Connections」
点击「New」→ 选择「MCP」
输入端点名称，配置访问权限
创建完成后复制 Server URL

通过 CLI

$ puppyone conn add mcp "产品知识库"
✓ MCP endpoint created
  Server URL: https://api.puppyone.ai/api/v1/mcp/server/sk_live_xxxxxxxxxxxx

客户端配置

Cursor

在 Cursor 的 MCP 设置中添加以下配置（Settings → MCP → Add new MCP server）：

{
  "mcpServers": {
    "puppyone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.puppyone.ai/api/v1/mcp/server/sk_live_xxxxxxxxxxxx"
      ]
    }
  }
}

Claude Desktop

编辑 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "puppyone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.puppyone.ai/api/v1/mcp/server/sk_live_xxxxxxxxxxxx"
      ]
    }
  }
}

Claude Code

在项目目录下运行：

claude mcp add puppyone -- npx -y mcp-remote https://api.puppyone.ai/api/v1/mcp/server/sk_live_xxxxxxxxxxxx

配置完成后，重启客户端即可看到 PuppyOne 提供的工具。

File Level Security (FLS)

每个 MCP 端点可以配置独立的 FLS 规则，精确控制 Agent 的访问范围：

工具权限

控制 Agent 可以调用哪些工具。例如，只开放读取工具而禁止写入：

✓ get_data_schema
✓ get_all_data
✓ query_data
✗ create
✗ update
✗ delete

路径权限

控制 Agent 可以访问哪些 Content Node 路径。未授权的路径对 Agent 完全不可见：

✓ /products          → 可以读取产品数据
✓ /faq               → 可以读取 FAQ
✗ /internal          → 不可见
✗ /financials        → 不可见

通过组合工具权限和路径权限，你可以为不同场景创建不同的 MCP 端点——客服 Agent 只读产品和 FAQ，研发 Agent 可读写技术文档，管理 Agent 有完整访问权限。

最佳实践

一个场景一个端点 — 为不同的 Agent 或客户端创建独立的 MCP 端点，配置不同的权限
遵循最小权限原则 — 只开放 Agent 实际需要的工具和路径
先只读，后开写 — 新端点先只配置读取工具，验证无误后再按需开放写入
妥善保管 API Key — API Key 等同于访问凭证，不要提交到公开仓库或分享给不信任的第三方

统一连接概览