Claix

Claix MCP 服务

为 Claix 托管的 MCP 服务。Claix 是 SQL 数据库与 AI Agent 之间的安全层。

通过 Streamable HTTP（以及旧版 SSE）将 Cursor、Claude、Windsurf、n8n、Make 或任何 MCP 客户端连接到 Claix。此服务的主要产品：Claix Retrieve（受控读取）和 Claix Guard（对拟议写入操作进行允许／拒绝判定）。Claix Ingest（文档 → JSON/Markdown）为辅助产品。

• 注册表： dev.claix/claix
• 端点： https://www.claix.dev/mcp
• 传输方式： Streamable HTTP 和旧版 SSE
• MCP 版本： 1.14.0
• 工具： 33
• 文档： https://www.claix.dev/documentation/mcp
• 服务卡片： https://www.claix.dev/.well-known/mcp/server-card.json
• Smithery： https://smithery.ai/server/info-f4xz/claix

Claix 是什么

Claix 位于 AI Agent 与 SQL 数据库（PostgreSQL、MySQL、MariaDB，以及 Supabase 等兼容 Postgres 的托管服务）之间。

产品	用途	MCP
Retrieve	受控读取：路由将表／列列入白名单；Agent 只能在此允许列表范围内作答	claix.routes.*、claix.agents.*、claix.retrieve.ask
Guard	应用执行 INSERT / UPDATE / DELETE 之前，Claix 会给出允许或拒绝的判定及原因。Claix 不会执行该语句	claix.guard.check → POST /check-sql
Ingest（辅助）	文档 → 经过架构验证的 JSON 或 Markdown；可选的多文档问答	claix.schemas.*、claix.extract.*、claix.agent.*、claix.markdown.*、claix.multi_document.ask

按使用量付费。使用 x-api-key 进行身份验证。

可以做什么

Claix Retrieve

创建路由和 Agent，然后提问。Agent 只读取其路由指定的表和列，并返回原始行（bruto）或类型化答案（razonada）。每次提问都会生成追踪记录（log_id）。

claix.routes.create
        ↓
claix.agents.create
        ↓
claix.retrieve.ask
        ↓
Typed answers from the live database

Claix Guard

Agent 提出一项写入操作。你的执行器先调用 Guard。由 Claix 作出判定；仅当 allowed 为 true 时，你的代码才执行 SQL。拒绝时 HTTP 状态仍为 200——务必检查 allowed。

Agent proposes INSERT / UPDATE / DELETE
        ↓
claix.guard.check   (sql, params?, connection_id?)
        ↓
{ allowed, reason, decision_id, … }
        ↓
Your app executes only if allowed === true

Claix Ingest（辅助）

列出或创建架构，然后将文件提取为 JSON、转换为 Markdown，或针对最多 10 个文件提出最多 5 个类型化问题。架构启用 Save Data（window_context）后，映射出的行可以插入已连接的数据库，响应中也可以包含 row_id。

claix.schemas.list
        ↓
claix.extract.pdf
        ↓
Structured JSON, and row_id when Save Data is on

快速开始

1. 获取 API 密钥

在 claix.dev 创建账户并生成 API 密钥。

x-api-key: YOUR_CLAIX_API_KEY

重要

请勿将 API 密钥放入公开代码仓库、屏幕截图、浏览器代码或提交历史中。

2. 从 Cursor 连接

打开 Cursor → Settings → MCP 并添加：

{
  "mcpServers": {
    "claix": {
      "url": "https://www.claix.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_CLAIX_API_KEY"
      }
    }
  }
}

或者从官方 MCP 注册表安装 dev.claix/claix（远程 URL https://www.claix.dev/mcp，请求头 x-api-key）。

3. 向 Retrieve Agent 提问

创建路由和 Agent 后（通过仪表板或 MCP 工具），调用 claix.retrieve.ask：

{
  "agent_name": "restaurant-ops",
  "questions": [
    {
      "question": "How many tables are reserved this Saturday between 20:00 and 22:00?",
      "format": "int"
    }
  ]
}

当 Agent 的 response_mode 为 razonada 时，必须提供 format。模式为 bruto 时，format 为可选项。可用格式：string、int、boolean、timestamp、timestamptz、date、json、array:string、array:int。每次调用最多可提问 5 个问题。

该调用对应 POST /retrieve/{agent_name}。

4. 使用 Guard 检查写入操作

在应用执行更改之前：

{
  "sql": "INSERT INTO shop.orders (customer_id, total) VALUES ($1, $2)",
  "params": ["c-1042", 6200],
  "connection_id": "8f14e45f-ceea-4e6f-8b23-1e2d3c4b5a6f"
}

调用 claix.guard.check。读取 allowed、reason 和 decision_id。Claix 不会执行 SQL。

5. 提取 PDF（可选的 Ingest）

调用 claix.schemas.list，然后使用 schema_id 和文件调用 claix.extract.pdf：

{
  "schema_id": "YOUR_SCHEMA_ID",
  "file_base64": "JVBERi0xLjQK..."
}

使用 Smithery 安装

npx -y @smithery/cli run info-f4xz/claix

{
  "mcpUrl": "https://www.claix.dev/mcp",
  "headers": {
    "x-api-key": "YOUR_CLAIX_API_KEY"
  }
}

连接 Claude Desktop

Claude Desktop 可以通过 mcp-remote 连接：

{
  "mcpServers": {
    "claix": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.claix.dev/mcp",
        "--header",
        "x-api-key:YOUR_CLAIX_API_KEY"
      ]
    }
  }
}

其他 MCP 客户端

任何能够向远程 MCP 服务发送自定义标头的客户端都可以使用：

{
  "url": "https://www.claix.dev/mcp",
  "headers": {
    "x-api-key": "YOUR_CLAIX_API_KEY"
  }
}

其中包括 Cursor、Claude Desktop、Claude Code、Windsurf、Cline、Continue、Zed、n8n、Make，以及支持 Streamable HTTP 或 SSE 的 LangChain 或 LangGraph 客户端。

如果客户端无法发送标头，工具也接受可选的 api_key 参数。建议优先使用标头。

身份验证

POST /mcp HTTP/1.1
Host: www.claix.dev
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: YOUR_CLAIX_API_KEY

传输方式

模式	常见用途	连接
Streamable HTTP	Cursor、Smithery、n8n、Make、当前的 MCP 客户端	POST https://www.claix.dev/mcp
Legacy SSE	通过 mcp-remote 连接的 Claude Desktop、较旧的会话客户端	GET /mcp，然后 POST /mcp/message?sessionId=...

两种模式使用相同的基 URL。claix.dev 会重定向到 www.claix.dev。

工具

类别	工具	用途
检索	claix.retrieve.ask	向 Agent 提问。POST /retrieve/{agent_name}
路由	claix.routes.create、claix.routes.edit、claix.routes.delete	将表/列加入白名单并设置路由规则
Agent	claix.agents.create、claix.agents.edit、claix.agents.pause	创建/编辑 Agent，或设置 paused / active
Guard	claix.guard.check	允许/拒绝拟议的写入操作。POST /check-sql。不会执行 SQL
架构（Ingest）	claix.schemas.list、get、create、update、delete	提取架构，包括 Save Data（window_context）
提取（Ingest）	claix.extract.excel、pdf、doc、image、text、audio	文件或文本 → 经过架构验证的 JSON
Agent 模式（Ingest）	claix.agent.excel、pdf、doc、image、text、audio	架构启用 Agent 模式时处理相同输入
Markdown（Ingest）	claix.markdown.excel、pdf、doc、image、text、audio	文件 → Markdown。可选的 save=true 可返回 row_id
多文档	claix.multi_document.ask	最多 10 个文件和 5 个带类型的问题。POST /multi-document
转换	claix.convert.json_to_excel	JSON → .xlsx

不要自行编造 schema_id、route_id、agent_id 或 connection_id。先列出或创建它们。

检索、Guard 检查、提取、Agent 模式和多文档工具会返回跟踪字段（视情况为 log_id / decision_id）。

工作流

向数据库提问（Retrieve）

claix.routes.create
→ claix.agents.create
→ claix.retrieve.ask

如果 Agent 已在仪表板中创建，也可以跳过前两步，直接使用其 slug 调用 claix.retrieve.ask。

检查写入操作（Guard）

claix.guard.check
→ read allowed / reason
→ your executor runs SQL only if allowed

提取 PDF（Ingest，次要）

claix.schemas.list
→ claix.extract.pdf

跨多个文件提问

claix.multi_document.ask

提示词

prompts/list 包含：

• workflow.retrieve-ask
• workflow.guard-check
• workflow.discover-and-extract
• workflow.agent-document-analysis
• workflow.invoice-pdf
• workflow.markdown-save
• workflow.multi-document-ask

资源

• MCP 文档：claix://docs/mcp
• OpenAPI 规范：claix://docs/openapi
• 工具目录：claix://docs/tools
• 服务卡片：https://www.claix.dev/.well-known/mcp/server-card.json
• 产品指南：https://github.com/claix-dev/claix-for-devs
• 完整文档：https://www.claix.dev/documentation/mcp

安全

• 将 API 密钥存储在客户端的机密存储中或环境变量中。
• 优先使用 x-api-key 标头，而不是每个工具的 api_key 参数。
• claix.schemas.delete、claix.routes.delete 和暂停 Agent 都会更改账户。调用前请先确认。
• Retrieve 使用你所连接的只读数据库角色。
• Guard 仅检查拟议的写入。你的执行器持有写入凭据，必须遵守 allowed。

官方注册表

已在 MCP Registry 中以 dev.claix/claix 发布。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.claix/claix"

链接

• 网站：https://www.claix.dev
• MCP 文档：https://www.claix.dev/documentation/mcp
• Retrieve：https://www.claix.dev/documentation/call-an-agent
• Guard：https://www.claix.dev/documentation/check-sql
• 服务卡片：https://www.claix.dev/.well-known/mcp/server-card.json
• Smithery：https://smithery.ai/server/info-f4xz/claix
• 此仓库：https://github.com/claix-dev/claix-mcp