如何通过 MCP 把 MAREF 接入你的 Agent —— 分步教程

作者 MAREF Engineering

MCP 教程 Model Context Protocol 集成 智能体治理

Model Context Protocol（MCP）已成为智能体与工具通信的事实接口。Claude Code、Cursor、Windsurf 都在说这门语言。问题从来不是你的 Agent 会不会用 MCP——而是它调用的工具有没有人盯着。MAREF 在对话的两端都说 MCP，让治理成为一个层，而不是事后加上的补丁。

本教程基于 MAREF 真实 API 编写（maref.integration.mcp_client 与 maref.integration.mcp_bridge）。以下全部代码在标准的 pip install maref 环境即可运行。

两个角色，一个协议

MAREF 在 MCP 上有两个方向的工作方式，搞清楚你要哪个，整个配置就完成了一半：

  • MAREF 作为 MCP client——MAREF 主动连接外部 MCP server（file、shell、browser、email 或第三方工具服务器），列出它们的工具，并在每一次调用真正发出之前，让工具通过它的安全门（security gate）。
  • MAREF 作为 MCP server——Claude Code / Cursor / Windsurf 把 MAREF 当作一个工具服务器来连接。Agent 想调用的每一个工具，都会变成 MAREF 注册表里受治理的工具。

大多数团队从第一种开始，再进阶到第二种。下面两种都会讲到。

1. MAREF 作为 MCP client —— 治理外部工具

入口是 MCPClient。你用 MCPServerConfig 注册一个外部服务器，MAREF 帮你管理连接生命周期——初始化、能力协商、重连：

连接外部 MCP server 
from maref.integration.mcp_client import MCPClient, MCPServerConfig

client = MCPClient()

config = MCPServerConfig(
    command=["npx", "-y", "@some/tool-server"],
    transport_type="stdio",          # 或 "sse"，配合 url=
    server_name="my-tool-server",
    env={"TOOL_API_KEY": "..."},
)

conn = client.register_server(config)   # 返回 MCPConnection
tools = client.list_tools(conn)         # list[MCPToolDef]

现在到了关键点。裸的 MCPClient.call_tool 会跳过治理。安全路径是 MCPBridge——它把每一次调用都包进安全门：

每一次工具调用都经过安全门 
from maref.integration.mcp_bridge import MCPBridge

bridge = MCPBridge(client)               # 可选：传入你自己的 MCPSecurityGate

# 监听治理事件
bridge.on("maref.mcp.invoke", lambda e: print("governed:", e.data))

bridge.discover_tools(conn)              # 给每个工具做一次安全检查

result = bridge.invoke_tool(
    conn,
    tool_name="create_file",
    args={"path": "/tmp/demo.txt", "content": "hello"},
)
# 如果安全门返回 DENY，invoke_tool 会返回
# {"error": "Tool blocked by security gate", "tool": ...} ——
# 外部服务器甚至不会被触达。

这一行——bridge.invoke_tool——就是"能调用任何工具的 Agent"与"只能调用策略允许的工具的 Agent"之间的分水岭。每一次调用都会发出 maref.mcp.invoke 事件，你可以把它接到审计日志、SIEM 或仪表盘。

2. MAREF 作为 MCP server —— 治理 Claude Code / Cursor

如果你的 Agent 宿主已经会说 MCP，把 MAREF 自己的工具注册表暴露成一个 MCP server 即可。MCPServerAdapter 把 MAREF 的 ToolRegistry 桥接到 MCP 线上协议——list_tools 和 handle_tool_call 就是协议需要的两个方法：

把 MAREF 注册表暴露为 MCP server 
from maref.mcp.router import MCPServerAdapter
from maref.tools import ToolRegistry

registry = ToolRegistry()                # 你的受治理工具都在这里
adapter = MCPServerAdapter(registry)

# MCP JSON-RPC 请求进来，受治理的响应出去
adapter.handle_tool_call("send_email", {"to": "[email protected]"})

实践中你通常会把它挂到完整的 MCPServer 实现（maref.integration.mcp_server）后面，那会在工具之上再给你 resources、prompts 和 sampling 回调。MAREF 没有内置 maref mcp serve 这样的 CLI 命令——stdio 入口是一个约 15 行的启动脚本，直接接在真实的 MCPServer API 上：

mcp_stdio.py —— MAREF stdio 启动器 
import json, sys
from maref.integration.mcp_transport import JSONRPCRequest
from maref.integration.mcp_server import MCPServer

server = MCPServer(name="maref-mcp-server", security_gate=gate)  # gate: 你的安全门
# ... server.register_tool(...) 注册受治理工具 ...

for line in sys.stdin:                     # newline-delimited JSON-RPC 2.0
    msg = json.loads(line)
    req = JSONRPCRequest(method=msg["method"], params=msg.get("params"), id=msg.get("id", 0))
    resp = server.handle_request(req)
    sys.stdout.write(json.dumps({"jsonrpc": resp.jsonrpc, "result": resp.result, "error": resp.error, "id": resp.id}, ensure_ascii=False) + "
")
    sys.stdout.flush()
Claude Code 配置 —— 指向启动器 
{
  "mcpServers": {
    "maref": {
      "command": "python3",
      "args": ["/path/to/mcp_stdio.py"]
    }
  }
}

从那一刻起，当 Claude Code 或 Cursor 调用任何工具，调用都会先经过 MAREF 的治理状态机——策略决策树、安全门、审计追踪——然后才触达外部世界。

3. 治理真正拦截什么

治理不是建议，而是决策。决策树按四层做出——Rule → Mode → SafetyGate → User：

  • 硬规则（绝不碰 /etc）立刻拦截，不咨询模型。
  • 当前模式（只读 / 分诊 / 全权）收窄允许范围。
  • 安全门捕获高风险操作——高爆炸半径、不可信目标、异常模式。
  • 人工升级用于真正危险的情况，有具名审批人、有审计记录。

又因为每一个决策都按 Agent 签名（Ed25519）并写入审计日志，"这是哪个 Agent 干的？"永远不会成为争论。

现在就试

看到这个闭环运转起来最快的方式是本地 demo——它会启动一个受治理的玩具 Agent 和一个实时仪表盘，让你看着 BLOCK/ALLOW 决策一条条流出来：

本地受治理 demo 
pip install maref
maref demo --port 8080
# 打开 http://localhost:8080 —— 仪表盘实时展示 8 层防御
# 流水线、信任分和审计日志。

🛡️ 来源：MAREF 源码 —— src/maref/integration/mcp_client.py（MCPClient、MCPServerConfig、register_server）、src/maref/integration/mcp_bridge.py（MCPBridge.discover_tools / invoke_tool）、src/maref/integration/mcp_server.py（MCPServer）、src/maref/mcp/router.py（MCPServerAdapter）。查看全部集成方式。