# MCP 服务器

> 用一个 URL 和你的 API 密钥，把 Claude、Cursor、Codex 或任何 MCP 客户端接到一家餐厅的合规记录上。

Source: https://developers.backresto.com/zh/docs/mcp

BackResto 在 `https://api.backresto.com/mcp` 运行着一个 **Model Context Protocol** 服务器。用你的 API 密钥把你的 AI 工具接上去，就能在工具自己的界面里询问一家餐厅的记录：不用写代码，我们这边不用安装任何东西，你那边也不用托管任何东西。

它通过和其他一切相同的合作方 API 读取数据，用的是同一把密钥。**它看不到任何这把密钥原本就看不到的东西**：按餐厅和按权限范围的授权由 API 执行，而不是由你接入的工具执行。

## 接入你的工具

你首先需要一把密钥，见[获取密钥](https://developers.backresto.com/zh/docs/access)。然后选择你的工具：

### Claude

1. **添加自定义连接器**: 在 Claude 里（桌面应用或 claude.ai 均可），打开 Customize，再进入 Connectors，点击 Add custom connector。如果是 Team 或 Enterprise 套餐，需要所有者先在组织设置里添加一次。

2. **命名并粘贴地址**: 把它命名为 BackResto，粘贴下面的 URL。在“身份验证”和“OAuth 客户端”中，Claude 会检测到我们的服务器，并预先选中“立即登录”和“自动注册”：保留这两项。不要填写客户端 ID 或密钥。然后点击添加。

```
https://api.backresto.com/mcp
```

3. **用你的密钥连接**: 点击 Connect。会打开一个 BackResto 页面：粘贴以 brp_ 开头的密钥，点击连接。回到 Claude 后，连接器已启用，带有五个工具。

4. **完成**: 用平常的话询问这家餐厅记录下来的内容。这把密钥已经知道哪家餐厅是你的。

### Claude Code

1. **注册服务器**: 打开终端运行这条命令，把 brp_YOUR_KEY 换成你的密钥。

```sh
claude mcp add --transport http --scope user backresto \
  https://api.backresto.com/mcp \
  --header "Authorization: Bearer brp_YOUR_KEY"
```

2. **检查连接**: 启动 Claude Code 并输入 /mcp。backresto 会显示为已连接，带有五个工具。

3. **完成**: 用平常的话询问这家餐厅记录下来的内容。这把密钥已经知道哪家餐厅是你的。

### Cursor

1. **打开 MCP 设置**: 在 Cursor 里依次进入 Settings、Tools & MCP，点击 New MCP Server，会打开 mcp.json。

2. **添加服务器**: 把下面的内容粘进 mcp.json，把 brp_YOUR_KEY 换成你的密钥。服务器会带着五个工具出现在列表里。

```json
{
  "mcpServers": {
    "backresto": {
      "type": "http",
      "url": "https://api.backresto.com/mcp",
      "headers": {
        "Authorization": "Bearer brp_YOUR_KEY"
      }
    }
  }
}
```

3. **完成**: 用平常的话询问这家餐厅记录下来的内容。这把密钥已经知道哪家餐厅是你的。

### Codex

1. **把密钥放进环境变量**: Codex 从环境变量而不是配置文件里读取 bearer 令牌。把这一行加进你的 shell 配置文件，把 brp_YOUR_KEY 换成你的密钥。

```sh
export BACKRESTO_API_KEY="brp_YOUR_KEY"
```

2. **注册服务器**: 然后运行一次这条命令。Codex 会把这个变量的值作为 Authorization 请求头发送。

```sh
codex mcp add backresto \
  --url https://api.backresto.com/mcp \
  --bearer-token-env-var BACKRESTO_API_KEY
```

3. **完成**: 用平常的话询问这家餐厅记录下来的内容。这把密钥已经知道哪家餐厅是你的。

### 其他

1. **打开你的工具的 MCP 设置**: 找到 MCP 或集成设置，添加一个使用 Streamable HTTP 的远程服务器。如果你的工具只要求填写 URL，它会打开一个 BackResto 页面让你粘贴密钥，就不需要请求头了。

2. **填写地址**: 这是服务器的 URL。

```
https://api.backresto.com/mcp
```

3. **把密钥作为请求头添加**: 每次请求都把它作为 Authorization 请求头发送。

```
Authorization: Bearer brp_YOUR_KEY
```

4. **完成**: 用平常的话询问这家餐厅记录下来的内容。这把密钥已经知道哪家餐厅是你的。

## 这些工具

五个工具：一个找到餐厅，另外四个读取它的[集合](https://developers.backresto.com/zh/docs/collections)。

| 工具 | 它做什么 |
| --- | --- |
| `backresto_list_restaurants` | 列出这把密钥能触及的餐厅，以及它在每家餐厅上的权限范围。 |
| `backresto_list_collections` | 列出这把密钥被授予的那些集合，以及打开每一个的权限范围。当你不知道这把密钥能触及什么时，这是该先调的那个。 |
| `backresto_list_records` | 从一个集合里读一页记录，包含 tombstone。接受 `collection`，以及可选的 `limit`（1-100，默认 50）和 `cursor`。 |
| `backresto_get_record` | 按 `collection` 和 `recordId` 取回一条记录。 |
| `backresto_list_record_assets` | 以签名 URL 列出附在一条记录上的文件（`cleaning-task-pictures`、`delivery-pictures`、`traceability-labels` 或 `drive-files`），并把照片作为模型能直接查看的图片展示给它。 |

收货记录就是其中的两个集合，`deliveries` 和 `delivery-pictures`，用和其他一切相同的工具来读。它们的字段是什么意思，见[收货记录](https://developers.backresto.com/zh/docs/deliveries)。

`restaurantId` 在所有工具上都是可选的。不填，就使用这把密钥自己的餐厅，所以一家只有一把密钥的餐厅永远不需要知道自己的标识符。只有触及多家餐厅的密钥才需要选择，而错误信息会列出可选项。

这五个工具都声明为只读且幂等，所以一个规矩的客户端不会像对待会写入的工具那样，每次调用都来征求你的许可。

两条实际的限制。照片为模型内联展示的上限是每次调用 `backresto_list_record_assets` **十张图片、约 7.5 MB**；超出的部分仍会出现在摘要里，带着它的 URL 和没有被展示的原因。另外整个端点与合作方 API 共用每把密钥每分钟 300 个请求的[额度](https://developers.backresto.com/zh/docs/rate-limits)：一次工具调用就是一个请求，一场对话永远碰不到它，一个循环会。

## 保护好密钥

这把密钥就是你全部的访问权限，而 MCP 客户端的配置只是笔记本电脑上的一个普通文件。

- **永远不要提交这个文件。** 如果你的工具把配置放在代码仓库里，请改为引用环境变量或操作系统的密钥库，就像上面的 Codex 配置那样。
- **给每台机器单独一把密钥。** 一台笔记本一把密钥，意味着丢一台笔记本只需吊销一把，而不是把你所有集成都轮换一遍。
- **怀疑某处还留着一份副本时，问我们一把密钥最后一次是什么时候用的。** 我们能看到每把密钥最后一次认证的时间，而吊销也是同一封邮件。

## 只用 URL 连接

Claude（桌面应用和 claude.ai）、ChatGPT 以及其他只需要填写服务器 URL 的工具通过 OAuth 接入：它们会自行向 BackResto 注册，然后打开一个 BackResto 页面，你在上面粘贴一次密钥即可。无需安装任何东西，也没有配置文件。工具会保存密钥并替你发送，因此它能访问的范围与密钥完全一致，吊销密钥就会断开它。

目前还不能用 BackResto 账号登录：凭证仍然是密钥。如果这正是横在你和一次集成之间的东西，就说出来：它会往前排。

## 它擅长什么

具体地说，接上这些工具之后，一位运营负责人可以问：

- *「上个月有哪些收货被拒收了，为什么？」*
- *「把这个季度所有高于 4 °C 的鸡肉收货给我看看。」*
- *「把周二被拒收那批货的照片给我看看：损坏看得出来吗？」*
- *「哪些冰箱最经常超出温度范围，在哪个区域？」*
- *「上周的冷却循环是不是都按时降下来了？」*
- *「哪些清洁任务被跳过了，哪些没有照片？」*

前三个读的是 `deliveries` 和 `delivery-pictures` 这两个集合，其余的读的是其他[集合](https://developers.backresto.com/zh/docs/collections)，而且每一个都只读你的密钥被授予的那些。答案来自检查员会读的同一批记录，经由餐厅签发的同一批授权。

一个在读集合的模型，应该被告知它读的是什么：这是这个 API 所收到内容的一份快照，不是一份保证完整的历史。如果你把它摆到客户面前，请把这句话一起摆过去。