# 让 AI 客户端通过 MCP 调用 AskTable

通过 MCP 将 AskTable 的查询和管理能力提供给 AI 客户端。

AskTable 的 MCP Server 把问数和管理能力按 Model Context Protocol 暴露成工具，让 Claude、MCP Inspector 等支持 MCP 的 AI 客户端直接调用。它是单一 server（名字 `asktable`），共 43 个工具。MCP 不绕过 AskTable 的权限：客户端能调什么，仍由 API-Key 类型和项目权限决定。

## 开始前

- 一个 AskTable 项目和项目 API-Key。只要问数用 `asker`；要调管理类工具用 `admin`。
- 创建位置：左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」，弹窗里选类型。
- 客户端支持 Streamable HTTP 或 stdio。生产接入用 HTTP。
- 地址要先确认清楚，三种部署不一样，见下。
- 界面入口：底部头像 → 「文档」 → 「MCP 服务」，会按当前部署打开对应地址。

## 操作步骤

**确认你的 MCP 地址**

| 部署方式                             | 地址                              |
| -------------------------------- | ------------------------------- |
| SaaS（cloud.asktable.com）         | `https://mcp.asktable.com/`     |
| 私有部署，一体化镜像（容器内 nginx 反代 `/mcp/`） | `https://<你的 AskTable 站点>/mcp/` |
| 私有部署，独立 `asktable-mcp` 容器        | `http://<mcp-host>:8690/`       |

独立容器的 HTTP transport 接受任意路径，不要求 `/mcp/` 前缀；一体化镜像对外只暴露 `/mcp/`，nginx 会剥掉前缀再转给 8690。

**在客户端里填地址和 Key**

Streamable HTTP 的配置（字段名以你的客户端为准）：

```json
{
  "mcpServers": {
    "asktable": {
      "type": "http",
      "url": "https://mcp.asktable.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

`Authorization` 头是必传的。服务端每个请求构造独立的客户端实例，不跨租户持有状态。

**确认客户端能列出工具**

连上后让客户端列出工具，应该看到 43 个。按域分组如下：

| 域            | 工具                                                                                                                                                   | 数量 |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| datasource   | `datasource_list`、`datasource_get`、`datasource_create`、`datasource_update`、`datasource_delete`、`datasource_upload_file`、`datasource_test_connection` | 7  |
| meta         | `datasource_meta_get`、`datasource_meta_export`、`meta_sync`、`meta_import`                                                                             | 4  |
| training     | `training_pair_list`、`training_pair_create`、`training_pair_update`、`training_pair_delete`                                                            | 4  |
| field        | `field_set_visibility`、`field_set_description`、`field_set_ai_value_index`                                                                            | 3  |
| table        | `table_set_description`                                                                                                                              | 1  |
| role         | `role_list`、`role_get`、`role_create`、`role_update`、`role_delete`                                                                                     | 5  |
| policy       | `policy_list`、`policy_get`、`policy_create`、`policy_update`、`policy_delete`                                                                           | 5  |
| chat         | `chat_ask`、`chat_followup`                                                                                                                           | 2  |
| conversation | `conversation_list`、`conversation_get`、`conversation_delete`                                                                                         | 3  |
| data\_agent  | `data_agent_list`、`data_agent_get`、`data_agent_create`、`data_agent_update`、`data_agent_delete`                                                       | 5  |
| project      | `project_get`、`project_preference_get`、`project_update`、`project_preference_update`                                                                  | 4  |

列表类工具接受 `page` 和 `size`（`size` 上限 200），不传就走后端默认。

**用 chat\_ask 问一次，再用 chat\_followup 追问**

让客户端调用 `chat_ask` 发起提问。需要多轮时用 `chat_followup` 接上一次的对话。客户端提供 `progressToken` 时，这两个工具会在每次轮询之间发进度通知。

删除类工具（`*_delete`）的入参强制要求 `confirm` 为 `true`，不传会被判为参数错误。

**本机调试时改用 stdio**

需要单独调试或用 MCP Inspector 时，在 `mcp/` 目录下起 stdio：

```bash
bun src/main.ts --stdio
```

stdio 模式下 Key 从环境变量取：

```bash
export ASKTABLE_API_URL='https://<你的 AskTable 站点>'
export ASKTABLE_API_KEY='YOUR_API_KEY'
```

服务端用 `ASKTABLE_API_URL` 指向 AskTable 的 API，默认值是 `https://api.asktable.com`；一体化镜像里它被设为 `http://127.0.0.1:8688`，走同容器 localhost。

**上生产前收口凭证**

客户端配置文件通常会被同步或备份。生产环境用客户端的密钥管理能力注入 `Authorization`，不要把 Key 明文留在配置仓库里。Key 泄露时立即到「设置」 → 「API-Key」删除该 Key 并重建。

## 关键约束

| 项目                 | 值或默认                                       | 在哪里改                                                     |
| ------------------ | ------------------------------------------ | -------------------------------------------------------- |
| server 名称与工具数      | 单一 `asktable`，43 个工具                       | 无界面开关                                                    |
| 云端地址               | `https://mcp.asktable.com/`                | 底部头像 → 「文档」 → 「MCP 服务」                                   |
| 私有部署（一体化镜像）        | `<你的站点>/mcp/`                              | 见[私有部署（Docker）](https://docs.asktable.com/deploy/docker) |
| 私有部署（独立容器）         | `http://<mcp-host>:8690/`                  | 容器的 `ports` 与 `ASKTABLE_API_URL`                         |
| 认证                 | `Authorization: Bearer <API-Key>`，必传       | 客户端配置                                                    |
| `ASKTABLE_API_URL` | 默认 `https://api.asktable.com`              | MCP 容器的环境变量                                              |
| 列表分页 `size`        | 上限 200，不传走后端默认                             | 工具入参                                                     |
| 删除类工具              | 必须显式传 `confirm: true`                      | 工具入参                                                     |
| 审计日志               | 每次调用写一行 JSON 到 stderr，Key 只留 sha256 前 16 位 | 容器日志                                                     |
| 生产传输方式             | Streamable HTTP；stdio 只用于本机调试              | 启动参数                                                     |

## 出问题怎么判断

| 现象                                          | 判定条件                         | 处理                                                     |
| ------------------------------------------- | ---------------------------- | ------------------------------------------------------ |
| 客户端报 `InvalidRequest`                       | 服务端把 HTTP 401 或 404 映射成这个错误  | 检查 `Authorization` 头是否带 `Bearer ` 前缀、Key 是否有效、URL 是否写对 |
| 客户端报 `InvalidParams`                        | 服务端把 HTTP 422 映射成这个错误        | 参数类型或必填项不对，按工具 schema 改正                               |
| 客户端报 `InternalError`                        | 上游返回其他状态码                    | 看错误对象里保留的 `httpStatus`；再到 AskTable 服务日志里按时间关联          |
| 调 `*_delete` 报参数错误                          | 入参里没有 `confirm: true`        | 显式传 `confirm: true`                                    |
| 独立容器连不上                                     | `http://<mcp-host>:8690/` 不通 | 确认容器端口已发布、`ASKTABLE_API_URL` 指向可访问的后端                  |
| 一体化镜像里 `/mcp/` 404                          | 容器内 8690 没起来                 | 看容器内 `mcp-server` 进程与 nginx 反代配置                       |
| 调 `meta_sync` 立刻返回 `{"status":"triggered"}` | 没传 `wait`                    | 这是预期行为；要等结果就传 `wait`、`poll_interval_ms`、`max_attempts` |
| 列表工具返回的条数少于预期                               | 没传 `size`，走了后端默认分页           | 显式传 `size`（上限 200）和 `page`                             |
| 客户端一直收不到进度                                  | 客户端没提供 `progressToken`       | 进度通知只在客户端带 `progressToken` 时发送                         |

## 下一步

- 在终端里直接操作 AskTable：[命令行工具](https://docs.asktable.com/integrations/cli)
- 自己处理请求和响应，不经过 AI 客户端：[OpenAPI](https://docs.asktable.com/integrations/openapi)
- 私有部署单独跑 MCP 容器：[私有部署（Docker）](https://docs.asktable.com/deploy/docker)