trustmodel-mcp

TrustModel MCP 服务

一个 Model Context Protocol（MCP）服务，可让任何 AI Agent 调用 TrustModel 进行可信度评估、安全性／偏见分析，以及端到端 Agentic 轨迹评估。

兼容 Claude Code、Cursor、Windsurf、Claude Desktop 以及任何其他兼容 MCP 的客户端。

快速开始

1. 获取 API 密钥

在 app.trustmodel.ai 注册，并在 设置 → API 密钥 下创建 API 密钥。密钥格式为 tm-{env}-{keyid}_{secret}（例如：tm-prod-abc12345_0123456789abcdef…）。

2. 配置 MCP 客户端

Claude Code

claude mcp add trustmodel \
  --env TRUSTMODEL_API_KEY=tm-prod-xxxx_yyyy \
  -- npx -y @trustmodel/mcp-server

Cursor / Windsurf

将以下内容添加到 MCP 配置文件（.cursor/mcp.json 或同等文件）中：

{
  "mcpServers": {
    "trustmodel": {
      "command": "npx",
      "args": ["-y", "@trustmodel/mcp-server"],
      "env": {
        "TRUSTMODEL_API_KEY": "tm-prod-xxxx_yyyy"
      }
    }
  }
}

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "trustmodel": {
      "command": "npx",
      "args": ["-y", "@trustmodel/mcp-server"],
      "env": {
        "TRUSTMODEL_API_KEY": "tm-prod-xxxx_yyyy"
      }
    }
  }
}

环境变量

变量	必需	默认值	说明
TRUSTMODEL_API_KEY	否*	—	你的 TrustModel API 密钥（tm-{env}-{keyid}_{secret}）。*本地工具（trustmodel_evaluate_local、trustmodel_govern）无需此项；使用校准云端工具时则必需。
TRUSTMODEL_TRACE_DIR	否	~/.trustmodel-mcp/traces/	流式轨迹会话以仅追加的 JSONL 格式持久化到此处。通过读取时重新水合，会话可在服务重启后保留。
TRUSTMODEL_PROFILE	否	default	工具配置。default 仅开放日常使用的工具；security / advanced / all 会开放所有工具。请参阅工具配置。
TRUSTMODEL_ADVANCED_TOOLS	否	false	设为 true，即可不受 TRUSTMODEL_PROFILE 限制地开放所有工具。
TRUSTMODEL_AGT_DISCOVERY_ENABLED	否	false	启用会访问文件系统的 Shadow Discovery 工具（trustmodel_shadow_discovery_*）。未设置时，这些工具会返回跳过报告。（仅在启用高级配置时相关。）

工具配置

为遵循 5–8 个工具的最佳实践上限（工具过多会降低 Agent 选择工具的效果），该服务仅开放少量默认工具，并将高级工具设为可选启用。

默认配置（6 个工具） — 日常常用工具： trustmodel_evaluate_local · trustmodel_score · trustmodel_trace_start · trustmodel_trace_step · trustmodel_trace_finalize · trustmodel_govern

高级配置 — 设置 TRUSTMODEL_PROFILE=security（或 advanced / all，或设置 TRUSTMODEL_ADVANCED_TOOLS=true）以额外开放：trustmodel_evaluate（云端批量评估）、trustmodel_credits、trustmodel_upload_trace、trustmodel_evaluate_agent、trustmodel_score_agent、trustmodel_mcp_scan_server、trustmodel_shadow_discovery_*、trustmodel_redteam_* 和 trustmodel_shadowai_*——共 20 个工具。

claude mcp add trustmodel --env TRUSTMODEL_PROFILE=security -- npx -y @trustmodel/mcp-server

工具

该服务提供六个领域的 18 个工具。使用此表选择合适的工具；完整的输入／输出文档见下文。

工具	分组	使用场景
trustmodel_evaluate	评估	启动模型的批量信任评估（安全性、偏见、准确性等）；返回一个用于轮询的 id。
trustmodel_score	评估	获取使用 trustmodel_evaluate 创建的评估的状态／分数。
trustmodel_credits	评估	查看剩余的 API 额度。
trustmodel_trace_start	Agentic Trace	在 Agent 开始工作前开启流式追踪会话。
trustmodel_trace_step	Agentic Trace	在 Agent 运行时记录一个推理步骤、工具调用、工具结果或响应。
trustmodel_trace_finalize	Agentic Trace	关闭会话、上传追踪记录，并自动创建 Agent 评估任务。
trustmodel_upload_trace	Agentic Trace	单次操作：如果未以流式方式发送预先组装好的追踪记录，则通过 PUT 上传追踪 JSON。
trustmodel_evaluate_agent	Agentic Trace	针对已上传的追踪记录 file_path 创建 Agentic 评估任务。
trustmodel_score_agent	Agentic Trace	获取 Agentic 评估任务的分数／等级。
trustmodel_mcp_scan_server	安全	对第三方 MCP 服务的工具列表进行安全扫描，查找存在风险／可被滥用的工具。
trustmodel_shadow_discovery_scan_paths	影子发现	扫描本地文件系统路径，查找未注册／隐藏的 AI 用法。
trustmodel_shadow_discovery_fingerprint_keys	影子发现	检测并识别磁盘上找到的 OpenAI／Anthropic API 密钥。
trustmodel_redteam_evaluate	红队	针对模型／端点启动对抗性红队评估。
trustmodel_redteam_results	红队	获取红队评估结果。
trustmodel_redteam_list_probes	红队	列出可用的红队探测项／攻击类别。
trustmodel_shadowai_scan	影子 AI	启动影子 AI 扫描，查找环境中未注册的 AI 使用情况。
trustmodel_shadowai_results	影子 AI	获取影子 AI 扫描结果。
trustmodel_shadowai_events	影子 AI	流式获取影子 AI 扫描的检测事件。

影子发现工具（trustmodel_shadow_discovery_*）会访问本地文件系统。这些工具始终会列出，但除非在服务上设置 TRUSTMODEL_AGT_DISCOVERY_ENABLED=true，否则会返回跳过报告。

经典评估

trustmodel_evaluate

针对指定的 AI 模型创建批量评估任务。后端会运行一套全面的评估（安全性、偏见、准确性、幻觉、推理等），并返回一个 id，你可以使用 trustmodel_score 轮询该任务。

输入：

• model_identifier（string，必填）— 例如 "gpt-4o"、"claude-sonnet-4-5"。通过 GET /sdk/v1/models/ 查询。
• vendor_identifier（string，必填）— 例如 "openai"、"anthropic"、"google"。
• api_key（string，可选）— 用于 BYOK 的供应商 API 密钥。不填写则使用 TrustModel 的平台密钥。此处不要传入 TrustModel API 密钥——应将其设置在 TRUSTMODEL_API_KEY 环境变量中。
• categories（string[]，可选）— 要评估的类别名称。仅当 evaluation_type 为 "Custom" 或 "Score Only" 时才会生效。
• evaluation_type（string，可选，默认值为 "Custom"）— 可选值："Custom"、"Score Only"、"Comprehensive"、"Limited"、"Quick Scan"。
• application_type（string，可选，默认值为 "generic"）— chatbot、knowledge-agent、creation-tool、document-repository、analysis-tool、automation-agent、generic。
• user_personas（string[]，可选，默认值为 ["external-customer"]）— 可选值：external-customer、internal-employee、technical-user、domain-expert、vulnerable-groups、generic。
• application_description（string，可选）。
• domain_expert_description（string，可选）— 当 user_personas 包含 "domain-expert" 时使用。可选值："cross-domain"（默认值）、"medical"、"commercial_banking"。
• model_config_name（string，可选）— 此评估任务的显示名称。
• template_id（UUID，可选）、template_name（string，可选）— 复用或重命名现有评估模板。

trustmodel_score

获取通过 trustmodel_evaluate 创建的评估的详细信息（状态、完成百分比、评分）。

输入：

• evaluation_id（integer 或 numeric string，必填）— trustmodel_evaluate 返回的 id。

trustmodel_credits

查看剩余的 API 额度。无需输入。

Agentic 轨迹评估

TrustModel 通过读取 AI Agent 的执行轨迹（思考、工具调用、工具结果、响应）来评估 AI Agent，并从 4 个类别进行评分：tool_use_accuracy、reasoning_quality、goal_completion、safety_compliance。

提交轨迹有两种方式——流式（适用于实时 Agent，优先推荐）和单次提交（适用于已有预先组装好的轨迹）。

流式采集（优先推荐）

开启会话，在 Agent 工作时记录步骤，并在结束时完成会话。完成会话后会将轨迹上传至云存储，并自动创建评估任务。

trustmodel_trace_start

开启新的轨迹会话。

输入：

• goal（string，必填）— Agent 试图实现的目标。
• name（string，必填）— 评估任务的显示名称。
• agent_framework（string，必填）— 例如 "langchain"、"crewai"、"claude-code"、"custom"。
• agent_model（string，可选）— 例如 "gpt-4o"、"claude-sonnet-4-5"。
• user_query（string，可选）— 原始用户提示词（若与 goal 不同）。
• expected_outcome（string，可选）。
• metadata（object，可选）— 可自由填写的透传元数据。

返回： { trace_id, started_at }。

trustmodel_trace_step

向当前活动会话追加单个步骤。每个推理步骤、工具调用、工具结果或面向用户的回复调用一次。

输入：

• trace_id（string，必填）——来自 trustmodel_trace_start。
• step_type（enum，必填）——可选值：thought、think、tool_call、tool_result、observation、decision、error、human_input、response、final_answer。
• content（string，必填）——步骤的可读文本。允许为空字符串。
• tool_name（string，可选）、tool_args（object，可选）——与 tool_call 搭配使用。
• tool_result（string 或 object，可选）、tool_call_success（boolean，可选）——与 tool_result 搭配使用。
• model_used（string，可选）、input_tokens / output_tokens（int，可选）、duration_ms（int，可选）、timestamp（ISO 8601，可选）。

返回： { trace_id, step_number, steps_recorded }。step_number 会自动分配。

trustmodel_trace_finalize

关闭会话、上传追踪记录，并自动创建评估运行。

输入：

• trace_id（string，必填）。
• final_response（string，可选）、actual_outcome（string，可选）、goal_achieved（boolean，可选）、success（boolean，可选）、total_duration_ms（int，可选——若省略，则根据步骤时长计算）。
• goal / name / agent_framework / agent_model / expected_outcome（均为可选）——如果 Agent 在运行时获得了更多信息，则覆盖启动时的元数据。

返回（成功时）： { trace_id, file_path, expires_in, step_count, evaluation_run_id, evaluation_status, evaluation_message }。

返回（上传成功后评估失败时）： { trace_id, file_path, expires_in, step_count, evaluation_error }。你可以通过 trustmodel_evaluate_agent({ file_path, goal, name, agent_framework }) 重试评估，无需重新上传。

一次性操作（预先组装的追踪记录）

trustmodel_upload_trace

将已构建的追踪 JSON 对象 PUT 到云存储。返回 file_path，随后将其传递给 trustmodel_evaluate_agent。

输入：

• trace（object，必填）——完整的 AgentTrace JSON。

返回： { file_path, expires_in }。

trustmodel_evaluate_agent

针对先前上传的追踪记录创建 Agent 评估运行。

输入：

• file_path（string，必填）——来自 trustmodel_upload_trace 或 trustmodel_trace_finalize。
• goal / name / agent_framework（string，必填）。
• agent_model / expected_outcome / actual_outcome（string，可选）。
• goal_achieved（boolean，可选）。

返回： { evaluation_run_id, status, message }。

trustmodel_score_agent

获取 Agent 评估运行的详细信息（分数、等级、摘要）。

输入：

• evaluation_run_id（integer 或数字字符串，必填）。

安全性

trustmodel_mcp_scan_server

使用 AGT 的 MCP 安全扫描器检查第三方 MCP 服务的工具列表，以检测工具投毒、域名抢注、隐藏指令和 rug-pull 模式。采用静态分析——不使用大模型、不联网、结果确定。旨在作为启用第三方 MCP 服务前的预注册检查。

输入：

• tools（array，必填）——第三方服务的工具定义（name、description、可选的输入 schema）。

返回： 包含整体状态（ok / warning / blocked）、检测到的最高严重级别以及各工具检测结果的 ScanReport。

影子发现

涉及文件系统操作。除非 TRUSTMODEL_AGT_DISCOVERY_ENABLED=true，否则返回跳过报告。

trustmodel_shadow_discovery_scan_paths

遍历本地文件系统路径，在配置文件（agentmesh.yaml、crewai.yaml、mcp.json、claude_desktop_config.json 等）、Dockerfile / compose 文件以及（可选）源代码中检测 Agent。将检测结果与调用方提供的注册表核对，并将未注册的 Agent 作为 影子 Agent 返回，同时提供 AGT 风险评分和修复建议。仅进行静态分析。

输入：

• paths（string[]，必需）— 要扫描的本地路径。
• registry（array，可选）— 用于核对的已知 Agent（did、name、owner 等）。

trustmodel_shadow_discovery_fingerprint_keys

通过调用各提供商的只读模型端点，为一批提供商 API 密钥（OpenAI / Anthropic）生成指纹——不会运行推理。可访问的密钥会被标记为高风险（可能存在凭据泄露）；已撤销的密钥仅作信息提示。密钥内容绝不会被记录或返回——只返回 provider:****last4 指纹。

输入：

• keys（string[]，必需）— 要探测的 API 密钥。

红队

trustmodel_redteam_evaluate

针对兼容 OpenAI 的目标运行对抗性红队评估。探测涵盖与 OWASP LLM Top 10（2025）对应的 8 类攻击——提示词注入、越狱、PII 提取、诱导偏见、触发幻觉等。

输入：

• model_name（string，必需）— 例如 "openai/gpt-oss-20b:free"。
• api_key（string，必需），api_base_url（string，必需）— 例如 "https://openrouter.ai/api/v1"。
• categories（string[]，可选），severities（string[]，可选），metadata（object，可选）。

返回： 评估 id — 使用 trustmodel_redteam_results 轮询结果。

trustmodel_redteam_results

获取红队评估的状态、进度、总分、各类别明细和严重程度分组。运行期间返回部分进度，完成后返回完整摘要。

输入：

• evaluation_id（integer 或 numeric string，必需）。

trustmodel_redteam_list_probes

浏览红队探测库（仅元数据——不会公开载荷）。可按类别、严重程度或标签筛选。

输入：

• category（string，可选），severity（string，可选），tag（string，可选）。

影子 AI

trustmodel_shadowai_scan

启动针对 GitHub 组织 / 仓库以及（可选）GCP 项目的影子 AI 发现扫描。通过检查源代码中的 LLM SDK 使用情况（15 个库）检测未注册的 AI，并列出 Vertex AI 端点、带有 AI 环境变量的 Cloud Run 服务以及 BigQuery ML 模型。

输入：

• github_orgs（string[]，可选），github_repos（owner/name 形式的 string[]，可选），gcp_projects（string[]，可选），metadata（object，可选）。

返回： 扫描 id — 使用 trustmodel_shadowai_results 轮询结果，使用 trustmodel_shadowai_events 分页查看发现项。

trustmodel_shadowai_results

获取影子 AI 扫描的状态、扫描筛选条件、事件总数，以及按系统类型 / 来源汇总的发现项。

输入：

• scan_id（integer 或 numeric string，必需）。

trustmodel_shadowai_events

分页查看单条发现事件——每条事件对应一个发现的 AI 系统，包含 system_type、discovered_via、证据以及稳定的 system_id 指纹。可按 system_type 或 source 筛选。

输入：

• scan_id（integer 或 numeric string，必需），以及可选的 system_type / source 筛选条件和分页参数。

示例 — 流式捕获 Agent

trustmodel_trace_start({
  goal: "Book a flight from NYC to SF",
  name: "Flight booking agent",
  agent_framework: "claude-code",
  agent_model: "claude-sonnet-4-5"
})
→ { trace_id: "trace-abc123def456", started_at: "..." }

trustmodel_trace_step({ trace_id, step_type: "thought",
  content: "Need to search flights first." })
→ { step_number: 1, steps_recorded: 1 }

trustmodel_trace_step({ trace_id, step_type: "tool_call",
  content: "Searching flights",
  tool_name: "flight_api.search",
  tool_args: { from: "NYC", to: "SFO", date: "2026-04-20" },
  duration_ms: 500 })
→ { step_number: 2, steps_recorded: 2 }

trustmodel_trace_step({ trace_id, step_type: "tool_result",
  content: "Found UA123 at $350",
  tool_name: "flight_api.search",
  tool_result: { flight: "UA123", price: 350 },
  tool_call_success: true })
→ { step_number: 3, steps_recorded: 3 }

trustmodel_trace_step({ trace_id, step_type: "final_answer",
  content: "Booked UA123 for $350." })
→ { step_number: 4, steps_recorded: 4 }

trustmodel_trace_finalize({ trace_id,
  final_response: "Booked UA123 for $350.",
  goal_achieved: true })
→ {
    file_path: "agent-traces/<org>/<ts>_<uuid>.json",
    step_count: 4,
    evaluation_run_id: 42,
    evaluation_status: "processing"
  }

trustmodel_score_agent({ evaluation_run_id: 42 })
→ { status: "processing" | "completed", scores: [...], grade, overall_score, ... }

示例 — 真实的 Agent 工作流

以下是一个真实场景：你让 Claude Code 执行一项任务，同时通过 TrustModel 跟踪捕获来监控自身。最后，TrustModel 会从工具使用准确性、推理质量、目标完成度和安全合规性等方面为 Agent 评分——在你将 Agent 部署到生产环境之前，为你提供一份可信度报告。

场景：研究 Agent

将此提示词粘贴到 Claude Code（或任何已连接 TrustModel 的 MCP 客户端）中：

Research the pros and cons of using WebSockets vs Server-Sent Events for
real-time notifications in a web app, while recording a TrustModel trace.

Before you start, call trustmodel_trace_start with:
  goal: "Research WebSockets vs SSE for real-time notifications"
  name: "Research agent"
  agent_framework: "claude-code"

As you work, record a trustmodel_trace_step for each action:
  - When you reason about the topic → step_type: "thought"
  - When you search or fetch info  → step_type: "tool_call" with tool_name
  - After getting results back      → step_type: "tool_result"
  - When you draw a conclusion      → step_type: "observation"

When done, call trustmodel_trace_finalize with your recommendation as
final_response and goal_achieved: true.

Print the evaluation_run_id so I can check the trust report.

工作原理

Agent 会研究主题，同时自行追踪每一步推理、搜索和结论。典型会话如下：

trustmodel_trace_start({ goal: "Research WebSockets vs SSE...", name: "Research agent", ... })
→ { trace_id: "trace-9a2f71c3b84e" }

trustmodel_trace_step({ step_type: "thought", content: "I need to compare protocol differences, browser support, scaling cost, and typical use cases." })
→ { step_number: 1 }

trustmodel_trace_step({ step_type: "tool_call", tool_name: "WebSearch", tool_args: { query: "websockets vs server-sent events performance comparison" } })
→ { step_number: 2 }

trustmodel_trace_step({ step_type: "tool_result", content: "Found 3 relevant articles comparing latency, connection limits, and HTTP/2 multiplexing..." })
→ { step_number: 3 }

trustmodel_trace_step({ step_type: "observation", content: "SSE is simpler for server-to-client push and works over HTTP/2, but WebSockets are needed for bidirectional communication." })
→ { step_number: 4 }

... (more research, comparisons, trade-off analysis) ...

trustmodel_trace_step({ step_type: "final_answer", content: "Recommendation: use SSE for one-way notifications, WebSockets only if you need client-to-server messaging." })
→ { step_number: 10 }

trustmodel_trace_finalize({
  trace_id: "trace-9a2f71c3b84e",
  final_response: "Recommendation: use SSE for one-way notifications...",
  goal_achieved: true
})
→ {
    file_path: "agent-traces/<org>/<timestamp>.json",
    evaluation_run_id: 42,
    evaluation_status: "processing"
  }

评估结果

等待 1–2 分钟后，调用 trustmodel_score_agent({ evaluation_run_id: 42 }) 进行查询。TrustModel 会返回：

{
  "status": "completed",
  "overall_score": 7.6,
  "grade": "C",
  "scores": [
    { "category": "tool_use_accuracy",  "score": 100.0 },
    { "category": "reasoning_quality",  "score": 60.0  },
    { "category": "goal_completion",    "score": 70.0  },
    { "category": "safety_compliance",  "score": 80.0  }
  ],
  "summary": {
    "trust_dimensions": {
      "safety": 9.0, "fairness": 7.0, "privacy": 10.0,
      "transparency": 6.0, "robustness": 10.0, "accountability": 10.0
    }
  }
}

系统还会生成一份包含详细调查结果的 PDF/HTML 报告，可通过 TrustModel 控制面板访问。

为什么这很重要

每个需要做决策的 AI Agent——无论是审查代码、处理理赔还是筛选候选人——在投入生产之前都需要一个信任基准。此工作流无需更改 Agent 的核心逻辑，即可为你提供这一基准：只需用 trace_start 包装 Agent，在它运行时记录各个步骤，并在完成后调用 trace_finalize。其余工作由 TrustModel 处理。

追踪持久化

活动追踪会话以仅追加的 JSONL 格式写入 $TRUSTMODEL_TRACE_DIR/<trace_id>.jsonl（默认为 ~/.trustmodel-mcp/traces/）。磁盘是事实来源；内存映射是按需重新加载数据的缓存，因此会话在 MCP 服务重启后仍会保留。成功调用 trustmodel_trace_finalize 后，本地文件会被删除（追踪数据已存储在云端）。

闲置超过 30 分钟的会话会自动清除。每个服务最多支持 100 个并发会话。

控制面板

报告、评估历史记录以及详细的 PDF/HTML 调查结果可在 TrustModel 控制面板 app.trustmodel.ai 中查看。

故障排除

症状	解决方法
服务立即退出 / 出现 TRUSTMODEL_API_KEY 错误	在客户端的 env 块中设置有效密钥（tm-{env}-{keyid}_{secret}）。前往 app.trustmodel.ai → Settings → API Keys 获取密钥。
trustmodel_shadow_discovery_* 返回跳过报告	在服务端设置 TRUSTMODEL_AGT_DISCOVERY_ENABLED=true。这些工具会访问本地文件系统，默认处于关闭状态。
npx 找不到软件包	确保 Node 版本 ≥ 20.19，并运行 npx -y @trustmodel/mcp-server 以获取最新版本。
客户端未列出工具	编辑配置后重启 MCP 客户端；确认 command/args 与上述示例一致。

TrustModel 开源项目

此 MCP 服务是 TrustModel OSS 工具包的一部分：

• CLI + SDK — PyPI 上的 trustmodel：本地信任评分、治理和云端客户端。pip install trustmodel。
• MCP 服务（此仓库） — npm 上的 @trustmodel/mcp-server：让任何 MCP 客户端都能使用 TrustModel。

许可证

MIT