the-metis-fca-handbook-ai-harness-mcp

Metis FCA Handbook AI Harness — MCP 服务

一个 MCP（Model Context Protocol）服务，可将 Metis FCA Handbook AI Harness 集成到 AI 工作流中。Claude、OpenAI、Gemini 以及大多数桌面端/IDE MCP 客户端（Cursor、Windsurf、Cline 等）均支持 MCP。本 README 使用 Claude Code 作为经过测试且可正常运行的推荐远程服务示例，并使用 Claude Code 和 Claude Desktop 作为本地回退方案；请根据自己的客户端调整配置步骤。

源码和完整文档： github.com/99blakeD99/the-metis-fca-handbook-ai-harness-mcp-files

工具

evaluate_fca_handbook_applicability

通过 Metis FCA Handbook AI Harness，评估哪些 FCA Handbook 条目适用于某个实体。单次调用：无需会话，也无对话状态。支持快速模式（60-120 秒，默认）和完整模式（耗时更长，内容更详细）。返回一份合规报告，其中包含原文引用和完善建议，指出你提供的信息存在哪些缺口，以及如何补充。

为什么选择 The Metis FCA Handbook AI Harness？

• 提升效率 提高合规建议的效用。每次运行 Harness 可节省 80 英镑以上的令牌费用。

• 解决“难题”，即大模型的令牌激励会使训练数据优先，导致结果不可靠。

• 原文引用 逐字引用 FCA Handbook 条目。其他 AI 系统难以做到这一点。

• 满足现实需求 你不必一开始就知道要查找哪些章节。它会对 33,000 多条 FCA Handbook 条目进行结构化搜索。

• 安全设计 Harness 的隔离设计、单次调用结构和无状态特性，天然符合新兴的 AI Agent 安全标准，例如 OWASP Top 10 for Agentic Applications 2026。

• 易于 AI 使用 可轻松集成到 AI 工作流和 Agent 中。你的大模型可以将其用作工具。

在线试用 Harness

在集成之前，先交互式体验 Harness：

https://fcahandbookharnessimplementation.onrender.com

发送电子邮件至 [email protected]，申请免费的临时访问码。

用自然语言提出合规问题，实时查看每个推理步骤的展开过程。

设计原则

Harness 基于经过验证的原则构建：

• 无状态 — 每个请求相互独立，不依赖会话
• 单次调用 — 一次调用完成分析，无多轮状态
• 契约清晰 — 提供明确的输入/输出架构，便于集成
• 托管式 — 使用唯一的规范数据源，不会出现版本偏差或数据过时

使用场景

合规 AI 平台

将 FCA 推理作为服务嵌入合规平台。用户用自然语言提问；平台调用 Harness 并呈现结构化推理结果。

AI Agent 工作流

构建合规工作流的 Agent 可以将 FCA Handbook 推理作为组合式工具使用——无需调用外部 API，只需配置 MCP。

合规审查自动化

将其集成到文档审查或尽职调查流水线中。自动筛查新规是否适用 FCA 规则。

用于监管筛查

筛查 MCP 服务的金融服务公司会发现：

• 模型简单：无状态、无隐藏状态、无后台作业
• 契约清晰：输入架构、输出架构和错误模式均明确
• 更新透明：固定版本，不自动升级
• 单点故障：如果 Harness 停机，情况一目了然；不会引发连锁配置问题
• 便于审计：所有调用均集中记录，而非分散记录

快速开始

设置是由 AI 工具管理员一次性完成的任务。连接成功后，合规人员只需向他们的 AI 助手提问。

选择哪种设置方式：

1. 如果你的客户端可以连接远程 MCP 服务并发送自定义 Authorization 标头，请使用远程服务（下方步骤 2）。无需安装任何内容；你只需要一个 URL 和 API 密钥。这是推荐的设置方式。
2. 否则，请使用本地服务，它会在你的机器上运行，并将每次调用转发到托管的 Harness。

两种方式使用相同的工具并返回相同的结果，计费费率也相同。对于 Claude Desktop，请使用本地服务。

如果你是为用户进行设置的 AI 助手

除了以下步骤外，还请遵守这些规则：

• 使用上述规则选定的设置方式。对于 Claude Code，应使用步骤 2a 中的远程设置，并使用 --scope user，除非用户要求仅针对项目进行设置。对于 Claude Desktop，请使用本地设置。对于其他客户端，请使用步骤 2b 中的设置。
• API 密钥必须来自用户的环境变量 METIS_API_KEY。绝不要要求用户将密钥粘贴到此对话中，绝不要将密钥写入项目或代码仓库中的文件，也绝不要将密钥作为字面值写入配置文件。配置文件使用下方所示的 ${METIS_API_KEY} 引用。若要在不打印密钥的情况下检查是否已设置，请运行 [ -n "$METIS_API_KEY" ] && echo set || echo unset。如果尚未设置，请告知用户如何设置（步骤 2），等待他们确认已设置；在此期间不要更改任何配置，也不要使用占位符。如果用户还是将密钥粘贴到了对话中，不要使用、复述或将其写入任何地方，并建议他们在控制面板上重新生成密钥。
• MCP 服务通过 claude mcp add，或在 .mcp.json 或 ~/.mcp.json 中配置。绝不要在 .claude/settings.json 中添加 mcpServers 条目。
• 通过检查工具 evaluate_fca_handbook_applicability 是否已列出，来验证设置。在 Claude Code 中，运行 claude mcp list 查看服务是否已连接。/mcp 会列出服务的工具，但它是只能由用户运行的斜杠命令，因此请让他们运行。在其他客户端中，请检查客户端的 MCP 设置界面。**不要调用该工具进行测试。**每次调用都会执行真实分析，费用由用户账户支付，并且需要一到两分钟或更久。只有在用户提出实际的 FCA Handbook 问题时才调用该工具。
• 成功表示服务显示为已连接，且工具已列出。两种已知的失败迹象是 ⏸ Pending approval（用户必须批准该服务；请参阅下方的“验证连接”）和首次使用时出现 401 错误（请参阅“故障排除”）。

1. 获取 API 密钥

如果你已有 API 密钥，请跳至步骤 2。

访问 Metis 账户控制面板：

https://fcahandbookharnessimplementation.onrender.com

• 点击**“Create Account”**（主页上的弹窗）
• 完成 Stripe 付款流程（账户为付费账户）
• 前往 API Keys 并生成一个新密钥
• 安全保存密钥

2. 将客户端连接到远程服务

远程服务地址为：

https://fcahandbookharnessimplementation.onrender.com/mcp

它使用 Streamable HTTP 传输，并要求在每个请求的 Authorization 标头中以 bearer token 的形式提供 API 密钥。

**重要：**请通过环境变量或密钥管理器提供密钥，绝不要将其作为字面值写入可能提交到共享代码仓库的配置文件中。请在启动客户端之前，将以下行添加到 shell 启动文件（~/.bashrc、~/.zshrc 等）中，以便客户端自身的进程环境中包含此变量：

export METIS_API_KEY="sk_live_..."

将 sk_live_... 替换为你 Metis 账户中的实际 API 密钥。

在 Windows 上，请改为在命令提示符中运行 setx METIS_API_KEY "sk_live_..."，然后重新启动客户端。无论使用哪种方式，都请在设置变量后启动客户端；如果可以，请从终端启动：从 Dock、Spotlight 或“开始”菜单启动的应用可能无法读取 shell 启动文件中设置的变量。

2a. Claude Code

最简单的方式是使用 CLI，它会为你写入正确的文件。请按示例使用单引号准确引用标头，这样 shell 就不会在 claude mcp add 读取 ${METIS_API_KEY} 之前对其进行展开。否则，你的实际密钥会作为字面值写入配置文件，这正是上文提示中警告的硬编码。

claude mcp add --transport http --scope user fca-handbook-harness-mcp https://fcahandbookharnessimplementation.onrender.com/mcp --header 'Authorization: Bearer ${METIS_API_KEY}'

项目专用配置请使用 --scope project，而不是 --scope user。如果你更愿意直接编辑文件，请将以下内容写入 ~/.mcp.json（适用于所有项目），或写入项目根目录下的 .mcp.json（仅适用于该项目）。这些都是独立文件，不在 .claude/ 目录中；Claude Code 不接受 .claude/settings.json 中的 mcpServers 键。

{
  "mcpServers": {
    "fca-handbook-harness-mcp": {
      "type": "http",
      "url": "https://fcahandbookharnessimplementation.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer ${METIS_API_KEY}"
      }
    }
  }
}

Claude Code 启动时会从环境中替换 ${METIS_API_KEY}。如果该变量在启动时未设置，Claude Code 会将字面文本 ${METIS_API_KEY} 作为密钥发送（并发出警告），从而导致 401 错误，很容易被误认为是密钥错误。请从运行 [ -n "$METIS_API_KEY" ] && echo set 会打印 set 的 shell 启动 Claude Code。如果添加服务后没有看到工具，请重启 Claude Code。

2b. 其他客户端

Cursor、VS Code（Copilot）、Gemini CLI、Cline 以及其他开发工具和 Agent 框架，只要提供 URL 和自定义标头，就可以连接远程 MCP 服务。它们应该可以使用以下设置，但我们尚未进行测试。字段名称和文件位置因客户端而异，且仍在变化，因此请参考你所用客户端的文档，了解如何添加远程 MCP 服务。

• URL： https://fcahandbookharnessimplementation.onrender.com/mcp
• 传输方式： Streamable HTTP
• 标头： Authorization: Bearer <your API key>。如果客户端支持，请从环境变量读取密钥。
• 超时： 快速调用需要 60-120 秒，完整调用耗时更长。如果客户端的默认超时时间较短，请调长。

不同客户端引用环境变量的语法各不相同。例如，Cursor 文档中使用 ${env:METIS_API_KEY}，而 Claude Code 使用 ${METIS_API_KEY}。请使用客户端自己的语法，切勿使用字面值密钥。

仅支持远程服务免认证或 OAuth 认证的客户端无法发送静态 API 密钥。请在该客户端中使用本地服务。

3. 验证连接

Claude Code，仅首次运行： 首次在包含新增或已更改的项目范围 .mcp.json 的项目中启动 claude（以交互方式运行，而非使用 -p）时，Claude Code 会在连接前显示一次性的服务信任/批准提示。在你接受之前，服务会处于“等待批准”状态，其工具实际上无法使用（运行 claude mcp list 会显示 ⏸ Pending approval）。请接受提示，或在现有会话中运行 /mcp 并在那里批准。此限制不适用于 ~/.mcp.json（全局范围）。

连接后，你应该能在 Agent 工作流中看到 evaluate_fca_handbook_applicability 可用作工具。如果没有显示，请查看下方的故障排除部分。

请通过检查工具是否已列出进行验证。不要仅为测试连接而调用该工具：每次调用都会执行真实分析，并向你的账户计费。

替代方案：在本地运行服务（stdio）

如果你的客户端无法连接上述远程服务，请使用此方案。一个小型本地服务会在你的计算机上运行，并使用相同的 API 密钥将每次调用转发到托管的 Harness。你需要 Python 3.10 或更高版本。

安装本地服务

pip install fca-handbook-harness-mcp

配置 MCP 客户端（本地）

以下 mcpServers JSON 结构适用于大多数桌面端／IDE MCP 客户端，但配置文件的位置和重启步骤因客户端而异。请选择与你使用的客户端相对应的方式。

重要： Harness API 密钥应在运行时通过环境变量或密钥管理器提供，切勿将其作为字面值硬编码到可能提交到共享代码库的配置文件中。支持两种方式——请选择一种，因为它们需要不同的 MCP 配置：

• 方式 A — Shell 配置文件。 在启动 MCP 客户端（VS Code、Claude Desktop 等）之前，将 export METIS_API_KEY="sk_live_..." 添加到 shell 启动文件（~/.bashrc、~/.zshrc 等）中，以便该变量存在于客户端自身的进程环境中。使用此方式时，MCP 配置应通过变量替换引用该变量：

  "env": { "METIS_API_KEY": "${METIS_API_KEY}" }
  

• 方式 B — .env 文件。 在项目目录中创建 .env 文件，其中包含 METIS_API_KEY=sk_live_...。服务会在启动时自行加载该文件（通过 load_dotenv()）——MCP 客户端无需获取该值。使用此方式时，请从 MCP 配置中完全省略 env 块。 不要照搬方式 A 中的 "${METIS_API_KEY}" 片段——客户端自身的环境中不会设置该变量，因此替换会静默失败，并将字面字符串 ${METIS_API_KEY} 作为 API 密钥传入。这会导致 401 错误，很容易被误认为密钥无效或已撤销。

⚠️ 如果 MCP 配置位于主目录（~/.mcp.json），而非项目本地位置（项目根目录中的 .mcp.json），它就会应用于这台机器上的每个项目——其中一个多余的 ${METIS_API_KEY} 占位符会导致所有项目的 harness 都无法正常工作，而不只是你正在配置的项目。除非你明确需要在整台机器上共享密钥，否则请优先使用项目本地配置。

Claude Code（本地）

Claude Code（Claude IDE 扩展）支持全局（用户级）和项目级 MCP 配置。注意： MCP 服务应配置在 .mcp.json 文件中，切勿配置在 .claude/settings.json 中——该文件仅用于权限／偏好设置，不识别 mcpServers 键（Claude Code 会以 Unrecognized field: mcpServers 报错并拒绝该配置）。

添加任一作用范围的最简单方式是直接使用 CLI，它会为你写入正确的文件。请按所示（使用单引号）准确引用 ${METIS_API_KEY}，这样 shell 就不会在 claude mcp add 读取之前展开它——否则，实际密钥会以字面值写入配置文件，而本节要避免的正是这种硬编码：

claude mcp add --scope user fca-handbook-harness-mcp -e 'METIS_API_KEY=${METIS_API_KEY}' -- fca-handbook-harness-mcp

这是方式 A——按照下文所示，在 shell 配置文件中导出实际密钥。对于项目本地配置，请使用 --scope project，而不是 --scope user。如果你希望直接编辑文件，或想使用方式 B（.env），请参阅下文。

全局配置（建议 FS 律所使用）

如果你需要在多个项目中工作，请全局配置 MCP，以便随处使用。由于此文件是整台机器共享的，请使用 方法 A——单项目的 .env 查找路径不适合全局配置。

文件位置： ~/.mcp.json（你的主目录——注意，这是一个独立文件，不在 .claude/ 内）

编辑或创建 ~/.mcp.json，并添加：

{
  "mcpServers": {
    "fca-handbook-harness-mcp": {
      "command": "fca-handbook-harness-mcp",
      "env": {
        "METIS_API_KEY": "${METIS_API_KEY}"
      }
    }
  }
}

然后在启动 Claude Code 之前，将以下内容添加到你的 shell 配置文件中（例如 ~/.bashrc、~/.zshrc、~/.fish/config.fish）：

export METIS_API_KEY="sk_live_..."

将 sk_live_... 替换为你 Metis 账户中的实际 API 密钥。Claude Code 启动服务时，会将此环境变量中的 ${METIS_API_KEY} 替换为对应值——如果此时未设置该变量，Claude Code 就会以字面字符串 ${METIS_API_KEY} 加载服务（并发出警告），这正是导致下方「故障排除」中所述误导性 401 错误的原因。

重启： 重启 Claude Code。连接成功后，所有项目中都可以使用 evaluate_fca_handbook_applicability 工具。

项目级配置（单项目设置）

如果你只需要在某个特定项目中使用 MCP，请改为在项目本地进行配置。这与方法 B 最匹配。

文件位置： 项目根目录中的 .mcp.json（一个独立文件，不在 .claude/ 内）

编辑或创建 .mcp.json 并添加以下内容——如上方方法 B 所述，不要添加 env 块：

{
  "mcpServers": {
    "fca-handbook-harness-mcp": {
      "command": "fca-handbook-harness-mcp"
    }
  }
}

然后在项目根目录中创建一个 .env 文件，内容如下：

METIS_API_KEY=sk_live_...

将 sk_live_... 替换为你 Metis 账户中的实际 API 密钥。

重要： 项目级 .mcp.json 和 .env 文件通常会被提交到版本控制中——提交前，请确保将 METIS_API_KEY 添加到 .gitignore（.mcp.json 本身不包含机密信息，因为方法 B 不包含 env 块），或者改用全局配置方式（建议 FS 律所使用）。

重启： Claude Code 会自动检测更改并重新加载 MCP 连接（你也可以重启 IDE）。

Claude Desktop（本地）

文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

Claude Desktop 的配置本质上是整台机器共享的（没有项目本地配置方式），因此方法 A 更合适——在此使用方法 B 前，请参阅上方的 ⚠️ 说明。如果文件已存在，请向其中添加 mcpServers 条目，而不要覆盖整个文件。在 Windows 上，使用 setx 设置变量（参见上方第 2 步），然后重启 Claude Desktop。

方法 A——Shell 配置文件：

{
  "mcpServers": {
    "fca-handbook-harness-mcp": {
      "command": "fca-handbook-harness-mcp",
      "env": {
        "METIS_API_KEY": "${METIS_API_KEY}"
      }
    }
  }
}

在启动 Claude Desktop 之前，在系统环境中设置 METIS_API_KEY（例如，在 ~/.bashrc、系统偏好设置中，或通过图形界面设置）：

export METIS_API_KEY="sk_live_..."

方法 B——.env 文件： 在 Claude Desktop 的运行目录中创建 .env 文件，内容为 METIS_API_KEY=sk_live_...；并使用上方省略了整个 env 块的配置（不要保留带有 ${METIS_API_KEY} 占位符的 env 块——参见上方方法 B 的警告）。

重启： 退出并重启 Claude Desktop 应用。连接成功后，即可使用 evaluate_fca_handbook_applicability 工具。

其他客户端（本地）

这些客户端通常使用与上方 Claude Desktop 相同的 mcpServers JSON 格式。请查阅客户端文档，了解配置文件位置、重启步骤，以及客户端是否像 Claude Code 和 Claude Desktop 一样在 env 块中进行 ${VAR} 替换（有些客户端使用图形界面连接器而非 JSON 文件，或者可能完全不进行替换——依赖方法 A 前请先确认）。

验证本地连接

请参阅上方的验证连接。针对项目作用域 .mcp.json 的首次运行审批流程同样适用。

使用工具

该工具接受两个参数：

• user_input（必填，最多 5000 个字符）：将所有内容合并为一段文本，包括公司类型、产品／服务、目标市场、监管问题等。
• analysis_mode（可选）："quick"（默认，约 60-120 秒）或 "full"（耗时更长，提供详细的条件推理）

该工具会返回：

• summary：用 2-3 句话概述适用情况
• entry_analysis：检索到的 FCA Handbook 条目及其推理过程
• obligations：高置信度和低置信度／相关性较低的义务；每项义务还可附上适用的具体条件
• refinement_suggestions：分析无法根据输入确定的内容及其重要性，并附上可提升准确性的具体修改建议
• citations：FCA Handbook 中的逐字引文，并标注约束级别（R=规则，G=指导）
• tokens：包含 input、output 和 total token 数量的对象，用于追踪成本／复杂度

故障排除

远程服务：工具返回“Missing API key”或“Invalid or revoked API key”：

• “Missing API key”表示客户端未发送 Authorization: Bearer <key> 标头。请检查配置中的 headers 条目。
• 如果你已在控制面板确认密钥有效，但仍收到“Invalid or revoked API key”，通常是因为 ${METIS_API_KEY} 占位符未被替换，这是因为客户端启动时未设置该变量。请从运行 [ -n "$METIS_API_KEY" ] && echo set 会输出 set 的 shell 启动客户端。否则，请从控制面板重新复制密钥，确保没有多余的空格或换行符。

远程服务：工具未列出：

• 在 Claude Code 中运行 claude mcp list。⏸ Pending approval 表示需要批准该服务（参见上文“验证连接”）。添加服务后，请重启客户端。
• 检查客户端是否支持 Streamable HTTP 传输，并能发送自定义 Authorization 标头。如果不支持，请使用本地服务。

远程服务：连接在调用期间断开或超时：

• 快速调用需要 60-120 秒，完整调用耗时更长。如果客户端的默认超时时间较短，请调高超时设置。如果客户端或网络无法保持连接这么久，请改用本地服务。

Claude Code：“Settings validation failed: Unrecognized field: mcpServers”：

• 这表示你将 mcpServers 添加到了 .claude/settings.json（或 ~/.claude/settings.json）中——该文件不支持此配置。请按照上文“本地 Claude Code”部分的说明，将 mcpServers 配置块移到 .mcp.json（项目级）或 ~/.mcp.json（全局）中，或者运行 claude mcp add --scope project|user ...，让 Claude Code 为你写入配置。

Claude Code：模型似乎隐约知道有一个“MCP”存在，却不知道它的名称或功能，也从不调用它：

• 这是首次运行时的批准关卡（参见上文“验证连接”），并非工具描述问题——未经批准的项目级 .mcp.json 服务实际上不会连接，因此模型收不到它的真实名称、描述或架构，只能看到通用的 MCP 资源工具。运行 claude mcp list 确认（⏸ Pending approval 表示确实如此），然后运行 /mcp 或以交互方式重启 claude 来批准。

工具未显示（Claude Desktop；大多数桌面 MCP 客户端也有同类问题）：

• 确认配置文件路径（因平台而异，见上文）
• 确认 fca-handbook-harness-mcp 可通过命令行解析（which fca-handbook-harness-mcp / where fca-handbook-harness-mcp）。桌面 MCP 客户端通常以精简环境启动，可能无法使用与你的 shell 相同的 PATH——如果无法解析该命令，请将 "command": "fca-handbook-harness-mcp" 替换为查询结果中的绝对路径
• 重启 MCP 客户端（不只是重新加载）

401 Unauthorized，但你已在控制面板确认密钥有效：

• 检查 MCP 配置中是否仍包含未被替换的字面量 ${METIS_API_KEY}（或类似占位符）——当使用方法 B（.env）但配置仍包含为方法 A 编写的 env 配置块时，就会发生这种情况。检查实际启动的服务进程的环境变量（例如 Linux 上的 /proc/<pid>/environ），确认它实际收到的值
• 确认已设置 METIS_API_KEY——可以在配置的 env 中设置（方法 A），也可以在服务能够找到的 .env 文件中设置（方法 B），但不能两者兼用，也不能都不设置
• 检查密钥是否正确（从控制面板重新复制）
• 确保密钥中没有多余的空格或换行符

连接超时：

• 分析可能需要 60-120 秒（快速模式），完整模式则需要更长时间
• 确保可以访问互联网并连接到 fcahandbookharnessimplementation.onrender.com

文件

• mcp_server.py — MCP 服务实现（主入口；其文档字符串是工具架构的权威来源）
• pyproject.toml — PyPI 软件包清单
• server.json — MCP 注册表清单（registry.modelcontextprotocol.io 格式）
• manifest.json — MCPB/Smithery 捆绑包清单
• requirements.txt — Python 依赖项（mcp、requests）
• uv.lock — 固定的依赖项解析结果，确保 uv run 可复现
• __init__.py — Python 软件包标记文件
• README.md — 本文件
• LICENSE — MIT 许可证
• .gitignore — Git 忽略规则
• .mcpbignore — 从 MCPB 捆绑包中排除的文件

支持

如有疑问或问题，请联系：[email protected]

---

产品： Metis FCA Handbook AI Harness
许可证： MIT