contextq-mcp

@contextq/mcp

ContextQ 的 MCP 服务——将 ContextQ 知识管理 API（89 个工具：保存、搜索、摄取、目标图谱、Agent 会话、中继等）作为模型上下文协议工具提供。连接时会加载精选的约 24 个工具作为默认集合，以降低 tools/list 的令牌成本；其余工具可按需加载，或通过 CONTEXT_MCP_TOOL_PROFILE=full 加载——参见下文。

npx -y @contextq/mcp

客户端配置

每个客户端都需要设置两个环境变量：

变量	说明
CONTEXT_API_URL	ContextQ 服务的基础 URL（例如 https://ctx.example.com）
CONTEXT_API_KEY	每次请求中作为 Authorization: Bearer 发送的 API 密钥

可选：

变量	说明
CONTEXT_MCP_TOOL_PROFILE	default（未设置时的默认值）会在连接时加载精选的约 24 个工具，远低于大多数主机的舒适工具列表预算；full 会从一开始就加载全部约 89 个工具。使用 default 时，其余工具仍可通过 ctx_tool_groups（列出）/ ctx_load_tool_group（加载）工具访问，无需重新连接——参见 docs/mcp-tools.md 中的“ToolSearch 延迟加载下的可发现性”

配置方式：Claude Code 和 Claude Desktop 可通过 contextq init CLI 命令自动配置。Cursor、Windsurf 和 Cline 需要手动编辑配置文件——完整参考请参见 docs/mcp-setup.md。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

Claude Code

claude mcp add contextq \
  -e CONTEXT_API_KEY=sk_live_YOUR_API_KEY \
  -e CONTEXT_API_URL=https://ctx.example.com \
  -- npx -y @contextq/mcp

Cursor

添加到 Cursor MCP 配置（.cursor/mcp.json 或“设置”>“MCP”）：

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

Windsurf

状态（2026-06-02）：Windsurf 已更名为 Devin Desktop，Cascade 已于 2026-07-01 终止服务。如果你已安装 Windsurf，以下配置仍然适用；但新安装应改用 Devin Desktop。Devin Desktop 在 .devin/mcp.json 中使用相同的 MCP 配置格式。

添加到 Windsurf MCP 配置（.windsurf/mcp.json）：

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

发送哪些数据及租户隔离

• 只会发送 Agent 发出的请求。 MCP 服务是无状态代理——它会通过 CONTEXT_API_URL 将每次工具调用转发至 ContextQ API，并返回响应。没有遥测数据、后台同步，也不会跟踪使用情况；ContextQ 服务记录的内容除外。
• API 密钥受租户范围限制。 每个 ContextQ API 密钥都绑定到单个租户。所有 /api/* 端点都会强制执行租户隔离——API 密钥只能访问其签发对象所在的租户。在 API 层面不可能发生跨租户数据泄露。
• 每次请求均需验证身份。 每次调用都会在 Authorization: Bearer 请求头中发送你的 CONTEXT_API_KEY。它绝不会出现在返回给大模型的工具名称、参数架构或响应中。

客户端超时配置

少数 ContextQ 工具会在服务器端运行 LLM 调用、kNN 扫描或批量 DB 操作，耗时可能确实超过典型 MCP 客户端的默认请求超时。如果客户端在服务器响应前中止，你会看到一个看起来像是工具故障的超时错误——但通常并非如此。请为此 MCP 服务配置更长的单服务器超时时间，而不是认为工具卡住了。

慢速工具（建议延长超时时间，例如根据工作区大小设置为 120000-180000 ms）：

工具	耗时较长的原因
ctx_dream	通过向量相似度对工作区中的上下文进行聚类，然后为每个簇运行一次 LLM 综合调用。
ctx_evolve	对最多 20 个最近邻上下文运行 LLM 评判，以决定链接或归档。
ctx_ingest	获取/解析来源，并运行 LLM 声明提取和 kNN 差异分析。大型摄取或 URL 来源的摄取会返回 { jobId, statusUrl }，并要求通过 ctx_ingest_status 轮询——但小型内联摄取仍会同步运行，可能耗时数秒。
ctx_regenerate_mocs	重新对某个租户的所有上下文进行聚类，并为每个簇运行一次 LLM 综合调用（管理员范围）。
ctx_memory_review_run	对较旧的上下文进行抽样，并要求 LLM 逐条给出判定（超级管理员范围）。
ctx_bulk_update	在一次调用中对最多 200 个上下文 ID 应用生命周期/归档补丁——有数量限制，但仍比更新单行耗时更长。
ctx_audit_cleanup_run	一次性删除最多 5000 条 activity_logs 记录（超级管理员范围）。
ctx_snapshot_create / ctx_fork_world / ctx_diff_world	克隆或比较工作区的完整记忆状态（上下文、链接、目标图）——耗时随工作区大小增加。

其他所有工具（ctx_search、ctx_get、ctx_save、ctx_list、agent_*、goal_*、relay_* 等）都是常规 CRUD/搜索操作，通常应能在客户端默认超时时间内完成。

这些数值只是起点，并非保证值——实际延迟取决于 ContextQ 服务的硬件、工作区大小以及配置的大模型/嵌入提供方。请先在自己的部署环境中测量，再调整设置。

.mcp.json 中按服务设置 request_timeout_ms

大多数支持 .mcp.json 的 MCP 客户端（包括 Claude Code）都接受按服务设置的 request_timeout_ms，以覆盖该服务上所有工具调用的客户端默认请求超时时间：

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      },
      "request_timeout_ms": 120000
    }
  }
}

request_timeout_ms 按服务生效，而非按工具生效——如果你经常调用慢速工具，请根据预计会遇到的最慢工具设置超时时间，而不是按平均耗时设置。Claude Code 2.1.206 修复了该字段被静默忽略的错误（无论设置如何，都会应用 60s 的默认值）；如果设置似乎没有生效，请确认 Claude Code 版本至少为 2.1.206。

Claude Code 空闲超时

除了 request_timeout_ms，Claude Code（2.1.187+）还会强制执行 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT——一个空闲中止超时（默认约为 5 分钟），如果 MCP 工具调用在此期间没有产生任何活动，就会触发。使用大型工作区调用慢速工具时，请在 shell 环境（而非 .mcp.json）中设置此变量：

export CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=300000   # milliseconds; raise if ctx_dream/ctx_ingest still time out

这两项设置都只是关于任何给定调用耗时的建议，并非保证。

API 版本兼容性

此 MCP 服务公开的 99 个工具接口直接映射自 ContextQ API（默认加载 24 个，其余工具通过 CONTEXT_MCP_TOOL_PROFILE=full 或按需加载——参见上文“客户端配置”）。工具数量和签名会随服务版本变化。请固定兼容版本：

MCP 包	ContextQ 服务 API
@contextq/[email protected]	ContextQ v2.x（99 个工具）

升级 ContextQ 服务时，请查看更新日志，并将 MCP 包升级到匹配的主版本。版本不匹配可能导致出现未知工具或调用签名失效。

许可证

MIT