AtlaSent MCP Server

@atlasent/mcp-server

为任何兼容 MCP 的 AI Agent 强制执行先授权、后执行的 MCP 服务。

这是开发者接入 AtlaSent AI Action Protection 的入口。企业团队通过设计合作伙伴计划采用该方案。

AtlaSent 是面向人员、软件和 AI 所执行重要操作的安全与组织授权基础设施。

该 MCP 服务将其引入 AI Agent（Claude、Cursor、Windsurf 以及任何 MCP 宿主）。在 Agent 的工具调用更改真实系统之前（例如部署到生产环境、导出数据或授予访问权限），Agent 会先向 AtlaSent 发起请求。使用 API 密钥（远程模式）时：

1. 连接服务：只需几行配置即可将其连接到你的 Agent。
2. 高风险操作会等待：等待人员批准。其他操作照常执行。
3. 每项决策都会生成签名记录，包括决策依赖审批时的批准者信息。

无需账户，60 秒即可试用：npx -y @atlasent/mcp-server（本地模式，不提供任何保护的演示）。

**免费，无需账户：**将 MCP 服务的工具列表粘贴到 AI Permission Check，查看哪些工具可能更改真实系统，以及应该由谁批准。这项检查会在浏览器中运行。

**本地拦截免费。**无需账户即可在自己的机器上实际拦截操作，请使用 MCP Gate 或 Claude Code agent guard。两者均属于免费社区计划。团队可通过 AtlaSent 计划使用托管决策、共享策略和审批功能。

面向工程师

AtlaSent 执行执行时授权：判断当前是否授权执行某项具体的重要操作；在 allow 时颁发范围受限的 Permit；在执行 Gate 验证该 Permit；只有完成这些步骤后，才允许执行受治理的原生操作。

请求看起来合理，并不代表它获得了组织授权。

该 MCP 服务向 Model Context Protocol 宿主提供 AtlaSent 授权原语，并包含一个受保护的部署演示，可端到端验证上述执行顺序。

由谁决定？

此仓库提供 两个软件包，其中一个有两种模式。这三者都会阻止工具调用。只有其中一个能作为证据，区别不在功能列表，而在于是谁批准的。

接入面	决定者	说明
@atlasent/mcp-server 本地模式	内置启发式规则	什么也不是——无需凭据的演示。它的终端规则是 allow，包括它无法识别的操作类型。切勿依赖它来提供保护。
@atlasent/mcp-gate + policy.json	你提前在可编辑的文件中设定	**运维人员配置。**初始配置为 {"default":"deny","rules":[]}，在你编写规则之前会阻止所有操作。无需账户和网络即可运行。
@atlasent/mcp-gate 云端模式	你的组织在执行时决定	组织许可——仅可使用一次，与该次调用绑定，之后可验证。

可以悄悄编辑的规则属于配置。由组织签发、仅使用一次且之后可以出示的许可，才是权威凭证。两者都会阻止调用，但只有后者能回答*“是谁授权的？”*——这正是事故发生后，而不是发生前会被问到的问题。

Gate 会在每次决策中说明由谁决定：no_matching_rule 表示你的本地策略，cloud_permit_consumed 表示组织许可。**这些原因字符串刻意不统一为笼统的“已阻止”。**不要将它们合并。

这两个软件包的作用方向相反，因此需要分开： mcp-server 将 AtlaSent 作为 MCP 工具提供，供 Agent 调用以请求授权； mcp-gate 则位于他人的 MCP 服务前方并拦截调用。

不变量

对于受保护路径上的强制执行：

Action proposed
  → current organizational Authority + Policy + Context evaluated
  → Decision
      deny / hold / escalate → STOP
      allow → bounded Permit
  → Permit Verification at the execution Gate
      invalid / expired / replayed / mismatched / error → STOP
      verified → native effect may execute
  → execution/native-effect Evidence recorded where the integration supplies it

评估不等于执行。肯定的 Decision 不等于 Gate。许可验证发生在受保护副作用之前。

快速入门：60 秒，无需账户

试用此服务无需 AtlaSent 账户或 API 密钥。未设置凭据时，它会以本地模式运行：一个可离线工作的进程内规则引擎。

一键安装（本地模式，无需账户）：

将以下内容添加到 MCP 宿主配置中（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code 等；各宿主的文件位置见下文）：

{
  "mcpServers": {
    "atlasent": {
      "command": "npx",
      "args": ["-y", "@atlasent/mcp-server"],
      "env": { "ATLASENT_MODE": "local" }
    }
  }
}

然后让你的 Agent “将 billing-api 部署到生产环境”。内置规则会因缺少审批而拒绝此操作。添加审批后再次请求即可获准，并且服务器会在模拟部署运行前验证许可证。

内置本地规则（src/localEngine.ts）：

情况	决策
没有审批的生产操作	deny
在变更窗口之外执行破坏性操作（delete、drop、purge 等）	hold
签署 / 认证 / 授予 / 撤销 / 暂停 / 恢复操作	deny
覆盖 / 发布 / 导出 / 导入 / 发布操作	hold
通过规则的任何操作	allow → 一次性许可证，有效期 5 分钟

本地许可证未经签名，因此本地模式适用于开发、CI 和试用。它不是生产环境的强制执行边界。设置 NODE_ENV=production 时，服务器会拒绝回退到本地模式。准备好使用签名许可证、审计证据和组织自己的策略后，请切换到远程模式——获取 API 密钥。

从源码运行

git clone https://github.com/AtlaSent/atlasent-mcp-server.git
cd atlasent-mcp-server
npm install
npm run build
npm run demo      # blocked deploy → approved + verified deploy → replay refused, fully offline

使用 Docker 运行

docker build -t atlasent-mcp .
docker run -i --rm atlasent-mcp                                          # local mode, stdio
docker run -i --rm -e ATLASENT_API_KEY -e ATLASENT_BASE_URL atlasent-mcp  # remote mode

Claude Code 插件：阻止 Agent 破坏生产环境

packages/agent-hooks 是一个 Claude Code 插件。破坏性命令 和发布命令会等待人工处理：DROP TABLE、terraform destroy、卷 删除、git push --force、生产部署。如果无人审批，这些操作就会被拒绝。 其他操作照常运行。本地运行，无需账户。

/plugin marketplace add AtlaSent/atlasent-mcp-server
/plugin install atlasent-guard@atlasent

“键盘前有人点了同意”到此为止。本仓库的其余部分则是组织级方案：由你的组织指定审批人，并提供事后可验证的许可证。

基于规范的操作

AtlaSent 不会将每个临时工具字符串都视为一种新的受管操作类型。

请使用 Protected Action Canon 来保持操作身份稳定。以下是两个重要示例：

production.deploy
agent.tool.invoke

对于通用 AI 工具调用，请将 agent.tool.invoke 用作由规范支持的公共操作类型，并在授权上下文或所选集成路径支持的绑定字段中携带工具专属事实——工具名称、目标、环境、参数 / 负载摘要、资源状态及其他必需上下文。

请使用只读工具 atlasent_lookup_action 来发现由规范支持的操作类型，而不要另行发明一套分类体系。

权限不等于批准

请将以下概念区分开来：

• 权限 — 持续有效、范围明确的组织权利，可促成某类变更。
• 授权 — 针对此次请求作出的判断，确定此刻是否可以执行这一具体 Action。
• 策略 — 应用于该判断的、带版本的条件。
• 批准 — 经过验证的输入，可能满足某项策略条件；它不是持续有效的权限，也不是最终的授权结果。
• 决策 — 平台边界处的 allow | deny | hold | escalate。
• 许可凭证 — 有界的正向授权凭证。
• 验证 — 在执行边界检查许可凭证及适用的绑定关系。
• 执行 / 原生效果 — 底层工具或系统实际执行的操作。
• 证据 / 证明 — 关于授权以及（在可观测的情况下）效果 / 结果的持久证据。

人工批准、有利的风险信号、策略匹配、部署工单或工作流状态，本身都不会成为组织权限。

受保护工具演示

deploy_service 刻意保持精简。它演示了一条双层受保护路径：

agent requests deploy_service
  → authorize internal agent-tool compatibility gate
  → verify outer Permit
  → authorize production.deploy
  → verify production.deploy Permit
  → simulated deployment effect

内部外层门控使用由 Canon 支持的 agent.tool.invoke Action（CANON-000026 / ACT-0029）——这是整个 AtlaSent 生态系统中记录的同一公开标识，也是规范的通用 AI Agent 工具调用标识。此前它使用的是旧版、未编入目录的标识 model.agent.execute_tool，但该标识在运行时没有对应的 action_classes 配置路径（没有任何种子数据或迁移会创建该 slug 对应的行），因此，对于真实且未经修改的 Atlasent 组织，外层门控只会返回 NO_ACTION_CLASS 拒绝，无论工具专属的内层门控作出何种决策。将外层门控迁移到 agent.tool.invoke 后，它便能使用运行时真实存在的“AI Agent Safeguard”配置路径，而该路径本来就是为此目的而设。完整的调查和决策记录请参见 AtlaSent/atlasent-mcp-server#121。

如果任一决策不是 allow，或任一许可凭证未通过验证，则不会产生部署结果。

受保护工具的响应会包含操作专属的验证结果，以及模拟的原生结果：

{
  "decision": "allow",
  "permit_token": "...",
  "verification": {
    "outcome": "verified",
    "valid": true
  },
  "result": {
    "status": "deployed",
    "service": "billing-api"
  }
}

返回的许可凭证已在执行边界验证过程中被消耗。再次验证它应视为重放，而不是部署后必需的步骤。

人机协同演示：暂缓、批准、执行、记录

examples/hitl-demo.mjs 使用 atlasent_governed_file_change（AI Action Protection，一项设计合作伙伴计划），针对托管运行时和真实 GitHub 仓库，展示了一个不间断的完整流程：

阶段	展示内容
1 ATTEMPT	Agent 请求更改配置文件
2 HOLD	运行时暂缓操作并返回 approval_request_id。重新读取文件后发现其未发生变化
3 BOUND	拒绝了内容不同的同一请求，因此批准仅适用于这次更改
4 APPROVE	有人在 AtlaSent 控制台（Approvals）中批准该请求
5 EXECUTE	在边界处验证许可，然后仅执行一次写入，并打印提交 sha
6 RECORD	工具在该提交和分支头重新读取效果，演示程序再次读取，并打印 ai_action_proof.v1 哈希

密钥必须绑定到 Agent（控制台：Settings → Connect an AI agent）。请使用专用演示仓库。

npm run build
ATLASENT_API_KEY=ask_test_... \
ATLASENT_BASE_URL=https://<ref>.supabase.co/functions/v1 \
ATLASENT_ENVIRONMENT=staging \
ATLASENT_AI_ACTION_GITHUB_REPO=owner/demo-repo \
ATLASENT_AI_ACTION_GITHUB_BRANCH=main \
ATLASENT_AI_ACTION_GITHUB_TOKEN=<token that can write only that repo> \
npm run demo:hitl

演示程序仅打印工具返回的内容或仓库显示的内容。如果某个阶段未发生，演示程序会以 FAIL at <stage> 停止并以 1 退出。例如，如果组织的 agent.tool.invoke 策略允许在无人参与的情况下进行更改，演示程序会在 ATTEMPT 阶段失败，而不是跳过暂缓阶段。组织的策略必须要求人工批准。程序会写入 hitl-demo-evidence-<ts>.json，其中仅以 sha256 形式显示许可。

演示前，请运行 npm run demo:hitl:preflight。这是一项只读设置检查：它只发送 GET 请求，不会创建请求、批准、许可或提交。包含前置条件、控制台操作和预期输出的演示者运行清单见 docs/DEMO_90_SECONDS.md。

npm run demo:hitl -- --simulate 会使用内存中的运行时、仓库和审批人离线演练相同阶段。它打印的每一行都以 [SIMULATED] 开头，并且拒绝任何真实网络调用。不要将模拟运行当作实时运行来演示。

自行设防的 Agent 模式

对于拥有自身原生工具边界的 Agent 或 MCP 主机，安全模式如下：

const decision = await evaluate({
  action_type: "agent.tool.invoke",
  actor_id: "agent:research-bot",
  environment: "production",
});

if (decision.decision !== "allow") {
  throw new Error("Action is not authorized");
}

const verification = await verify_permit({
  permit_token: decision.permit_token,
  action_type: "agent.tool.invoke",
  actor_id: "agent:research-bot",
  environment: "production",
  // Present target_id / payload_hash when the selected authorization path
  // binds those fields.
});

if (!verification.valid) {
  throw new Error("Permit did not verify");
}

// Only now may the protected native effect occur.
const result = await runProtectedTool();

封装器、装饰器、提示词或 MCP 工具定义并不会自动成为不可绕过的 Gate。是否满足强制执行要求，取决于实际拓扑：除非所需的 Authorization 和 Permit Verification 已成功，否则原生效果必须无法通过所声称受保护的路径触达。

核心工具

evaluate

适用于 MCP 主机的简易本地／远程授权辅助工具。

Input:  { action_type, actor_id, environment, approvals?, change_window?, target_id?, change_plan?, target_system? }
Output: { decision: "allow" | "deny" | "hold", permit_token?, notes?, ... }

若结果为 allow，请勿立即执行。应先在执行边界处将 Permit 提交给 verify_permit 验证。

verify_permit

执行边界验证辅助工具。

Input: {
  permit_token,
  action_type,
  actor_id,
  environment,
  approvals?,
  change_window?,
  target_id?,
  payload_hash?
}
Output: { outcome: "verified" | "expired" | "invalid" | "error", valid, ... }

仅当 valid === true 时继续。若适用的契约要求 Permit 仅可使用一次，成功的 Verification 会消耗该 Permit。

deploy_service

受保护的部署演示。它会在生成模拟部署结果之前，内部完成所需的 Authorization 和 Verification。

atlasent_evaluate / atlasent_verify_permit

面向托管 V1 API 的工具。当需要 evaluate 小型演示信封之外的更多上下文时，请使用功能更丰富的远程评估路径。Verification 仍须在执行边界处进行。

atlasent_verify_permit 会调用 POST /v1/permits/verify，而托管 API 不提供此接口，因此它只会注册到可自托管网关（见托管工具与可自托管工具）。针对托管 API，请使用 verify_permit 进行验证。

对于 agent.* 操作（例如 agent.tool.invoke），atlasent_evaluate 会像 evaluate 一样，在评估前封装来源证明，结果可能包含 bound_payload_hash 和 bound_actor_id。Permit 会绑定到这些值，因此请将它们作为 payload_hash 和 actor_id 传递给 verify_permit。

atlasent_lookup_action

只读 Canon 查询，用于查找操作类型、门控标志、授权模式、证据要求和图关系。

Input:  { slug? }    // exact Canon slug, e.g. "production.deploy"
        { query? }   // plain language, e.g. "deploy the api service to prod"
        {}           // list the full Canon
Output: { found, result_count, actions[], retrieval? }

query 由一个基于随附 Canon 的确定性、完全离线排序器解析（无嵌入服务、无网络——src/actionRetrieval.ts）。响应包含一个 retrieval 区块：

retrieval.confidence	含义
confident	有一个 Canon 条目明确匹配。actions[0] 即为该条目。可以放心执行。
ambiguous	有两个或更多条目相近，或请求仅部分匹配。查看 retrieval.candidates 并选择一个，或改写请求。
none	Canon 中没有匹配此描述的操作。found 为 false，actions 为空，hint 指向 Canon 接收流程。

该工具绝不会捏造操作类型：每个候选项都引用自一个 Canon 条目；Canon 无法回答的请求会返回 none，而不是一个看似合理的 slug。emergency、weekend 或 urgent 等上下文词会被视为策略上下文，而非不同操作的证据——按照 LIFECYCLE.md 的分类原则，“emergency deploy to production” 仍会解析为 production.deploy。

atlasent_atlas_lookup

只读查询 AtlaSent 的规范概念，例如 Authority、Policy、Decision、Permit、Verification、Evidence、Gate 和 Trust Root。

atlasent_evidence_gap_report

“哪些部署未受管控？”传入 .github/workflows/*.yml 文件的文本，即可获取每个会更改真实系统的步骤（部署、发布软件包和镜像、数据库迁移、terraform/pulumi 应用）及其状态：

status	含义
bound	作业中有更早运行的门控步骤，且此步骤仅在 if: steps.<gate>.outputs.verified == 'true' 时运行。
gated	作业中有更早运行的门控步骤；拒绝时会在此步骤运行前使作业失败。
gated_upstream	门控位于此作业 needs: 的另一个作业中。此步骤运行的位置没有重新验证许可。
weak	存在门控，但无法阻止此步骤：使用了 continue-on-error、设置了它自己的 if:（例如 skip_gate 输入），或使用了 mode: evaluate-only 且没有任何步骤使用该许可。
ungoverned	完全没有门控。

Input:  { workflows: [{ path, content }], gate_actions? }
Output: { summary, findings[], triggers, parse_errors[], not_checked[], next_step, setup? }

每个缺口（ungoverned 或 weak）都包含一个 fix：应插入其前的 atlasent-action 步骤（包含适用的操作类型：production.deploy、package.release 或 infrastructure.change）、用于将此步骤绑定到门控已验证许可的确切 if:，以及现有门控需要做出的任何更改（移除 continue-on-error、移除 skip_gate 条件、添加 id-token: write）。存在缺口时，setup 会提供门控所需 API 密钥的注册链接。应用修复并重新运行报告：该步骤会显示为 bound。

可在本地模式下运行：无需 API 密钥、无需网络、不会执行任何操作。gate_actions 用于指定你自己的门控封装（例如复合操作）；报告会将它们列为自定义门控，且不会检查其内部实现。报告始终会列出它无法查看的内容（仓库设置、CI 外部的部署、./deploy.sh 的内部实现）；无法解析的文件会列在 parse_errors 中，绝不会跳过。报告结果干净，并不能证明不存在未受管控的操作。

atlasent-exposure-scan（一条命令，生成可分享的报告）

在真实代码库上运行同一项审查，并将结果写入可打开和转发的报告：

npx -y -p @atlasent/mcp-server@latest atlasent-exposure-scan path/to/repo
# writes atlasent-exposure-review.html, .md, .json and .csv

保留 @latest：否则 npx 可能会复用不包含此命令的旧缓存副本（在 Windows 上会显示“'atlasent-exposure-scan' is not recognized”）。离线运行：它会读取 .github/workflows/，不会进行网络调用。生成的 HTML 是单个自包含文件（不含脚本或外部资源）。审查报告会以“先修复这些问题”开篇：按根本原因归类缺口，并根据其影响（生产环境优先，未确定的环境绝不视为安全）、触发方式以及可读取的密钥进行排序。.csv 按相同顺序为每个步骤生成一行，可用于电子表格或工单导入。添加 --fail-on-gaps 可将其用作 CI 检查；--out <dir> 可指定文件的输出位置。如果你使用自己的包装操作（或在 atlasent-action 中使用 uses: ./）进行门禁，请通过 --gate-action <uses> 指定其名称（可重复指定），以便将这些步骤计为已设门禁。如果任何工作流文件无法读取或解析，报告会显示 INCOMPLETE SCAN，列出相关文件，命令以状态码 3 退出。

atlasent-change-sample（变更管理抽样审计会发现什么）

审计人员通过抽样检查生产变更来审查变更管理，并确认每项变更是否经过批准、批准人是否为作者以外的人员，以及批准是否针对最终合并的确切代码。此命令会针对一个代码库中已合并的拉取请求进行检查：

npx -y -p @atlasent/mcp-server@latest atlasent-change-sample your-org/your-repo --days 90
# writes atlasent-change-sample.html, .md and .json

它通过 GitHub API，使用你的令牌（GH_TOKEN、GITHUB_TOKEN 或 gh auth token）读取拉取请求、审查记录和每个已合并提交上的检查运行。它只会调用 GitHub：不会向 AtlaSent 发送任何内容，也绝不会打印或写入令牌。报告会以一行摘要开篇，例如“112 项已合并变更中有 7 项未通过变更管理抽样审计”，并将每项未通过的变更链接到其拉取请求。

• 机器人的批准不算人工批准；审查者之后提出的“要求更改”或撤销审查，也会取消他们之前的批准。
• 只有在有人批准合并时所对应的提交，针对更早提交的批准才会计入。
• 无法读取的内容会标记为未知，绝不会视为未通过；报告会显示 INCOMPLETE SCAN，并以状态码 3 退出。
• 它无法查看 GitHub 之外的批准、绕过拉取请求的变更、实际部署的内容、绕过分支保护的权限，也无法判断审查者是否符合你的政策要求。报告会明确说明这些限制。

--base <branch> 可指定分支（默认使用代码库的默认分支）；如果任何变更未通过，--fail-on-findings 会以状态码 1 退出。这不是合规评估或认证。

atlasent_exposure_review

免费的授权暴露审查。它会运行与 atlasent_evidence_gap_report 相同的离线分析，并以便于阅读的审查报告形式返回结果：扫描了哪些内容、无法查看哪些内容、每个可在没有可阻止它的门禁时更改真实系统的步骤、对应的精确修复方法，以及已经设有门禁的内容。

Input:  { workflows: [{ path, content }], gate_actions? }
Output: { review: "exposure_review.v1", markdown, summary, help?, sign_up_url? }

按原样显示 markdown。报告会明确说明，它只涵盖传入的文件，并非对你组织授权态势的评估。当发现缺口或未识别出任何内容时，help 会提供两个可选链接，指向请求页面：一个用于联系独立实施顾问解读发现的问题，另一个用于获取部署门禁方面的帮助。只有在你请求并在该页面同意后，你的信息才会分享给顾问；AtlaSent 不会从顾问的工作中收取费用。

无需 API 密钥，无需联网，也不会执行任何内容。

atlasent_integrity_audit

对组织 Authority 图谱进行只读审计，检查内部不一致。仅适用于托管模式；组织由服务端根据 API 密钥确定。

Input:  { decision_window_days? }   // 1-3650; omit to let the server choose
Output: the integrity report, verbatim

这不是通过/失败式的运行状况检查，该工具也不会自行给出结论。 每项发现都带有三种可能值之一的 classification：

classification	含义
defect	Authority 图谱中确实存在不一致。
non_exercisable	通常是正确、健康的状态，例如本应过期的授权已过期。这不是失败。
unresolved	无法验证该命题。绝不可将其视为正常；“无法检查”和“检查后未发现问题”是两种不同的事实。

如果 findings 列表为空，请先查看 summary.audited_scope，再下结论——决策窗口较短并不意味着没有发现。如果审计无法完成，服务端会拒绝请求，而不会返回部分报告；此工具会将其作为错误呈现，而不是返回空报告。

atlasent_get_permit / atlasent_check_permit / atlasent_get_decision

对单条记录进行只读查询。目前仅适用于自托管 /v1/* 网关：这些工具未在托管 API 上注册（请参阅托管版与自托管工具）。atlasent_get_permit 和 atlasent_check_permit 将在 atlasent-api#4522 投入生产后支持托管 API。

atlasent_get_permit    { permit_id }                     -> the permit record (status, actor, action, times, decision_id)
atlasent_check_permit  { permit_id }                     -> { valid, status: active|revoked|consumed|expired, revoked_at? }
atlasent_get_decision  { evaluation_id, include_trace? } -> { evaluation, trace?: { approvals, permit_uses, webhooks } }

atlasent_check_permit 会读取状态，但不会消耗授权。在延迟执行操作前使用它可以发现授权是否已被撤销，但它不是授权依据：只有在 verify_permit 之后才能执行操作。atlasent_get_decision 需要 audit:read 作用域；传入的 ID 应为授权的 decision_id。

授权工具绝不会返回授权的 token（其持有者凭据）或 signature。工具返回的任何内容都会进入 Agent 的上下文和交互记录，因此这两个字段会在客户端和 API 端同时剥离。

服务端还提供策略、授权、审批、证据、合规和 VQP 工具。注册哪些工具取决于服务端面向的是托管 API 还是自托管网关（请参阅托管版与自托管工具）。使用 MCP tools/list 查看当前配置的准确工具清单。

提示词

服务端还提供 MCP 提示词：可在宿主中选择的模板，用于启动先授权、后执行的工作流。

提示词	参数	引导 Agent 执行的操作
gate-action	action、environment（可选）	使用 atlasent_lookup_action 查询 Canon 操作类型，调用 evaluate；除非决策为 allow，否则停止；在执行操作前立即调用 verify_permit，然后才能执行。
explain-decision	decision（决策 JSON）	用通俗语言解释某项操作为何获准、被拒绝或被暂缓，以及哪些变化可能改变结果，但不提出绕过方法。
find-action-type	description	使用 atlasent_lookup_action 解析通俗语言描述，并在 confident / ambiguous / none 三种结果下分别处理，不得臆造 slug。

提示词只会引导 Agent，并不是 Gate：Agent 可以忽略它。只有在操作运行前立即验证授权，才能保护该操作（请参阅不变量）。

Approval 工作流

可以要求审批，但解决一项审批并不等同于执行受保护的 Action。

Approval / Assertion collected
  → current Authorization / reevaluation path
  → Decision
  → Permit on allow
  → Verification
  → native effect

审批由人员在 AtlaSent 控制台中作出，绝不会由 Agent 作出：此服务特意不提供创建或解决审批的工具。当某项操作被暂缓，等待人员处理时，结果会附带 approval_request_id；使用它调用 atlasent_await_approval，等待人员在控制台中作出决定。审批通过后会返回一个许可，但仍必须通过 verify_permit；如果审批被拒绝、过期或超时，则不会返回许可，操作也不会运行。（仅限远程模式；本地模式绝不会审批。）受保护的 Action 仍必须满足当前授权路径和执行边界 Verification，才能继续。

变更计划和计划变更。 production.deploy、infrastructure.change、production.rollback 和 secret.configuration.change 需要提供 change_plan（{ operation, revision?, artifact_ref? }，且必须包含 revision 和／或 artifact ref）。将其传递给 deploy_service、evaluate 或 atlasent_evaluate。服务会先创建一份准确记录该计划的 Change Brief，然后使用该 Brief 的 id 和相同计划进行评估。当密钥无法创建 Brief（HTTP 403）或运行时没有 Brief（HTTP 404）时，服务会仅使用计划进行评估，并添加一条 notes。任何其他 Brief 错误都会阻止评估。认领时，服务会再次提交相同计划，因此不匹配就意味着计划确实发生了变化。如果你在等待期间更改了计划，请将新计划作为 change_plan 传递给 atlasent_await_approval。默认情况下，服务会为新计划提交一项关联的重新请求（将 supersedes_approval_id 设为旧审批），然后等待人员作出决定。结果会在 summary 中显示各步骤，例如“计划从 X 变更为 Y → 已发送重新请求（审批 …）→ 等待中 → 已通过”。使用 on_plan_mismatch: "use_approved" 时，服务会认领已批准的计划，并将其作为 approved_plan 返回；请严格执行该计划。若再次不匹配、审批已撤销或存在可疑情况，或者组织策略设置了 auto_rerequest_on_mismatch: false，则等待会停止且不返回许可。结果会包含差异和后续操作说明。

对于要求验证操作者的操作类别，运行时会将审批解析为 approved_awaiting_claim，并且只有在认领请求提供操作者身份时才会签发许可。随后，服务会向运行时请求其自身 Agent 的短期 actor_identity.v1（POST /v1-agent-actor-identity，仅绑定到已注册 Agent 的 API 密钥可用）。操作类型和环境取自审批记录，服务会使用 { actor_identity } 发起认领。如果无法获取该身份，则不会认领，也不会返回许可。对于不支持该端点的运行时（HTTP 404），服务会像以前一样使用空请求体发起认领，并在结果中添加一条说明。

哪个 Agent、谁的 Agent、哪个聊天

每次 evaluate 调用都会报告调用所来自的应用（MCP 客户端的名称， 例如 claude-code 或 cursor），以及聊天或会话，表示为 agent_session。AtlaSent 会将此信息标记为由 Agent 主机报告并予以存储： 这有助于追溯某项操作所对应的对话，但绝不会用于作出决策。

• 会话 ID：Streamable HTTP 会话；否则使用主机设置的 ATLASENT_SESSION_ID；如果都没有，则使用带有 mcp-process- 前缀的进程 ID。
• 可选的 ATLASENT_RUN_ID，用于运行或作业 ID。
• 使用 Agent API 密钥时，请将 actor_id 留空：AtlaSent 会根据密钥本身识别 Agent 及其代理的人员，因此模型不会声明自己的身份。

执行证据

atlasent_record_execution_evaluation 会在原生效果发生后记录观察到的执行结果。该证据功能不能替代执行前的 Permit 验证。此功能仅注册到自托管的 /v1/* 网关（见托管式与自托管工具）。

请区分以下说法：

• allow 决策证明已作出肯定的授权判定；
• 已验证的 Permit 证明有界授权凭证在当时通过了其 Gate 检查；
• 执行／原生效果证据才能支持底层操作确实发生的说法。

本地模式与远程模式

模式	用途
local	零配置：离线的进程内规则引擎、未签名的许可凭证。用于开发、演示和 CI。
remote	调用配置的 AtlaSent 托管式／运行时 API。

获取 API 密钥

1. 在 console.atlasent.io/auth/sign-up 创建免费账户。
2. 选择 连接 AI Agent（也可在 设置 → API 密钥 中找到）。为 Agent 命名，选择你的应用（Claude Code、Claude Desktop、Cursor、Windsurf 等）， 控制台会提供密钥以及可直接粘贴的确切命令或 JSON。
3. 将密钥粘贴到 MCP 主机配置中。仅设置 ATLASENT_API_KEY 就会将 服务切换到远程模式；ATLASENT_BASE_URL 为可选项，默认使用托管式 API。
4. 让你的 Agent 尝试执行有重大影响的操作（例如“将 api 服务部署到生产环境”）。控制台会显示决策；任何需要审批的操作都会在审批队列中等待，直到有人批准。

远程模式具备本地模式无法提供的功能：Ed25519 签名的一次性许可凭证、 组织自有的策略，以及防篡改审计跟踪。

远程模式示例：

ATLASENT_API_KEY=ask_live_xxx \
ATLASENT_BASE_URL=https://api.atlasent.io/functions/v1 \
ATLASENT_MCP_READONLY=1 \
npx @atlasent/mcp-server

ATLASENT_BASE_URL 默认为 https://api.atlasent.io/functions/v1。所有 可通过托管式 API 使用的调用，都会根据其已部署名称发送到该基址下的函数：/v1-evaluate、/v1-verify-permit、/v1-approvals/...、 /v1-authority-intelligence/...，以及 REST 风格工具对应的路径：

工具	请求
atlasent_list_policies	GET {base}/v1-policies/
atlasent_list_permits	GET {base}/v1-permits
atlasent_list_audit_events	GET {base}/v1-audit/events（拒绝 evaluation_id：该端点没有此类筛选条件）
atlasent_get_evidence_export	GET {base}/v1-evidence-exports/{id}

组织始终由 API 密钥确定；org_id 参数不会选择其他组织。

托管工具与自托管工具

有些工具仍会在域名根路径下调用斜杠形式的 /v1/<resource> 路径（服务端会为它们移除 /functions/v1），而 api.atlasent.io 不支持这种路径形式：这些请求会返回 404。为确保 Agent 只看到可用工具，当服务端以托管 API 为目标时，不会注册这些工具：

分组	工具
策略	atlasent_get_policy、atlasent_create_policy、atlasent_update_policy、atlasent_delete_policy
许可	atlasent_get_permit、atlasent_check_permit、atlasent_revoke_permit、atlasent_permit（签发）、atlasent_verify_permit（v1 验证）
决策与证据	atlasent_get_decision、atlasent_record_execution_evaluation
Webhook	atlasent_create_webhook、atlasent_delete_webhook
SCIM	atlasent_list_scim_users、atlasent_get_scim_user、atlasent_create_scim_user、atlasent_patch_scim_user、atlasent_delete_scim_user、atlasent_list_scim_groups
SIEM	atlasent_get_siem_config、atlasent_upsert_siem_config、atlasent_test_siem_delivery
证据导出	atlasent_list_evidence_exports、atlasent_create_evidence_export
VQP 报告	atlasent_vqp_audit_summary、atlasent_vqp_drift_events

“以托管 API 为目标”是指 ATLASENT_BASE_URL 未设置或为空（默认情况）、无法解析，或指向 api.atlasent.io 或 AtlaSent 的某个托管 Supabase 项目。这些工具在本地模式下也会隐藏：它们从不使用本地引擎，只会进行远程调用，因此在本地模式下也都无法工作。

在以下任一情况下，这些工具会按原样注册：

• 服务端处于远程模式，且 ATLASENT_BASE_URL 指向其他任意主机（运行自有 /v1/* 网关的自托管运行时）；或
• 设置了 ATLASENT_MCP_ENABLE_GATEWAY_TOOLS=1（或 true），无论目标是什么。

每个工具都在等待相应的运行时处理程序来路由其部署路径；该路由尚不存在，或者需要不同的请求格式或凭据。原因在 src/engine.ts 中各工具的调用位置都有说明。待 atlasent-api#4522 投入生产环境后，atlasent_get_permit 和 atlasent_check_permit 即可在托管 API 上使用。隐藏操作只影响 tools/list：evaluate、verify_permit、atlasent_evaluate、deploy_service 和审批等待始终会注册，行为也始终相同。ATLASENT_MCP_READONLY=1 仍会在这些修改型工具注册后将其移除。

ATLASENT_FUNCTION_REGION 控制运行时边缘函数的执行位置。未设置时，对托管运行时的调用会在 us-west-1 执行，与其数据库位于同一区域。自托管基础 URL 则采用 Supabase 的最近区域默认值。将其设为区域 ID 可指定其他区域；设为 auto 则禁用固定区域。与数据库位于同一区域很重要：evaluate 会依次进行数十次数据库往返。

现场演示的只读模式

设置：

ATLASENT_MCP_READONLY=1

可在使用实时 API 演示时，阻止注册修改型管理工具。只读模式不会将服务端变成通用安全边界；它只是缩小暴露的修改面。受保护的执行路径仍取决于上文所述的 Authorization 和 Verification 拓扑。

故障时默认拒绝

对于配置为要求 AtlaSent Authorization 和 Permit Verification 的路径，以下情况应视为阻止条件：

• Decision 不为 allow；
• 缺少所需的 Permit；
• 身份验证/API 失败；
• Permit 无效、过期、已撤销、已重放或绑定不匹配；
• Verification 出错；
• 缺少所需的执行绑定。

影子/建议性评估有助于观察，但它并不等同于强制执行保护。

Claude Desktop

添加到 claude_desktop_config.json。examples/claude_desktop_config.json 中提供了包含远程、本地和 HTTP 变体的即用文件。

{
  "mcpServers": {
    "atlasent": {
      "command": "npx",
      "args": ["-y", "@atlasent/mcp-server"],
      "env": {
        "ATLASENT_MODE": "remote",
        "ATLASENT_API_KEY": "ask_live_xxxxxxxxxxxxxxxx",
        "ATLASENT_BASE_URL": "https://api.atlasent.io/functions/v1",
        "ATLASENT_MCP_READONLY": "1"
      }
    }
  }
}

Claude Code

使用 claude mcp add 添加服务。它通过 stdio 运行。-- 后的所有内容都是 Claude Code 启动的命令：

claude mcp add atlasent -e ATLASENT_MODE=local -- npx -y @atlasent/mcp-server

运行 claude mcp list 检查连接是否成功，或在 Claude Code 会话中运行 /mcp 查看其工具。

作用范围。 --scope（-s）用于控制条目的存储位置：

作用范围	存储位置	用途
local（默认）	你的用户配置，仅用于当前项目	试用
project	仓库根目录下的 .mcp.json，并提交到版本库	与所有在该仓库中工作的人员共享 MCP 服务。Claude Code 会要求每个人先批准项目服务，然后才会启动。
user	你的用户配置，用于每个项目	在运行 Claude Code 的所有项目中使用

claude mcp add atlasent --scope project -e ATLASENT_MODE=local -- npx -y @atlasent/mcp-server

会写入此 .mcp.json：

{
  "mcpServers": {
    "atlasent": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@atlasent/mcp-server"],
      "env": { "ATLASENT_MODE": "local" }
    }
  }
}

不要在项目作用范围的 .mcp.json 中提交 API 密钥。对于远程模式，请使用 local 或 user 作用范围。

远程模式。 设置 ATLASENT_API_KEY。仅设置密钥就会将服务切换到远程模式，且 ATLASENT_BASE_URL 默认为 https://api.atlasent.io/functions/v1。设置 ATLASENT_MODE=remote 可明确指定远程模式；设置 ATLASENT_MODE=local 则会强制使用本地模式，即使已设置密钥也是如此。请参阅本地模式与远程模式。

claude mcp add atlasent --scope user \
  -e ATLASENT_MODE=remote \
  -e ATLASENT_API_KEY=ask_live_xxxxxxxxxxxxxxxx \
  -e ATLASENT_BASE_URL=https://api.atlasent.io/functions/v1 \
  -- npx -y @atlasent/mcp-server

要切换模式，请使用 claude mcp remove atlasent 移除条目，然后重新添加。

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）。可直接复制使用的本地模式文件，无需账户：examples/cursor_mcp.json。

{
  "mcpServers": {
    "atlasent": {
      "command": "npx",
      "args": ["-y", "@atlasent/mcp-server"],
      "env": {
        "ATLASENT_MODE": "remote",
        "ATLASENT_API_KEY": "ask_live_xxxxxxxxxxxxxxxx",
        "ATLASENT_BASE_URL": "https://api.atlasent.io/functions/v1",
        "ATLASENT_MCP_READONLY": "1"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json。可直接复制使用的本地模式文件，无需账户：examples/windsurf_mcp_config.json。

{
  "mcpServers": {
    "atlasent": {
      "command": "npx",
      "args": ["-y", "@atlasent/mcp-server"],
      "env": {
        "ATLASENT_MODE": "remote",
        "ATLASENT_API_KEY": "ask_live_xxxxxxxxxxxxxxxx",
        "ATLASENT_BASE_URL": "https://api.atlasent.io/functions/v1",
        "ATLASENT_MCP_READONLY": "1"
      }
    }
  }
}

VS Code

添加到工作区中的 .vscode/mcp.json。VS Code 使用的顶层键是 servers，而不是 mcpServers。可直接复制使用的本地模式文件，无需账户：examples/vscode_mcp.json。

{
  "servers": {
    "atlasent": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@atlasent/mcp-server"],
      "env": { "ATLASENT_MODE": "local" }
    }
  }
}

要使用远程模式，请将 env 块替换为 Cursor 部分所示的内容。

其他 MCP 客户端

也可以通过其他 MCP 兼容宿主常用的 MCP 服务配置方式配置此服务（command: npx、args: ["-y", "@atlasent/mcp-server"]，以及上文所示的相同 env 块）。

此服务也列于 Glama（基于此仓库的 Dockerfile 构建；列表所有权信息见 glama.json）和 官方 MCP Registry（io.github.Atlasent/mcp-server，清单见 server.json）中，因此支持注册表的宿主可以发现并安装它，无需手写配置块。npm run bundle 会为支持安装 MCPB 包的宿主构建此服务的 MCPB 包。查看它在哪些地方列出或未列出：docs/DISTRIBUTION.md。

开发

npm install
npm run typecheck
npm run lint      # ESLint (toolchain in tools/lint, installed on first run)
npm test          # offline: no network, no API key
npm run build
npm run demo

npm test 完全离线运行。本地模式测试不会访问网络，远程模式测试会模拟 fetch。其中包含回归测试，证明当外层 Agent 工具 Permit 或特定部署操作 Permit 的 Verification 失败时，受保护的部署演示都不会产生原生结果。

更喜欢即用型环境？在 dev container 中打开仓库（使用 VS Code 或 GitHub Codespaces），它会在创建时安装依赖并进行构建。

社区

• 问题和想法：GitHub 讨论
• 错误和小型功能：提交 Issue
• 较大的改动（新工具、线格式或故障关闭行为）：先提交 RFC Issue
• **想要贡献？**请阅读 CONTRIBUTING.md，并查找 good first issue
• **安全问题报告：**请发送邮件至 [email protected]。详见 SECURITY.md。请勿提交公开 Issue。

所有参与者都应遵守行为准则。

安全

请勿在源代码管理中存放 API 密钥、签名材料、客户机密或生产凭据。授权上下文仅限所选策略和绑定所需的信息。

对安全敏感的集成必须确保实际副作用发生在控制流中所需的授权和验证检查之后。记录决策后仍然继续执行，并不构成强制执行。

相关的公开组件

• atlasent-sdk — 语言 SDK
• atlasent-action — GitHub Actions 集成
• atlasent-verify — 离线证据验证器
• atlasent-keys — 公共验证材料

许可证

根据 Apache License, Version 2.0 授权。