使用说明

mcpx

MCP架构守护者代理 --运行时检测模型上下文协议服务器的中断模式更改、中毒尝试和受控的向后兼容请求转换。

问题

MCP服务器在运行时公开工具模式，没有版本控制契约。当服务器更新时——重命名参数、更改类型、更改描述——客户端会中断 默默地LLM不会崩溃。它产生了一种变通方法，产生了自信的错误答案。

更糟糕的是，攻击者可以通过巧妙地编辑工具描述来重定向代理行为，从而利用这一点(工具中毒).单个描述更改可以使您的代理在不违反任何架构的情况下泄露凭据。

没有现有的工具在运行时捕捉到这一点。 CI工具，如 mcpdiff 在构建时捕获更改，但仅限于您控制的服务器。MCP网关处理身份验证和路由，但通过不变的模式传递。

mcpx做什么

mcpx是一个位于MCP客户端和服务器之间的透明代理：

┌────────────┐       ┌────────┐       ┌────────────┐
│ Claude     │◄─────►│  mcpx  │◄─────►│ MCP Server │
│ Desktop    │ stdio │        │ stdio │ (local)    │
└────────────┘       └────────┘       └────────────┘

┌────────────┐       ┌────────┐  HTTP/SSE  ┌────────────┐
│ Claude     │◄─────►│  mcpx  │◄──────────►│ MCP Server │
│ Desktop    │ stdio │        │            │ (remote)   │
└────────────┘       └────────┘            └────────────┘

开 第一次连接，它将每个工具的模式和描述快照为固定的基线。开 每个后续连接，它将实时模式与基线进行比较，并：

检测突破性变化 --删除工具、新的必需参数、类型更改
检测中毒 --工具/参数描述注入、隐藏Unicode、可疑参数名称
阻止不安全的工具调用 --返回一个明确的错误，而不是让LLM产生幻觉
记录所有内容 --随时间推移对每个模式更改的完整审计跟踪
建议使用安全垫片 --琐碎的仅重命名映射可以被批准或自动批准

快速开始

# Install
./install.sh
# installs to ~/.local/bin/mcpx by default

# Optional:
# ./install.sh --prefix /usr/local
# ./install.sh --debug
# ./install.sh --ml              # Enable Level 3 semantic similarity detection

# Use as a drop-in proxy wrapper
# Before:  "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]
# After:
mcpx run -- npx -y @modelcontextprotocol/server-github
mcpx run --auto-approve-shims -- npx -y @modelcontextprotocol/server-github

# Or connect to a remote MCP server over HTTP/SSE
mcpx run --upstream https://mcp.example.com/mcp

# With custom headers (e.g. auth tokens)
mcpx run --upstream https://mcp.example.com/mcp -H "Authorization: Bearer sk-..."

在您的Claude桌面配置中(claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "mcpx",
      "args": ["run", "--", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "..."
      }
    },
    "remote-server": {
      "command": "mcpx",
      "args": ["run", "--upstream", "https://mcp.example.com/mcp", "-H", "Authorization: Bearer sk-..."]
    }
  }
}

就是这样，一行换一行。mcpx处理其余部分。

CLI命令

mcpx run -- <command>        # Proxy a local MCP server (stdio)
mcpx run --auto-approve-shims -- <command> # Auto-approve/apply eligible trivial shims
mcpx run --upstream <url>    # Proxy a remote MCP server (HTTP/SSE)
mcpx run --upstream <url> -H "Header: value"  # With custom headers
mcpx baselines list          # Show pinned baselines
mcpx baselines show <name>   # Show baseline details
mcpx baselines delete <name> # Re-pin on next connection
mcpx diff <name>             # Show schema drift
mcpx events <name>           # Show recent audit events
mcpx shims list <name>       # Show shim proposals/decisions for a server
mcpx shims approve <name> <tool> # Approve latest proposal for a tool
mcpx ci scan --baseline <baseline> --target <target> --format json|sarif|both
mcpx ci scan ... --suppress <RULE_ID> [--suppress <RULE_ID> ...]
mcpx ci scan ... --only-new-since <previous-mcpx-report.json>

检测到什么

更改	严重性	操作
工具已删除	中断	阻止调用
已添加必需参数	中断	阻止调用
参数类型已更改	中断	阻止调用
已删除可选参数	警告	日志
描述已更改	警告	中毒分析
描述中隐藏Unicode	已阻止	阻止调用
描述中的注入模式	已阻止	阻止调用
可疑参数名称（例如。 `system_override_instruction`)	阻止	阻止呼叫
参数描述中的注入/隐藏字符	已阻止	阻止调用
琐碎的重命名漂移(`file_path` -> `filepath`)	建议	需要批准（或自动批准）
不平凡的漂移(`user_id` -> `admin_token`)	已阻止	手动更新基线
新增工具	安全	日志
添加可选参数	安全	日志

中毒检测

mcpx扫描：

工具说明
参数名称
参数说明

级别1 （始终打开）：BLAKE3哈希比较——任何更改都会被标记。

2级（默认）：结构分析——Levenshtein相似性，加上正则表达式检测：

指令覆盖尝试("ignore previous instructions")
凭证访问指令("read ~/.ssh/id_rsa")
数据泄露模式("send to https://...")
隐藏的Unicode字符（零宽度空格，RTL覆盖）
BCC渗出（Postmark MCP攻击模式）
高风险参数名称令牌(exec, eval, system, prompt, override等等）

级别3 （选择加入， --ml 标志）：语义相似性——使用局部全迷你LM-L6-v2 嵌入模型（约80MB，下载一次）以检测逃避结构检查的意义保持改写。语义相似度低于0.80的描述被标记为可疑。

# Install with Level 3 enabled
./install.sh --ml

# Or with cargo
cargo install --path crates/mcpx-cli --features ml

自动摆振（安全模式）

Shimming被故意限制，以避免将代理人变成一个困惑的代理人。

管道顺序严格：

先进行中毒检查。
如果检测到中毒，请堵塞，不要填隙。
如果干净，评估微小漂移并生成垫片建议。

当前垫片规则：

只有重命名，琐碎的映射才有资格。
需要类型兼容性。
模糊/非平凡的映射被阻止。
运行时重写键冲突块，并验证敏感目标的映射值。

审批方式：

默认值（推荐）： 只有提案。工具被堵塞 shim_requires_approval 直到你批准。
自动模式： --auto-approve-shims 自动批准并应用合格的小垫片。

手动审批工作流程：

mcpx shims list MyServer
mcpx shims approve MyServer search

所有提案/批准都记录在SQLite中，并反映在 mcpx events.

CI导出（JSON/SARIF）

mcpx ci scan 支持：

用于机器处理的JSON导出
SARIF导出用于本地GitHub代码扫描集成
故障阈值通过 --fail-on warning|breaking|blocked
通过可重复的规则抑制 --suppress <RULE_ID>
基线增量模式 --only-new-since <previous-report.json> （仅在新发现时失败）

支持的规则ID：

MCPX-BREAKING-SCHEMA
MCPX-POISON-TOOL-DESC
MCPX-POISON-PARAM-NAME
MCPX-POISON-PARAM-DESC
MCPX-SHIM-REQUIRES-APPROVAL
MCPX-SHIM-NONTRIVIAL

例子：

mcpx ci scan \
  --baseline .github/ci/mcpx-baseline.json \
  --target .github/ci/mcpx-target.json \
  --format sarif \
  --out artifacts/mcpx-ci.sarif \
  --fail-on blocked

SARIF结果包括规则元数据和物理位置（工件URI+行），因此代码扫描系统可以呈现可操作的警报。

建筑

mcpx是作为一个Rust工作区构建的，带有聚焦的crates：

mcpx核心 --JSON-RPC 2.0和MCP协议类型，快照捕获
mcpx传输 --stdio和HTTP/SSE双向代理、消息泵
mcpx模式 --递归JSON模式差异化、约束填充建议/重写引擎
mcpx毒素 --结构相似性分析、注入模式检测
mcpx毒素ml --（可选）通过ONNX嵌入模型实现语义相似性
mcpx商店 --用于基线、快照、审计日志的SQLite存储
mcpx cli --带clap的CLI二进制文件

扩展mcpx

如果要添加功能，请使用此文件映射：

新CLI命令： crates/mcpx-cli/src/main.rs + crates/mcpx-cli/src/commands/
新数据库表/查询/事件： crates/mcpx-store/src/lib.rs
新的架构漂移规则： crates/mcpx-schema/src/diff.rs
新型中毒探测器： crates/mcpx-poison/src/patterns.rs 和 structural.rs
新的运输方式： crates/mcpx-transport/src/
共享协议类型： crates/mcpx-core/src/

推荐工作流程：

为您正在接触的板条箱添加测试。
实施最小的有用更改。
跑 cargo test --workspace.
跑 cargo check --workspace --all-targets 用于跨机箱集成检查。

初学者功能想法：

mcpx diff --live 单次连接模式（捕获/差异/退出）。
mcpx events <server> --type <event_type> 过滤。
Shim MVP用于重命名参数 crates/mcpx-schema/src/shim.rs.
mcpx.toml 阈值和允许/阻止覆盖的策略配置。

路线图

[x] v0.1——stdio代理、自动基线、模式差异、中毒检测（级别1+2）、阻塞
[x] v0.2--~~ HTTP/SSE传输~~，~~自动匀场（向后兼容请求重写）~~，~~ CI导出（JSON/SARIF）~~
[]v0.3--~~语义相似度（局部嵌入）~~，TUI仪表板， mcpdiff 基线格式互操作
[]v0.4——多服务器组合，策略即代码（TOML配置），Homebrew tap

从源头构建

git clone https://github.com/meghsatpat/mcpx.git
cd mcpx
cargo build --release
# Binary at target/release/mcpx

# With semantic similarity (Level 3):
cargo build --release --features ml

CI和发布工作流

此存储库包括标准的GitHub Actions工作流：

CI (.github/workflows/ci.yml)
- cargo fmt --check
- cargo clippy -- -D warnings
- cargo test --workspace
- cargo check --workspace --all-targets
- 跨平台发布基于Ubuntu/macOS/Windows
Security Audit (.github/workflows/security-audit.yml)
- 跑 cargo audit 论依赖关系变化与周计划
Dependency Review (.github/workflows/dependency-review.yml)
- 检查pull请求中新的/更改的依赖关系
Release (.github/workflows/release.yml)
- 标签推送(v*)，构建 mcpx 二进制文件并将其附加到GitHub版本

许可证

麻省理工学院

使用说明

mcpx

问题

mcpx做什么

快速开始

CLI命令

检测到什么

中毒检测

自动摆振（安全模式）

CI导出（JSON/SARIF）

建筑

扩展mcpx

路线图

从源头构建

CI和发布工作流

许可证

相关 MCP

AI代理云连接工具

MCP安全代理工具

私有VNet日志查询代理

MCP服务器安全审计工具

旅游预订管理服务

凭证注入代理