使用说明

                         __  __  ____ ____  __  __
                        |  \/  |/ ___|  _ \ \ \/ /
                        | |\/| | |   | |_) | \  /
                        | |  | | |___|  __/  /  \
                        |_|  |_|\____|_|    /_/\_\

          Secure gateway for MCP servers — from CLI to production.

文档 | 示例 | 安装 | GitHub

mcpx 是AI代理和主控程序服务器。它将任何MCP服务器封装到具有安全策略、审计日志和作用域守护进程隔离的CLI命令中，这样团队就可以放心地在生产中采用MCP。

# Discover → Call → Compose
mcpx serena find_symbol --name "Auth"
mcpx serena search_for_pattern --substring_pattern "TODO" | jq -r '.file'
mcpx postgres query --sql "SELECT * FROM users LIMIT 10"

为什么选择mcpx

MCP服务器在生产中有三个问题：

1.背景成本

在任何工作开始之前，加载MCP服务器本机每次会话需要花费50-100K令牌。mcpx通过Bash按需调用工具。零前期成本。

设置	上下文成本	影响
5台MCP服务器（本机）	~80000个令牌	上下文几乎已满
任何计数（mcpx）	0个令牌	完整上下文可用

2.无安全保障

每次MCP工具调用都不受限制。连接到Postgres MCP的AI代理可以 DROP TABLE 轻而易举地 SELECT。没有授权，没有政策执行，没有审计跟踪。

mcpx添加了缺失的安全层：

# Block SQL mutations on your database MCP
security:
  policies:
    - name: no-mutations
      match:
        tools: [query]
        content:
          target: args.sql
          deny_pattern: "(?i)\\b(INSERT|UPDATE|DELETE|DROP|TRUNCATE)\\b"
      action: deny
      message: "Mutation queries blocked"

$ mcpx postgres query --sql "DROP TABLE users"
error: server "postgres": policy "no-mutations" denied tool "query"
  Reason: Mutation queries blocked

3.多服务器管理

每台服务器都需要自己的安全配置文件。代码搜索MCP需要与数据库MCP或消息传递MCP不同的规则。当两个开发人员同时处理不同的项目时，他们的守护进程不应该干扰。

mcpx通过每服务器安全性和作用域守护进程来处理此问题：

servers:
  serena:
    security:
      mode: editing
      policies:
        - name: source-only
          match:
            args:
              relative_path: { allow_prefix: ["src/", "internal/"] }
          action: deny
  postgres:
    security:
      mode: read-only

安装

# Homebrew (macOS / Linux)
brew tap codestz/tap
brew install mcpx

# Go install (requires Go 1.24+)
go install github.com/codestz/mcpx/cmd/mcpx@latest

# Or build from source
git clone https://github.com/codestz/mcpx.git
cd mcpx && make build

快速开始

1.导入现有配置

mcpx init
# Detected .mcp.json — imported 3 servers: serena, sequential-thinking, filesystem

2.或手动配置

# .mcpx/config.yml
servers:
  serena:
    command: serena
    args: [start-mcp-server, --context=claude-code]
    daemon: true
    startup_timeout: 30s

3.使用它

mcpx serena find_symbol --name "Auth"         # call a tool
mcpx ping serena                               # health check
mcpx list serena -v                            # list all tools with flags

安全

mcpx在AI代理和MCP服务器之间提供了三层安全：

政策

定义在每次工具调用之前进行评估的规则。支持工具名称globs、参数检查和内容正则表达式：

security:
  enabled: true
  global:
    policies:
      - name: no-path-traversal
        match:
          args:
            "*path*": { deny_pattern: "\\.\\.\\/"}
        action: deny
        message: "Path traversal blocked"

servers:
  serena:
    security:
      mode: editing
      policies:
        - name: restrict-paths
          match:
            args:
              relative_path: { allow_prefix: ["src/", "internal/"] }
          action: deny

模式

快速安全配置文件： read-only （阻止所有写入工具）， editing （完全访问）， custom （仅限政策）。

servers:
  ml-pipeline:
    security:
      mode: read-only   # prevents accidental changes to ML models

审计日志

每个工具调用都会记录到一个JSONL文件中，其中包含时间戳、参数和策略决策：

security:
  global:
    audit:
      enabled: true
      log: "$(mcpx.project_root)/.mcpx/audit.jsonl"
      redact: ["$(secret.*)"]

{"timestamp":"2026-03-28T18:19:50Z","server":"serena","tool":"find_symbol","action":"allowed"}
{"timestamp":"2026-03-28T18:19:59Z","server":"serena","tool":"find_symbol","action":"denied","policy_name":"no-path-traversal"}

看安全文档以获取完整参考。

配置

两级配置

文件	作用域	提交？
`~/.mcpx/config.yml`	全局（用户级别）	否
`.mcpx/config.yml`	项目级别	是

项目配置在冲突中获胜。

动态变量

args:
  - "$(mcpx.project_root)"    # directory containing .mcpx/config.yml
  - "$(git.root)"              # git repository root
  - "$(env.API_KEY)"           # environment variable
  - "$(secret.github_token)"   # OS keychain secret
  - "$(sys.os)"                # linux, darwin, windows

服务器选项

servers:
  my-server:
    command: string          # executable to run (required)
    args: [string]           # command arguments
    transport: stdio|http|sse # protocol (default: stdio)
    daemon: bool             # keep server alive between calls
    startup_timeout: string  # e.g. "60s" (default: "30s")
    url: string              # for http/sse transports
    headers: {}              # HTTP headers
    auth:                    # authentication
      type: bearer
      token: "$(secret.token)"
    env: {}                  # extra environment variables
    security: {}             # per-server security config

AI代理如何使用mcpx

将此添加到您的项目 CLAUDE.md （或同等）：

## Tools

This project uses mcpx for MCP tool access:
- `mcpx list` — discover servers and tools
- `mcpx <server> <tool> --help` — get usage for any tool
- Call tools via Bash as needed

人工智能懒洋洋地发现工具，按需调用它们，并通过管道组合它们。

秘密

mcpx secret set github_token ghp_abc123    # store in OS keychain
mcpx secret list                            # list secrets
mcpx secret remove github_token             # remove

配置中的参考 $(secret.<name>) --在运行时解析，从不在磁盘上，从不记录。

守护程序模式

重型服务器（如带有LSP的Serena）受益于生存：

servers:
  serena:
    daemon: true

mcpx daemon status             # show running daemons
mcpx daemon stop serena        # stop a daemon
mcpx ping serena               # health check with latency

CLI 参考

mcpx <server> <tool> [flags]      Call a tool
mcpx <server> <tool> --help       Show tool help
mcpx <server> <tool> --stdin      Read args from stdin JSON
mcpx <server> <tool> --example    JSON skeleton for the tool's args
mcpx <server> <tool> --validate-args ...  Type-check args without invoking
mcpx <server> --help              List all tools (compact); --full for descriptions

mcpx <server> info                Server capabilities
mcpx <server> prompt list|<name>  Prompts
mcpx <server> resource list|read  Resources

mcpx find <query>                 Rank tools across servers by intent (BM25)
mcpx batch < calls.jsonl          Run many calls in parallel (NDJSON in/out)
mcpx gain                         Token-savings dashboard (TUI)
mcpx doctor                       Config + connectivity diagnostics
mcpx ui status|stop|open|disable  Web dashboard daemon controls

mcpx list                         List servers
mcpx list <server> -v             List tools with flags
mcpx ping <server>                Health check
mcpx init                         Import .mcp.json
mcpx configure                    Generate agent reference docs (MCPX.md + per-server)

mcpx secret set|list|remove       Keychain secrets
mcpx daemon status|stop|stop-all  Daemon management
mcpx version                      Print version
mcpx completion bash|zsh|fish     Shell completions

全球旗帜

标志	描述
`--json`	输出原始JSON
`--quiet`	抑制输出
`--dry-run`	显示将执行的操作
`--pick <path>`	提取JSON字段
`--timeout <dur>`	每次通话超时

退出代码

代码	含义
0	成功
1	工具错误
2	配置错误
3	连接错误
4	超时
5	政策被拒绝
6	找不到工具
2	配置错误
3	连接错误

建筑

cmd/mcpx/            entrypoint
internal/
  config/            YAML config loading, merging, validation
  security/          policy engine, audit logging
  resolver/          dynamic variable resolution: $(env.*), $(git.*), etc.
  mcp/               MCP protocol client (JSON-RPC 2.0 over stdio/http/sse)
  cli/               Cobra CLI, dynamic command generation from MCP schemas
  daemon/            daemon process management, unix socket transport
  secret/            OS keychain integration

单个二进制，零运行时依赖性，亚毫秒启动
三次运输：stdio、HTTP（可流式传输）、SSE
安全中间件：在每次工具调用之前评估策略
审计跟踪：每个呼叫都记录了秘密编辑
无外壳膨胀 — exec.Command，不 sh -c无注射表面。
磁盘上永远不会有秘密 --在运行时从密钥链解析
守护进程套接字 --unix套接字位于 /tmp/mcpx-<server>-<uid>.sock，模式0600

壳牌完井

echo 'eval "$(mcpx completion bash)"' >> ~/.bashrc   # Bash
echo 'eval "$(mcpx completion zsh)"' >> ~/.zshrc     # Zsh
mcpx completion fish | source                         # Fish

贡献

看贡献.md 作为指导方针。

许可证

麻省理工学院