ffalcinelli/mcp-passport
GitHub: ffalcinelli/mcp-passport
一个基于 FAPI 2.0 与 DPoP 的 MCP 安全桥，保护远程服务器并简化 AI 客户端的透明认证。
Stars: 1 | Forks: 0
# mcp-passport 🛡️
[](https://codecov.io/gh/ffalcinelli/mcp-passport)
**用于 Model Context Protocol (MCP) 的安全 1:1 透明 Layer 7 代理**
`mcp-passport` 是一个高性能、安全的桥接器，旨在使用行业标准的 **FAPI 2.0** (Financial-grade API) 安全机制来保护远程 MCP 服务器。它作为 AI 客户端（如 Claude Desktop 或 Gemini CLI）的本地 `stdio` 服务器，并通过 HTTPS 将请求代理到远程 MCP 服务器，透明地处理复杂的身份验证和发现流程。
## ✨ 主要特性
- **MCP 合规性 (Spec 2025-11-25)**：完全实现了 MCP Authorization 规范，包括动态发现和资源信令。
- **动态发现**：通过 401 质询中的 `WWW-Authenticate` 头或 `/.well-known/oauth-protected-resource` 回退机制自动定位授权服务器。
- **FAPI 2.0 安全**：金融级安全模式，包括 **Pushed Authorization Requests (PAR)** 和 **PKCE**。
- **DPoP (Demonstrating Proof-of-Possession)**：以加密方式将 access token 绑定到临时的 ES256 密钥上，防止 token 重放攻击。
- **“气锁”机制**：自动挂起 JSON-RPC 请求以触发 OIDC 流程，支持 401 过期和 **403 Step-up**（scope 不足）质询。
- **RFC 8707 Resource Indicators**：在 OIDC 请求中显式标识目标 MCP 服务器，以防止 token 在不同资源间被滥用。
- **安全的 OS Vault 集成**：通过 `keyring` 利用系统原生的安全存储（macOS Keychain、Windows Credential Manager、Linux Secret Service）。
- **SSE 支持**：处理来自远程服务器的持久 Server-Sent Events (SSE)，并将其管道传输回 AI 客户端。
## 🏗️ 架构：桥接器
```
sequenceDiagram
participant C as AI Client (Claude)
participant P as mcp-passport (Airlock)
participant V as OS Vault (Keychain)
participant S as Remote MCP Server
participant O as OIDC Provider
C->>P: JSON-RPC Request (stdio)
alt No Discovery Info
P->>S: Unauthenticated Request
S-->>P: 401 Unauthorized + discovery info
end
P->>V: Check for DPoP Key & Token
alt Unauthenticated / Expired / 403 Step-up
P->>P: Activate Airlock (Suspend Requests)
P->>O: PAR Request (PKCE + DPoP + Resource)
O-->>P: request_uri
P->>C: Log Auth URL (stderr)
Note over C,P: User completes Auth in Browser
O->>P: Authorization Code (Loopback Callback)
P->>O: Token Exchange (DPoP Proof + Resource)
O-->>P: DPoP-bound Access Token
P->>V: Store Key & Token
P->>P: Deactivate Airlock (Resume Requests)
end
P->>S: signed JSON-RPC (DPoP + Token)
S-->>P: JSON-RPC Response
P->>C: Response (stdio)
```
## 🚀 快速开始
### 安装
从源码构建二进制文件：
```
cargo build --release
```
编译后的二进制文件位于 `target/release/mcp-passport`。
### Claude Desktop 集成
要将 `mcp-passport` 与 Claude Desktop 结合使用，请将其添加到您的 `claude_desktop_config.json` 中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```
{
"mcpServers": {
"my-secure-server": {
"command": "/path/to/mcp-passport",
"args": [
"--remote-mcp-url", "https://your-mcp-server.com/rpc",
"--remote-sse-url", "https://your-mcp-server.com/sse",
"--oidc-client-id", "your-client-id"
],
"env": {
"RUST_LOG": "info"
}
}
}
}
```
当 Claude 启动服务器时，`mcp-passport` 将向 `stderr` 输出一个身份验证 URL。您需要在浏览器中打开此 URL 以完成 OIDC 登录。通过身份验证后，token 将安全地存储在您的 OS keychain 中，并在未来的会话中自动使用。
## ⚙️ 配置
`mcp-passport` 可以通过 CLI 标志或环境变量进行配置。
| 选项 | CLI 标志 | 环境变量 | 默认值 |
|--------|----------|----------------------|---------|
| Remote MCP URL | `--remote-mcp-url` | `MCP_PASSPORT_REMOTE_MCP_URL` | **必填** |
| Remote SSE URL | `--remote-sse-url` | `MCP_PASSPORT_REMOTE_SSE_URL` | **必填** |
| Auth Scheme | `--auth-scheme` | `MCP_PASSPORT_AUTH_SCHEME` | `bearer` |
| Protocol Version | `--mcp-protocol-version` | `MCP_PASSPORT_MCP_PROTOCOL_VERSION` | `2025-11-25` |
| Discovery URL | `--oidc-discovery-url` | `MCP_PASSPORT_OIDC_DISCOVERY_URL` | 可选（懒加载） |
| Client ID | `--oidc-client-id` | `MCP_PASSPORT_OIDC_CLIENT_ID` | `mcp-passport` |
| Redirect URL | `--oidc-redirect-url`| `MCP_PASSPORT_OIDC_REDIRECT_URL` | `http://127.0.0.1:8082/callback` |
| User ID | `--user-id` | `MCP_PASSPORT_USER_ID` | `default_user` |
## 🛡️ 安全注意事项
### 本地机器信任
代理通过本地 `stdio` 与 AI 客户端通信。该安全模型假设本地机器是安全的。如果用户的机器遭到破坏，本地恶意软件只需劫持 `stdio` 管道或在解锁状态下查询 OS Vault，即可绕过网络身份验证。
## 🛠️ 开发与测试
### 运行测试
该项目包含全面的测试套件，包括用于完整 E2E 合规性验证的无头浏览器自动化。
```
# 运行 standard tests
cargo test
# 运行 headless browser E2E compliance test
# （需要 Docker 用于 Selenium/Chrome）
cargo test --test headless_compliance_test -- --nocapture
```
### 无头浏览器测试
`headless_compliance_test` 使用 **Fantoccini** 和 **Selenium Standalone Chrome**（通过 Testcontainers）来实现完整 OIDC 流程的自动化：
1. 触发 401 发现。
2. 自动化浏览器会话以执行基于 PAR 的登录。
3. 验证最终授权的 MCP 请求。
## 📄 许可证
该项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
标签：API网关, MCP协议, Rust, 人工智能, 安全合规, 用户模式Hook绕过, 网络代理, 网络流量审计, 身份认证, 通知系统