vectros-ai

@vectros-ai/mcp-server

一键安装徽章会在你的客户端中安装 服务入口。你仍需提供密钥——运行 npx -y @vectros-ai/cli bootstrap（推荐），或粘贴你的 ssk_...。请参阅从客户端连接和坦诚说明。

一个用于 Vectros 的模型上下文协议服务——Vectros 是一个类型化、多租户的记录存储，统一了混合搜索与基于引用的 RAG。它可在一个按客户隔离的记录和文档索引中，执行确定性查询与枚举，以及语义搜索——让 Agent 获得精确而非仅模糊的记忆。Agent 可在此通过 MCP 原生访问（Claude Desktop、Cursor、Claude Code、Cline、Continue、VS Code、托管平台）；同一数据也可通过 Vectros 应用和 SDK 供人类访问。

npx -y @vectros-ai/mcp-server

你的 Agent 可以搜索已建立索引的语料库、查询结构化记录、摄取文档，并提出基于文档内容的问题——只能访问你所在租户的数据，绝不会访问公共网络（这里没有网页工具）。

快速开始 — 一条命令

最快的设置方式是使用 @vectros-ai/cli 的 bootstrap 命令。它会创建一个绑定到受限 AccessProfile 的最小权限范围密钥（ssk_*），可选择为特定用例搭建数据模型，并将 vectros 服务安全合并到你的 MCP 客户端配置中——无需根密钥，也无需手动编辑 JSON：

npx -y @vectros-ai/cli bootstrap

你可以选择要设置的内容（空白的只读凭据，或任务跟踪之类的蓝图），然后使用开发者门户中的令牌登录一次。随后，命令会：

• 为这台机器创建一个范围受限的 ssk_*（可独立轮换），
• 创建匹配的 AccessProfile——仅限数据平面；命令会拒绝配置控制平面范围（密钥／配置文件／账单／……），
• 备份并将条目合并到 claude_desktop_config.json（Claude Desktop、Cursor、Cline）。对于 Claude Code，添加 --client code：它会合并项目的 .mcp.json，并输出等效的 claude mcp add 命令。

重启 MCP 客户端即可完成。该操作具有幂等性（可随时重新运行）；--rotate 会替换这台机器的密钥。

想自己浏览数据？ bootstrap 为你的Agent设置密钥，而不是为你本人创建登录账号——因此，在你将自己的用户加入蓝图的上下文之前，该蓝图的上下文不会出现在数据平面应用的切换器中（应用只会列出你的用户有权访问的上下文）。你可以在管理应用中（访问 → 上下文 → 你的上下文 → 配置文件 → 创建配置文件，通过电子邮件选择器选择自己，选择一个角色——无需原始 ID），或使用 CLI 和 --principal me（解析为你自己的用户）授予自己一次角色：

vectros access grant --principal me --context <context-id> --role <role>

包含人类角色的蓝图（例如 agentic-sdlc 的 editor）允许你使用 --role；否则，请使用 --actions records:r,search:r,… 内联授予范围。

对于脚本／Agent 用法，可在环境中设置登录令牌并跳过提示：

VECTROS_BOOTSTRAP_TOKEN=… npx -y @vectros-ai/cli bootstrap \
  --blueprint task-management --yes

想手动配置？请参阅下方的手动配置。

从客户端连接

客户端	一键安装	手动配置
Claude Desktop	桌面扩展（.mcpb） — 双击并粘贴密钥	JSON 片段
Cursor		.cursor/mcp.json，格式与下方相同
VS Code		.vscode/mcp.json，在顶层 servers 键下添加相同条目
Claude Code	claude mcp add（见下文）	项目 .mcp.json
Cline / Continue	—	与 Claude Desktop 相同的 JSON 片段
Smithery	npx -y @smithery/cli install @vectros-ai/mcp-server	—
Codex	—	TOML 片段（见下文）

对于所有客户端，最快的方式都是运行 npx -y @vectros-ai/cli bootstrap——它会创建范围受限的密钥并为你写入配置。一键按钮会安装服务条目；然后你需要提供密钥（通过 bootstrap，或粘贴你的 ssk_...）。

Codex（~/.codex/config.toml）：

[mcp_servers.vectros]
command = "npx"
args = ["-y", "@vectros-ai/mcp-server"]
env = { VECTROS_API_KEY = "ssk_live_..." }

需要坦诚说明的限制

精准是我们的核心主张——以下是此服务有意不做的事情：

• 需要人工参与。 初始化需要登录开发者门户 / 桥接令牌。只需一条命令，但需要有人登录——无法完全无人值守地完成配置。
• 有意不提供 Web 工具。 Agent 界面完全不提供网页搜索或网页抓取工具。Vectros 是记忆，不是浏览器。
• 目前 Agent 文档上传采用文本内联方式。 Agent 以内联方式摄取文档文本；使用 stdio 传输时支持通过受限环境上传本地文件，但目前 Agent 界面不支持批量上传文件。
• 审计历史具备防篡改检测能力，而非防篡改能力。 状态连续性链可让带外篡改变得可检测；但不会持续进行自动验证。

手动配置（Claude Desktop 或任何 MCP 客户端）

如果已全局安装 @vectros-ai/cli（使用 npm install -g @vectros-ai/cli，而非一次性的 npx 运行——之后服务器运行时需要 vectros 仍位于 PATH 中，而不只是初始化期间）并已运行 vectros bootstrap，则可以完全省略 env 块——服务器会自动从本地 vectros CLI 密钥环中解析你的密钥（见下文的凭据解析）。单独运行 vectros login 不会完成此操作——它会存储单独的登录会话，而不是此密钥——因此必须实际运行 bootstrap：

{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"]
    }
  }
}

没有安装 CLI，或者无法在某台机器上登录？请改为直接设置密钥：

{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"],
      "env": {
        "VECTROS_API_KEY": "ssk_live_..."
      }
    }
  }
}

此文件位于 Claude Desktop 自己的按用户划分的应用支持目录中，而非共享仓库中——但粘贴在其中的真实密钥仍是静态存储的有效机密：请勿将包含完整密钥的内容粘贴到聊天、工单或屏幕截图中，并尽可能优先使用上述密钥环方式。

重启 Claude Desktop。现在，Agent 可以将 Vectros 工具和两个资源作为可调用界面使用。

手动配置（Claude Code）

Claude Code 会读取项目级的 .mcp.json，其结构相同。 切勿将真实密钥提交到其中——团队通常会将 .mcp.json 纳入版本控制，以共享项目工具；其中一旦包含有效的 ssk_*/sk_* 值，进入 git 历史记录的那一刻就会造成凭据泄露，而不仅仅是在仓库公开时才会发生。

安全共享此配置的方法是：提交不包含任何 env 块的条目，让每位开发者使用自己的 vectros CLI 密钥环提供密钥（参见下文凭据解析——这与 git credential / docker-credential-* 使用的委托方式相同）。这要求每位团队成员都全局安装 @vectros-ai/cli 并运行过 vectros bootstrap——只用 npx 运行一次 CLI，或单独运行 vectros login（这是独立的登录会话，并非此密钥），都不会在 PATH 或密钥环中留下可供服务之后查找的内容：

{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"]
    }
  }
}

也可以让 Claude Code 的 CLI 为你写入基于密钥环的条目：

claude mcp add vectros -- npx -y @vectros-ai/mcp-server

如果某台机器确实没有安装 vectros CLI，可以直接通过 -e VECTROS_API_KEY=ssk_live_... 传入密钥——但此时请将配置保留为本地文件：先将 .mcp.json 添加到 .gitignore，不要连同其中的密钥一起提交。

添加 -e VECTROS_API_BASE_URL=<your environment's API base URL>，即可将服务指向其他环境。

重启以将其加载到会话中。 添加服务时已打开的 Claude Code 会话不会在会话中途加载它——请完全退出并重新打开项目（而不只是重新选择标签页）。/mcp 面板显示的是连接器市场，而不是本地配置的 stdio 服务，因此它无法确认服务是否已加载——请改为让 Agent 调用 Vectros 工具。配置以 git 公共根目录 为键，因此关联的工作树会解析到主仓库的 .mcp.json——请从同一个项目添加配置并打开项目。

**Windows 说明：**如果你的 .npmrc（或全局 npm 配置）将 @vectros-ai 作用域指向了其他注册表，那么直接运行 npx -y @vectros-ai/mcp-server 可能会解析到公共版本以外的构建。如果上面的命令无法启动，可以移除作用域注册表覆盖后直接运行 npx，或者指定已知可用的明确版本（npx -y @vectros-ai/mcp-server@<version>）。

工具（23 个工具）

搜索与 RAG

工具	功能
hybrid_search	在租户已索引的内容（记录 + 文档）中执行 BM25 + 稠密向量混合搜索。可按所有权范围筛选（单个维度使用 scope，多个维度同时筛选则使用 scopeFilters——例如指定组织内的某个客户端）、文件夹、类型、元数据筛选条件、创建日期范围，以及关键词精度（textMode）/相关性阈值。返回每条命中的索引投影。
rag_ask	基于已索引语料回答问题。通过 search 限定检索范围（所有权范围——search.scope 或多维度 search.scopeFilters——/ 文件夹 / 类型 / 元数据筛选条件 / 日期范围），并引导生成过程（使用 instructions，以及适用于支持温度参数的模型的 temperature）。聚合流式生成；进度通知会在生成期间保持调用活跃。可选的 providerAlias 可将单次调用路由到你自己的模型提供商（见下文）。
document_ask	基于单个文档回答问题。聚合方式和进度通知形式与 rag_ask 相同，也支持可选的 providerAlias。

记录（结构化、经架构验证的数据）

工具	功能说明
list_schemas	列出凭据可见的记录模式目录（可按 surface 筛选，或按 recordType 查找一个模式）。让 record_query / record_create 可供发现。
record_query	按查找字段查询记录——支持相等匹配（value）、范围或前缀，并支持 asc/desc 排序及可选的 sortFrom/sortTo 范围窗口；也支持列表模式，可选择 type、folderId（文件夹中的所有记录，不限类型——可与 type 组合以缩小范围）或 recent（跨所有类型的账户级近期更新动态），然后可按所有权筛选前两种模式。还支持跨 2-3 个字段进行复合相等匹配（values），但只能针对 模式 声明了包含这些字段的查找项（参见 list_schemas），不能任意挑选两个字段。
record_get	按 ID 获取一条记录，包括其完整载荷（为保护 Agent 上下文窗口，大型载荷会被截断）。
record_batch_get	在一次调用中按 ID 获取多条记录（1-100 条），每条都包含完整载荷。对于无法访问的请求 ID，会返回 missingIds，因为 API 会静默省略这些 ID。
record_create	创建指定类型的记录；通过 externalId 实现幂等；可选指定每条记录的 indexMode。
record_batch_write	在一次调用中创建或插入更新最多 50 条记录，无需进行 N 次 record_create 往返调用。条目可以混合类型，并会逐条验证和检查范围。atomicity: all_or_nothing 会将它们作为一个事务提交（如果任何条目失败，则不会写入任何内容）；默认的 best_effort 则会分别写入每条记录。只要批次已处理，就会报告成功——请查看每条记录的 results，不要只根据是否有错误来判断。
record_update	更新记录的载荷（深度合并；null 会删除键）；通过 expectedVersion 实现乐观并发控制。
record_delete	按 ID 永久删除一条记录（会留下墓碑记录）。

文档（文本/文件内容，已编入索引以供搜索 + 问答）

工具	功能说明
document_ingest	创建文档——内联文本正文或上传本地文件（文件模式仅支持 stdio 传输）。通过 externalId 实现幂等；可选指定 schemaId + payload，以创建可按查找字段查询的类型化文档。在 platform 0.46.0 及更高版本中，如果 externalId 未指定 schemaId，则会被拒绝，除非同时传入 confirmUntyped: true。
document_query	按查找字段查询文档（相等匹配 / 范围 / 前缀，支持 asc/desc 排序），或使用列表模式（按文件夹和所有权筛选）。
document_get	按 ID 获取文档（元数据包括生命周期 status 和处理状态 indexStatus；可选返回文本，最多约 8K 个 token，超出部分会被截断；对于基于文件的文档，可选返回预签名 downloadUrl——始终强制下载，不会内联呈现，不受文件类型影响）。
document_update	更新文档元数据 / 类型化载荷（深度合并）；通过 status 归档/恢复（ARCHIVED 会从搜索结果中软撤回，ACTIVE 会恢复）；通过 expectedVersion 实现乐观并发控制。
document_delete	按 ID 永久删除文档（移除文档及其索引内容）。

文件夹（用于归类记录 + 文档）

工具	功能说明
folder_query	按 ID 获取文件夹，或列出文件夹（用于树形导航的父文件夹子项，或租户的平面列表；通过 nextCursor 分页）。
folder_create	创建文件夹。
folder_update	更新文件夹名称 / 描述 / 所有权（合并补丁；通过 expectedVersion 实现乐观并发控制；不能更改文件夹的父级）。
folder_delete	删除文件夹。必须先清空——不能包含文档、记录或子文件夹——且上下文根目录受到保护，不能删除。

身份与历史

工具	功能
current_identity	描述凭据：tenantId、environment、principalType、principalKeyId、principalLabel，以及（对于范围受限的凭据）allowedActions + dataScope。目前不包含 granted_capabilities（member-lifecycle / forensic-read / context-directory-read / delegate-mint，截至 API 0.40.0；在 0.42.0 中加入 delegate-principal-stamp，在 0.44.0 中加入 trigger-control-plane-grant）——这是一种独立的访问范围维度，范围子句可以包含它，但 /v1/ping 尚未报告，因此 allowedActions + dataScope 可能低估凭据的实际访问范围。还会报告此服务自身的版本和捆绑的 SDK 版本（mcpServerVersion、sdkVersion）。
lookup_principal	根据你自己的 externalId（→其 Vectros UUID，用于所有权筛选器）或架构查找字段，解析用户或某个命名空间（org/client/你注册的任何命名空间）中的身份实体。传入 contextId 可指定某个应用上下文中的上下文所有命名空间。只读。
version_history	读取某条记录或文档的审计/版本记录（CREATE/UPDATE/DELETE，包含操作者 + 差异）。只读。

全部 23 个工具都封装了已发布的 Vectros HTTP API 端点。Agent 看到的工具输出是 JSON 响应。每次调用的费用通过推理响应中的 usage 字段体现。

并发更新。 如果另一个请求同时更改了同一项目，record_update、document_update、folder_update 以及带有 upsert: true 的 document_ingest 都会返回 409（errorCode: VERSION_CONFLICT），无论你是否传入 expectedVersion。不会写入任何内容，另一项更改会保留：重新读取该项目并重试。 即使另一项更改早已完成，expectedVersion 仍会拒绝基于较早读取的版本进行的更新。刚刚删除的项目若被更新，则会返回 404。对于带有 upsert 的 record_batch_write，如果某个项目同时遇到另一项更改，结果中会将其报告为 status: conflict 和 errorCode: VERSION_CONFLICT；请再次发送该项目。使用 atomicity: all_or_nothing 写入的项目不适用此规则。

已删除架构中的项目。 架构不再存在的项目不会被提供：读取该项目（record_get、 document_get）会返回错误；更新该项目、读取其 version_history，以及读取文档的文本、下载内容或答案（document_ask）都会被拒绝；record_query、document_query 和 record_batch_get 也不会返回该项目。请删除该项目。

通过自己的模型提供商路由调用

rag_ask 和 document_ask 接受可选参数 providerAlias：这是你的 Vectros 账户已启用的模型提供商配置的别名。传入该参数后，这次调用将由你自己的提供商处理，而非 平台托管的默认提供商；此时，model 指定你自己的提供商 ID 空间中的模型（如果省略，则使用 该提供商配置中的默认模型）。只有你提供了 providerAlias 时，服务才会转发该参数， 绝不会自动填入。

只有在你的账户完成提供商设置并签署平台的风险接受弃权声明后，该功能才可使用。缺少任一条件， 平台都会以 403 拒绝调用，并由工具原样返回。如果拒绝原因是弃权声明，403 中会包含说明具体情况的 errorCode：WAIVER_NOT_SIGNED（尚未签署弃权声明）、WAIVER_TEXT_CHANGED（已签署，但声明文本之后发生变更，因此先前的签名不再有效），或 WAIVER_REVOKED（账户所有者已撤销弃权声明）。账户所有者需在开发者门户（Model Providers）中处理相应问题；重试调用无济于事。

如果你的账户已在开发者门户中接受与 Vectros 签订的业务伙伴协议（Business Associate Agreement），账户所有者还必须在开发者门户（Model Providers）中对每个提供商配置进行确认，调用才能使用该配置。在此之前，平台会以 403 拒绝调用，并说明需要 BAA 持有人确认。所有者需在门户中完成此操作；此服务不会代为处理。

通过你自己的提供商处理的调用会离开平台托管的 Bedrock 路径和 Vectros 的 AWS BAA 边界，因此请审慎决定每次调用是否应使用该提供商。本文不代表你选择的提供商会如何处理你的数据。

仅启用部分工具

传入 VECTROS_MCP_TOOLS=hybrid_search,record_query,record_get，仅注册这三个工具——适合为 Agent 提供只读访问权限，同时避免凭证产生数据导入或推理费用。只有当凭证应能消耗推理余额时，才添加 rag_ask 或 document_ask。未知工具名称会导致启动时立即失败。

资源

两个用于提供环境上下文的只读资源（无需调用工具）：

URI	返回内容
vectros://schemas	与 list_schemas 返回相同的内容。Agent 可预加载架构到上下文中，以便自动发现。
vectros://identity	与 current_identity 返回相同的内容。Agent 可自行描述身份，无需消耗工具调用。

建议使用的凭据

使用受限永久 API 密钥（ssk_*），而不是根密钥（sk_*）。

受限密钥绑定到范围较窄的 AccessProfile，例如，在一个组织范围（scope:org）内只读。如果你的 MCP 安装遭到入侵，影响范围也仅限于该配置文件允许的范围，而不是整个租户。服务器启动时，如果你传入通配符 sk_*，会因此输出一条 warn 日志。

最简单的获取方式是运行 npx -y @vectros-ai/cli bootstrap（见上文） ——它会为你创建一个遵循最小权限原则的 ssk_* 密钥和一个 AccessProfile，无需根密钥。你也可以手动操作：在开发者门户中，前往 Keys → Create scoped key 创建受限密钥，将其绑定到一个只读 AccessProfile（名称不限，例如 mcp-read），然后把生成的 ssk_live_... 填入上面的配置中。

请参阅 Vectros 开发者文档中有关受限令牌的说明，了解如何设置遵循最小权限原则的凭据——vectros bootstrap 流程只需一条命令，就能创建受限的 ssk_* 密钥及其 AccessProfile。

从 API 0.43.0 开始，根 sk_* 不能再向其他应用上下文写入数据。 如果你使用根密钥运行此服务器，而某个工具调用指定了属于 default 以外上下文的 folderId / parentFolderId，或者文档的 schemaId，请求现在会被拒绝，并统一返回 400 "Folder not found" / "Schema not found"。这会影响 document_ingest、document_update、 record_create、record_update 和 folder_create，且改变了调用结果：这些调用过去会成功。 但它们实际上的行为并非表面看起来那样——根密钥写入的数据始终会标记为 default，因此记录会写入 default，而其文件夹或架构却位于其他上下文中，导致所属上下文永远无法看到该记录。以旧方式写入的现有记录不受影响，仍可读取、更新和删除。解决方法就是使用上文建议的受限密钥：绑定到目标上下文的密钥可以向该上下文写入数据，而且一直都可以。

凭据解析

服务器会使用第一个能提供 API 密钥的来源：

1. VECTROS_API_KEY——只要设置了该变量，就始终优先使用。
2. vectros CLI 密钥环——如果未设置该密钥，且 @vectros-ai/cli 0.9.0+ 位于你的 PATH 中，服务器就会将 vectros keyring show --format raw 作为子进程运行，并使用其输出的密钥。默认情况下，这会使用你的当前身份；设置 VECTROS_KEYRING_ALIAS 即可选择特定条目。这与 git credential / docker-credential-* / aws credential_process 的模式相同：密钥只保存在一个地方，服务器、脚本和 Agent 钩子都从那里读取，而不是各自保留一份可能不一致的明文副本。
3. 以上来源均不可用——启动失败，并显示同时列出这两个选项的提示信息。

解析出的密钥会保存在内存中，绝不会写入日志。启动日志会显示解析出的别名（而不是密钥），让你一眼就能看出服务器正在使用哪个身份——vectros keyring doctor（CLI 0.10.0+）也会显示相同的信息。

如果服务器选用了你未指定的身份，启动时会发出警告。 如果未设置 VECTROS_API_KEY，也未设置 VECTROS_KEYRING_ALIAS，服务器就会回退到密钥环中的当前条目并记录警告——它会使用 vectros switch 上次选中的身份运行，该身份可能是操作真实数据的 ssk_live_* 密钥，也可能是无法操作真实数据的 ssk_test_* 密钥。两种情况都可能带来意外，因为空白占位值（客户端配置中的 "VECTROS_API_KEY": ""，或 Docker 中通过 -e VECTROS_API_KEY 传入未设置的变量）看起来像是“尚未配置”，但实际解析结果与未设置密钥相同。系统不会阻止启动——指定 VECTROS_KEYRING_ALIAS 中的条目，或设置 VECTROS_API_KEY，警告就会消失。vectros keyring doctor（CLI 0.10.0+）会显示哪个条目处于当前状态，以及哪些密钥可操作真实数据。

环境变量

Var	Required	Default	Purpose
VECTROS_API_KEY	no*	—	Vectros API 密钥。接受 sk_* / ssk_* / st_*；推荐使用 ssk_*。*除非已安装 vectros CLI 且密钥环中存在可用条目，否则为必填——请参阅凭据解析。设置后优先使用此项。
VECTROS_KEYRING_ALIAS	no	(the active entry)	使用此 vectros 密钥环条目，而非当前活动条目。设置了 VECTROS_API_KEY 时会忽略此项。
VECTROS_API_BASE_URL	no	https://api.vectros.ai	用于覆盖为其他环境。会进行验证：必须使用 https://（或指向 localhost 的 http://），且主机必须是官方 *.vectros.ai 域名。
VECTROS_ALLOW_INSECURE_BASE_URL	no	—	设置为 1 可绕过基础 URL 允许列表（例如使用可信的本地代理）。不推荐——这会将密钥发送到未经验证的主机；同时会记录警告。
VECTROS_MCP_INGEST_ROOT	no	process cwd	document_ingest 的 filePath 模式允许访问的目录。超出此目录的路径（路径遍历／绝对路径／符号链接）或匹配敏感模式的路径会被拒绝。
VECTROS_MCP_TOOLS	no	(all tools)	逗号分隔的工具名称（例如 hybrid_search,rag_ask）。
VECTROS_MCP_DEBUG	no	—	设置为 1 可在 stderr 输出详细日志。
VECTROS_MCP_SKIP_PING_VALIDATION	no	—	设置为 1 可禁用启动时的 /v1/ping 检查。
VECTROS_MCP_HTTP_PORT	HTTP only	8765	HTTP 传输端口。
VECTROS_MCP_HTTP_HOST	HTTP only	127.0.0.1	绑定地址。使用 0.0.0.0 可监听所有接口（此时请设置 bearer token）。
VECTROS_MCP_HTTP_BEARER_TOKEN	HTTP only	—	客户端→服务端的 bearer token。监听 localhost 之外的地址时强烈建议设置；绑定到非环回地址时必须设置。
VECTROS_MCP_HTTP_ALLOWED_HOSTS	HTTP only	—	逗号分隔的额外允许 Host 值（用于防御 DNS 重绑定）。如果反向代理后方有公共主机名，请将其设为对应主机名。
VECTROS_MCP_HTTP_ALLOWED_ORIGINS	HTTP only	—	逗号分隔的额外允许 Origin 值。
VECTROS_MCP_HTTP_ALLOW_INSECURE	HTTP only	—	设置为 1 可允许在没有 bearer token 的情况下绑定到非环回地址。不推荐。

启动时验证凭据

在首次调用工具之前，服务端会使用你的凭据执行 GET /v1/ping 检查。无效密钥会在启动时明确报错， 而不会在对话过程中隐晦地返回 401。设置 VECTROS_MCP_SKIP_PING_VALIDATION=1 可禁用此检查。

HTTP 传输

对于托管 MCP 场景——在网络边界后运行服务端、 在多个 Agent 实例之间共享，或将其作为 sidecar 部署——此软件包还提供了 HTTP 二进制文件：

VECTROS_API_KEY=ssk_live_... \
VECTROS_MCP_HTTP_PORT=8765 \
VECTROS_MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  npx -y -p @vectros-ai/mcp-server vectros-mcp-server-http

HTTP 二进制文件不是默认选项——使用 npx -p <pkg> vectros-mcp-server-http 显式选择。 直接运行 npx -y @vectros-ai/mcp-server 始终会启动 stdio 服务端。

服务端默认监听 http://127.0.0.1:8765/mcp。bearer token 为可选项，但对于 localhost 之外的任何部署都强烈建议设置——如果没有它，任何能够访问该端口的人都可以使用你的凭据调用 Vectros。

健康探针位于 GET /healthz（始终无需身份验证，适用于 k8s readiness 检查）。

当前限制：每个进程的服务端仅使用一个上游凭据 （启动时解析的密钥）。通过传入的 Authorization header 按请求覆盖凭据是计划中的增强功能。目前，请针对每个需要的凭据边界分别部署一个服务端。

以编程方式使用（进阶）

大多数使用者采用上文的 CLI 形式。如果你需要在自己的 Node 进程中嵌入 服务端：

import { VectrosMCPServer, createStdioTransport } from '@vectros-ai/mcp-server';

const server = new VectrosMCPServer({
  apiKey: process.env.VECTROS_API_KEY!,
  tools: ['hybrid_search', 'rag_ask'],
  resources: ['schemas'],     // opt-in resource filter; default = all
  validateOnStart: true,      // default — set false to skip startup ping
});
await server.connect(createStdioTransport());

此 MCP 服务有意不提供的功能

这是一项决策，而不是待办事项。MCP 服务是交给自主调用方使用的工具界面，因此，API 提供的功能并不会自动成为工具——每项功能都必须证明自己值得出现在 Agent 的工具界面上。

界限在于数据平面：记录、文档、文件夹和搜索都完整提供。任何授予或管理权限的功能都不在其中，定义数据模型的设计时层也不在其中。

• 已存储的脚本（/v1/scripts — 推送、列出、获取、删除）。已存储的脚本是代码，不是数据。编写脚本属于设计时操作，这与架构变更放在 CLI 而非此处的原因相同：允许 Agent 编写之后会在你的凭据下运行的代码，与允许它编写记录，完全是两回事。
• 同步脚本执行（POST /v1/scripts/execute，scripts:x 范围）。这是两个选项中更接近纳入的一项，但因运维方面的原因而排除，并非能力不足——scripts:x:<name> 授权是有意限定到单个脚本的权限，普通的范围限定密钥也可以持有该权限。Agent 难以妥善处理的是故障情况：如果无法确定运行结果，就会返回 500 EXECUTION_OUTCOME_UNKNOWN，此时写入可能已提交，也可能尚未提交。调用方无法通过重试解决这个问题——必须去检查结果。要正确重试，还需要在多次尝试中复用 Idempotency-Key，但工具调用没有自然的重试标识，因此 Agent 在超时后重新调用时，可能会在不知不觉中再次运行脚本。要妥善提供此功能，需要针对这两点进行专门设计，而不是简单包装一下。在此之前，请通过能够处理这些情况的调用方运行脚本——API、SDK 或 CLI。
• 触发器规则（/v1/triggers）。声明规则会授予权限——规则的 scopes/roleIds 会立即生效，且和其他授予权限的界面一样，声明规则时会检查范围单调性。授予权限不是 Agent 应执行的操作。
• 触发器失败历史记录（GET /v1/trigger-failures）和用量／账单（GET /v1/usage）。两者都只读，也都属于运维范畴，而非数据平面——它们描述的是自动化和账户的运行情况，而不是内容本身。此类信息应由开发者门户或 CLI 提供，由人查看，而不是由 Agent 在任务过程中调用工具获取。
• 身份、访问权限和凭据管理——用户、访问配置、角色、应用上下文、签发方注册，以及范围限定密钥的生成。自发布以来保持不变：根据设计，身份 CRUD 不属于 Agent 的工具界面。lookup_principal 会将标识符解析为 ID，不执行其他操作。
• 合规操作（擦除、导出）。原因相同。

如果你认为其中某项应该出现在 Agent 的工具界面上，欢迎告知我们——这条界限是有意划定的，也可以根据理由重新调整。

此 MCP 服务尚未提供的功能

• 不支持提示词功能——/rag 和 /ingest_pdf 斜杠命令模板将在未来版本中推出。（资源配置——bootstrap 命令——位于单独的 @vectros-ai/cli 包中，见上文。）
• HTTP 传输在每个进程中仅支持单租户——通过传入的 Authorization 标头按请求覆盖凭据，将在 v1.0+ 中增强。
• 没有 Python 实现——仅支持 TS。Python 用户可以在任何项目中通过 npx 使用此 MCP 服务。
• rag_ask 和 document_ask 不原生支持流式传输——工具返回前会聚合完整答案。进度通知可用于处理延迟问题。原生 MCP 规范流式传输功能将在规范稳定后推出。

此 MCP 服务正处于迈向稳定 1.0 版本的 pre-1.0 阶段。

速率限制

工具调用遵循与任何 API 客户端相同的每分钟速率限制；速率限制指南说明了哪些请求会计入限制。遇到速率限制 429 时，工具会返回包含 HTTP 429 和 errorCode: RATE_LIMITED 的错误，以便 Agent 控制调用频率并重试，而不是盲目重试。rag_ask 和 document_ask 也可能返回带有 errorCode: BALANCE_BUSY 的 429（你的预付余额暂时正被其他并发请求占用：这不是速率限制，也不是余额不足，因此无需充值；稍后重试即可），或返回带有 errorCode: BALANCE_UNAVAILABLE 的 503（临时故障中断了余额检查步骤；这也不代表余额不足；稍后重试即可）。402 表示余额不足（INSUFFICIENT_BALANCE），或已达到套餐的使用限额（SUBSCRIPTION_LIMIT_EXCEEDED）。如果调用中指定了 providerAlias，但返回的 503 没有 errorCode，则表示平台无法打开已存储的服务商密钥：稍后重试；如果问题仍然存在，请在开发者门户中重新输入密钥。工具会返回消息、errorCode 和 requestId，但不会返回 Retry-After 标头。该指南还列出了各套餐的限额。

从源代码构建

git clone https://github.com/vectros-ai/vectros-mcp-server
cd vectros-mcp-server
npm install
npm run build
npm test

npm install 会从配置的 npm 注册表获取 @vectros-ai/sdk。

npm run build 会运行 tsup，在 dist/ 中生成 ESM/CJS 双格式输出。SDK 会打包到构建产物中（参见 tsup.config.ts）——发布的 npm 软件包是自包含的，用户无需在自己的机器上配置 .npmrc 即可使用。

安全与信任

Vectros 强制实施按客户隔离、默认拒绝的隔离策略，以及遵循最小权限原则的作用域密钥，并提供防篡改审计和版本历史记录。面向客户的界面经过广泛的对抗性安全审查，已得到加固。如需了解完整的信任状况及其边界，请参阅合规与信任指南。

工具输出是不可信的、由 API 提供的内容。 此处的每个工具都会以纯文本形式，在 MCP 响应中返回你自己的租户数据——文档文本、搜索结果、错误消息。此服务不会清理、转义或预先渲染这些文本，也不会评估或执行其中任何内容。请像处理 Agent 从外部来源获取的其他数据一样，在客户端中安全地渲染工具输出，不要对其调用 eval，也不要将其视为已预先清理的内容。

许可证

Apache-2.0。请参阅 LICENSE 文件。