ffalcinelli/mcp-passport
GitHub: ffalcinelli/mcp-passport
一个基于 FAPI 2.0 与 DPoP 的 MCP 安全桥，保护远程服务器并简化 AI 客户端的透明认证。
Stars: 0 | Forks: 0
# mcp-passport 🛡️
**Secure 1:1 transparent Layer 7 proxy for the Model Context Protocol (MCP)**
`mcp-passport` is a high-performance, secure bridge designed to protect remote MCP servers using industry-standard **FAPI 2.0** (Financial-grade API) security. It acts as a local `stdio` server for AI clients (like Claude Desktop or Gemini CLI) and proxies requests to a remote MCP server over HTTPS, handling complex authentication and discovery flows transparently.
## ✨ Key Features
- **MCP Compliance (Spec 2025-11-25)**: Full implementation of the MCP Authorization specification, including dynamic discovery and resource signaling.
- **Dynamic Discovery**: Automatically locates the authorization server via `WWW-Authenticate` headers in 401 challenges or the `/.well-known/oauth-protected-resource` fallback.
- **FAPI 2.0 Security**: Financial-grade security patterns including **Pushed Authorization Requests (PAR)** and **PKCE**.
- **DPoP (Demonstrating Proof-of-Possession)**: Cryptographically binds access tokens to ephemeral ES256 keys, preventing token replay attacks.
- **"Airlock" Mechanism**: Automatically suspends JSON-RPC requests to trigger OIDC flows, supporting 401 expiration and **403 Step-up** (insufficient scope) challenges.
- **RFC 8707 Resource Indicators**: Explicitly identifies target MCP servers in OIDC requests to prevent token misuse across different resources.
- **Secure OS Vault Integration**: Leverages the system's native secure storage (macOS Keychain, Windows Credential Manager, Linux Secret Service) via `keyring`.
- **SSE Support**: Handles persistent Server-Sent Events (SSE) from the remote server, piping them back to the AI client.
## 🏗️ Architecture: The Bridge
```
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)
```
## 🚀 Getting Started
### 安装
Build the binary from source:
```
cargo build --release
```
The compiled binary will be located at `target/release/mcp-passport`.
## ⚙️ 配置
`mcp-passport` can be configured via CLI flags or environment variables.
| Option | CLI Flag | Environment Variable | Default |
|--------|----------|----------------------|---------|
| Remote MCP URL | `--remote-mcp-url` | `MCP_PASSPORT_REMOTE_MCP_URL` | **Required** |
| Remote SSE URL | `--remote-sse-url` | `MCP_PASSPORT_REMOTE_SSE_URL` | **Required** |
| 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` | Optional (Lazy) |
| 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` |
## 🛠️ 开发与测试
### 运行测试
The project includes a comprehensive test suite, including headless browser automation for full E2E compliance verification.
```
# 运行标准测试
cargo test
# 运行无头浏览器 E2E 合规测试
# （需要 Docker 用于 Selenium/Chrome）
cargo test --test headless_compliance_test -- --nocapture
```
### 无头浏览器测试
The `headless_compliance_test` uses **Fantoccini** and **Selenium Standalone Chrome** (via Testcontainers) to automate the full OIDC flow:
1. Triggers 401 discovery.
2. Automates a browser session to perform the PAR-based login.
3. Verifies the final authorized MCP request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
标签：401, 403, AI客户端, CI, Claude Desktop, DPoP, FAPI 2.0, Gemini CLI, HTTPS, JSON 请求, JWT, Keyring, MCP, OAuth 2.0, OIDC, PAR, PKCE, RFC 8707, Rust, SEO: AI安全通信, SEO: FAPI 2.0桥接, SEO: MCP安全代理, Server-Sent Events, SSE, stdio, Step-up认证, Streamlit, 令牌绑定, 动态发现, 单点登录, 可视化界面, 多平台支持, 安全代理, 安全存储, 安全桥, 密钥串, 开源框架, 持续集成, 授权服务器, 操作系统检测, 本地代理, 桥接, 模型上下文协议, 系统钥匙串, 网络安全, 网络流量审计, 访问控制, 证明持有, 请求响应过滤, 资源指示符, 远程服务器, 透明代理, 通知系统, 金融级API, 防重放, 隐私保护