cQnce MCP

@cqnce/mcp-server

cQnce 的官方 MCP 服务 — 为任何 AI Agent 或工作流添加人工介入授权。

将 Claude、Cursor、GitHub Copilot 或任何兼容 MCP 的客户端连接到 cQnce，让 AI 在执行有风险或不可逆的操作前请求人工批准。

快速开始

npx @cqnce/mcp-server

运行前，请将项目 API 密钥设置为 CQNCE_API_KEY 环境变量。

审批模式

模式 1 — Agent 请求审批

Agent 按照系统提示词或通过工具发现的指示，自行调用 wait_for_approval 或 submit_authorization_request。这是最简单的集成方式，适用于有人监督的工作流。

风险： 受到入侵或配置错误的 Agent 可能根本不会调用该工具。

模式 2 — 强制审批关卡（生产环境推荐）

宿主应用或执行器会在每次敏感工具调用运行 之前 拦截它，并要求先获得 cQnce 审批，无论 Agent 请求了什么。审批关卡位于模型上下文之外 — Agent 无法绕过它。

这是一个真正的安全边界。企业级和对合规要求敏感的集成应采用此模式。

# Example: host-side interception (framework-agnostic)
HIGH_RISK_TOOLS = {"send_payment", "deploy_production", "delete_customer"}

def execute_tool_call(tool_call):
    if tool_call.name not in HIGH_RISK_TOOLS:
        return run_tool(tool_call)
    decision = cqnce.submit_and_wait(
        payload={"action": tool_call.name, "parameters": tool_call.arguments},
        timeout_seconds=300,
    )
    if decision["status"] != "APPROVED":
        return {"error": "not_authorized", "status": decision["status"]}
    return run_tool(tool_call)

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "cqnce": {
      "command": "npx",
      "args": ["-y", "@cqnce/mcp-server"],
      "env": {
        "CQNCE_API_KEY": "your-project-api-key"
      }
    }
  }
}

Cursor

添加到项目中的 .cursor/mcp.json（或全局配置 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "cqnce": {
      "command": "npx",
      "args": ["-y", "@cqnce/mcp-server"],
      "env": {
        "CQNCE_API_KEY": "your-project-api-key"
      }
    }
  }
}

任意 MCP 客户端（stdio 传输）

CQNCE_API_KEY=your-project-api-key npx @cqnce/mcp-server

云端 Agent（Streamable HTTP / 远程 MCP）

对于无法运行本地进程的云端托管 Agent，请使用部署在 Cloudflare Workers 上的 cQnce MCP Worker。它使用 MCP Streamable HTTP transport，且为无状态服务 — 每个请求都会使用你的 API 密钥进行身份验证。

将云端 Agent 框架配置为连接到：

https://mcp.cqnce.app/mcp
Authorization: Bearer <your-project-api-key>

示例（使用 MCP 的 Claude API）：

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.cqnce.app/mcp",
            "name": "cqnce",
            "authorization_token": "your-project-api-key",
        }
    ],
    messages=[{"role": "user", "content": "..."}],
    betas=["mcp-client-2025-04-04"],
)

自行托管

Worker 源代码位于此仓库中。将你自己的实例部署到 Cloudflare Workers：

npm install
npx wrangler deploy

如果使用私有 cQnce 部署，请在 Cloudflare 控制面板中设置 CQNCE_BASE_URL（默认值为 https://api.cqnce.app）。

配置

变量	必填	描述
CQNCE_API_KEY	是	来自 cqnce.app 的项目 API 密钥
CQNCE_BASE_URL	否	API 基础 URL（默认值：https://api.cqnce.app）
CQNCE_ADMIN_TOKEN	否	租户管理员 JWT — 启用项目／Agent／团队管理工具

工具

核心工具（需要 CQNCE_API_KEY）

工具	描述
wait_for_approval	提交请求并阻塞等待，直到人工批准或拒绝。这是人工介入工作流的主要工具。
submit_authorization_request	提交请求并立即返回 requestId（非阻塞）。
poll_request_status	根据 ID 检查请求的当前状态。
cancel_request	取消待处理的请求。
list_requests	列出此项目的请求（可按状态、日期和标签筛选）。
get_request	获取单个请求的完整详情，包括 Agent 响应。

管理工具（需要 CQNCE_ADMIN_TOKEN）

项目管理、路由规则配置、Agent／团队管理和 Webhook 回调。

推荐的系统提示词

通过 Anthropic API 集成 Claude 时，添加此系统提示词以自动强制执行授权策略 — 无需依赖用户每次都提出请求：

You have access to the cQnce tool for human-in-the-loop authorization.

ALWAYS call wait_for_approval BEFORE performing any action that is:
- Destructive or irreversible (deleting data, dropping tables, removing files)
- Affecting production systems (deployments, database migrations, config changes)
- Financial (payments, transfers, subscription changes)
- Involving credentials or access control (creating/revoking API keys, changing permissions)

In the approval payload, include:
- "action": what you are about to do
- "target": what resource is affected
- "reason": why this action is needed
- "risk": what happens if approved or rejected
- "attachments": (optional) list of supporting files as { name, contentType, data (base64) }
  — include logs, diffs, screenshots, or any evidence that helps the reviewer decide

When the response status is "REJECTED":
- Read the rejection reason carefully.
- If the reason identifies missing information or context, gather that information,
  enrich the payload (or attachments), and resubmit via wait_for_approval.
- Only give up if the rejection reason makes clear the action itself is not permitted.

Proceed ONLY if the returned status is "APPROVED".
If "EXPIRED" or the rejection reason leaves no actionable path forward, stop and explain.

示例

配置完成后，你可以这样告诉 Claude：

“删除生产数据库之前，请通过 cQnce 请求人工批准。”

Claude 会使用操作详情调用 wait_for_approval，暂停等待人工通过 cQnce 移动应用批准或拒绝，并且只有在状态为 APPROVED 时才会继续。如果请求被拒绝并附有理由（例如“缺少回滚计划”），Claude 会收集相关信息并自动重新提交。

要求

• Node.js 18+
• cQnce 账户和项目 API 密钥 — 免费注册