使用说明

授权MCP代理（Rust）

高性能模型上下文协议（MCP）用Rust编写的代理服务器，执行OIDC身份验证，以获取受令牌验证保护的远程MCP服务器的访问令牌，并为Claude Desktop等MCP客户端将HTTP传输桥接到本地stdio。

Rust重写 的原件 Python授权mcp代理与：

🚀 快速启动：<1秒（Python为2-3秒）
📦 单个二进制：3.3 MB独立可执行文件（无运行时依赖关系）
💾 内存不足：约10-20MB的占用空间（Python为50-80MB）
🔒 类型安全：使用Rust的所有权系统保证编译时间
🌍 跨平台：Linux、macOS（英特尔和苹果硅）和Windows的原生二进制文件

这是干什么用的？

使用 authful-mcp-proxy-rs 当您需要将MCP客户端（如Claude Desktop、Cursor或Windsurf）连接到远程MCP服务器时，该服务器：

受OAuth/OIDC令牌验证保护
本身不处理身份验证（没有内置的OAuth流）
退货 401 Unauthorized 没有适当的访问令牌

代理处理完整的OIDC身份验证流程，将您的凭据安全地存储在 ~/.mcp/authful_mcp_proxy/tokens/，并根据需要自动刷新令牌。

技术背景

通常，使用OAuth或OpenID Connect（OIDC）保护MCP连接需要与外部身份提供者协调的“授权”MCP服务器。MCP客户端通过MCP服务器处理身份验证，MCP服务器又与OAuth或OIDC授权服务器交互。然而，这不适用于仅受令牌验证保护的MCP服务器，即信任来自已知发行者的令牌但不与OAuth/OIDC授权服务器本身协调的MCP服务器。在这种情况下，MCP客户端检测到MCP服务器没有授权，并完全跳过OAuth/OIDC身份验证，导致 401 Unauthorized 所有工具、资源和提示请求都有错误。

此MCP代理通过直接OIDC授权服务器交互独立处理身份验证来填补这一空白。它通过将用户的浏览器打开到OIDC授权端点进行登录和范围批准来执行OAuth授权代码流。临时本地HTTP服务器接收OAuth重定向，并使用PKCE交换访问和刷新令牌的授权码。访问令牌用作所有后端MCP服务器请求的承载令牌，并在本地缓存，以避免重复的浏览器交互。当令牌过期时，代理会使用刷新令牌自动获取新的令牌。

安装

下载预构建二进制文件

下载适用于您平台的最新版本：

Linux（x86_64）:

# Download and install to /usr/local/bin
curl -L https://github.com/yourusername/authful-mcp-proxy-rs/releases/latest/download/authful-mcp-proxy-rs-linux-x64.tar.gz | tar xz
sudo mv authful-mcp-proxy-rs /usr/local/bin/
chmod +x /usr/local/bin/authful-mcp-proxy-rs

macOS（英特尔）:

# Download and install
curl -L https://github.com/yourusername/authful-mcp-proxy-rs/releases/latest/download/authful-mcp-proxy-rs-macos-intel.tar.gz | tar xz
sudo mv authful-mcp-proxy-rs /usr/local/bin/
chmod +x /usr/local/bin/authful-mcp-proxy-rs

macOS（苹果硅-M1/M2/M3/M4）:

# Download and install
curl -L https://github.com/yourusername/authful-mcp-proxy-rs/releases/latest/download/authful-mcp-proxy-rs-macos-arm.tar.gz | tar xz
sudo mv authful-mcp-proxy-rs /usr/local/bin/
chmod +x /usr/local/bin/authful-mcp-proxy-rs

Windows（x64）:

# Download and extract to Program Files
Invoke-WebRequest -Uri "https://github.com/yourusername/authful-mcp-proxy-rs/releases/latest/download/authful-mcp-proxy-rs-windows-x64.zip" -OutFile "mcp-proxy.zip"
Expand-Archive mcp-proxy.zip -DestinationPath "$env:ProgramFiles\authful-mcp-proxy-rs"

# Add to PATH (optional - or use full path in Claude Desktop config)

从源代码构建

需要锈 1.70或更高版本：

# Clone the repository
git clone https://github.com/yourusername/authful-mcp-proxy-rs.git
cd authful-mcp-proxy-rs

# Build release binary
cargo build --release

# Install to /usr/local/bin (Linux/macOS)
sudo cp target/release/authful-mcp-proxy-rs /usr/local/bin/

# Or on Windows, copy to a directory in your PATH
# copy target\release\authful-mcp-proxy-rs.exe C:\Windows\System32\

用法

快速开始

与Claude Desktop等MCP客户端一起使用的最简单方法：

Linux/macOS:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "/usr/local/bin/authful-mcp-proxy-rs",
      "args": ["https://mcp-backend.company.com/mcp"],
      "env": {
        "OIDC_ISSUER_URL": "https://auth.company.com",
        "OIDC_CLIENT_ID": "your-client-id"
      }
    }
  }
}

视窗:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "C:\\Program Files\\authful-mcp-proxy-rs\\authful-mcp-proxy-rs.exe",
      "args": ["https://mcp-backend.company.com/mcp"],
      "env": {
        "OIDC_ISSUER_URL": "https://auth.company.com",
        "OIDC_CLIENT_ID": "your-client-id"
      }
    }
  }
}

ℹ️ 注：必须只指定两个基本的OIDC参数（颁发者URL和客户端ID）。其他OIDC参数使用合理的默认值（参见配置选项).

⚠️ 重要提示： 确保您的OIDC客户端配置了 http://localhost:8080/auth/callback 作为允许的重定向URI！

首次运行：代理将打开您的浏览器进行身份验证。登录并批准所需的作用域后，您的凭据将在本地缓存，在令牌过期之前，您不需要再次进行身份验证。

配置选项

所有选项都可以通过环境变量在 env block或作为CLI参数传递。

所需配置：

环境变量	CLI标志	描述	示例
`MCP_BACKEND_URL`	`<MCP_BACKEND_URL>`	远程MCP服务器URL（位置参数）	`https://mcp.example.com/mcp`
`OIDC_ISSUER_URL`	`--oidc-issuer-url`	您的OIDC提供商的发行商URL	`https://auth.example.com`
`OIDC_CLIENT_ID`	`--oidc-client-id`	来自OIDC提供商的OAuth客户端ID	`my-app-client-id`

可选配置：

环境变量	CLI标志	默认值	描述
`OIDC_CLIENT_SECRET`	`--oidc-client-secret`	（无）	客户端机密（公共客户端不需要）
`OIDC_SCOPES`	`--oidc-scopes`	`openid profile email`	空格分隔的OAuth作用域
`OIDC_REDIRECT_URL`	`--oidc-redirect-url`	`http://localhost:8080/auth/callback`	OAuth回调URL

高级选项：

CLI标志	说明
`--no-banner`	抑制启动横幅
`--silent`	仅显示错误消息
`--debug`	启用详细的调试日志记录

跑 authful-mcp-proxy-rs --help 获取完整的CLI文档。

使用示例

示例1：克劳德桌面（推荐）

添加到您的Claude Desktop配置（可通过设置访问→ 开发者→ 编辑配置）：

{
  "mcpServers": {
    "company-tools": {
      "command": "/usr/local/bin/authful-mcp-proxy-rs",
      "args": ["https://mcp-backend.company.com/mcp"],
      "env": {
        "OIDC_ISSUER_URL": "https://auth.company.com",
        "OIDC_CLIENT_ID": "claude-desktop-client",
        "OIDC_SCOPES": "openid profile mcp:read mcp:write"
      }
    }
  }
}

⚠️ 重要提示： 确保您的OIDC客户端配置了 http://localhost:8080/auth/callback 作为允许的重定向URI！

重新启动Claude Desktop以应用更改。

示例2：使用客户机密（机密客户）

对于需要保密的OIDC机密客户：

{
  "mcpServers": {
    "secure-server": {
      "command": "/usr/local/bin/authful-mcp-proxy-rs",
      "args": ["https://api.example.com/mcp"],
      "env": {
        "OIDC_ISSUER_URL": "https://login.example.com",
        "OIDC_CLIENT_ID": "your-confidential-client-id",
        "OIDC_CLIENT_SECRET": "your-client-secret",
        "OIDC_SCOPES": "openid profile email api:access"
      }
    }
  }
}

示例3：自定义重定向端口

如果端口8080已在使用中，请指定其他端口：

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/authful-mcp-proxy-rs",
      "args": ["https://mcp.example.com"],
      "env": {
        "OIDC_ISSUER_URL": "https://auth.example.com",
        "OIDC_CLIENT_ID": "my-client-id",
        "OIDC_REDIRECT_URL": "http://localhost:9090/auth/callback"
      }
    }
  }
}

⚠️ 重要提示： 更新您的OIDC客户端配置，以允许自定义重定向URL！

示例4：调试模式

启用详细日志以进行故障排除：

{
  "mcpServers": {
    "debug-server": {
      "command": "/usr/local/bin/authful-mcp-proxy-rs",
      "args": [
        "--debug",
        "https://mcp.example.com"
      ],
      "env": {
        "OIDC_ISSUER_URL": "https://auth.example.com",
        "OIDC_CLIENT_ID": "my-client-id"
      }
    }
  }
}

与其他MCP客户端一起使用

MCP检查员

创建 mcp.json 文件：

{
  "mcpServers": {
    "authful-mcp-proxy": {
      "command": "/usr/local/bin/authful-mcp-proxy-rs",
      "args": ["https://mcp.example.com/mcp"],
      "env": {
        "OIDC_ISSUER_URL": "https://auth.example.com",
        "OIDC_CLIENT_ID": "inspector-client"
      }
    }
  }
}

启动检查器：

npx @modelcontextprotocol/inspector --config mcp.json --server authful-mcp-proxy

光标/风帆

这些编辑器使用与Claude Desktop相同的配置格式。使用适当的二进制路径将服务器配置添加到MCP设置文件中。

命令行/直接使用

# Run directly
authful-mcp-proxy-rs \
  --oidc-issuer-url https://auth.example.com \
  --oidc-client-id my-client \
  https://mcp.example.com/mcp

# Or use environment variables
export OIDC_ISSUER_URL=https://auth.example.com
export OIDC_CLIENT_ID=my-client
authful-mcp-proxy-rs https://mcp.example.com/mcp

凭证管理

凭证存储在哪里？

凭据缓存在 ~/.mcp/authful_mcp_proxy/tokens/ （出于兼容性考虑，与Python版本位于同一位置），文件名基于OIDC颁发者URL：

~/.mcp/authful_mcp_proxy/tokens/
  └── auth.example.com_realms_myrealm_tokens.json

视窗: %USERPROFILE%\.mcp\authful_mcp_proxy\tokens\

清除缓存凭据

要强制重新身份验证（例如，切换帐户或清除过期的令牌）：

Linux/macOS:

rm -rf ~/.mcp/authful_mcp_proxy/tokens/

视窗:

rmdir /s %USERPROFILE%\.mcp\authful_mcp_proxy\tokens

下次连接时，系统将提示您再次进行身份验证。

故障排除

浏览器无法打开进行身份验证

问题： 代理启动，但没有打开浏览器窗口。

解决：

检查端口8080（或您的自定义重定向端口）是否未被阻止
手动打开代理日志中显示的URL
验证您的防火墙没有阻止本地主机连接

401未经授权的错误

问题： 后端MCP服务器返回401个错误。

解决：

验证 OIDC_ISSUER_URL 与您的提供商完全匹配
检查 OIDC_CLIENT_ID 是正确的
确保授权服务器授予请求的范围
清除缓存的凭据并重新进行身份验证： rm -rf ~/.mcp/authful_mcp_proxy/tokens/
启用调试模式以查看令牌详细信息： --debug

重定向URI不匹配

问题： OIDC提供程序显示“redirect_uri不匹配”错误。

解决：

添加 http://localhost:8080/auth/callback 到OIDC客户端允许的重定向URI
如果使用自定义端口，请更新两个代理配置(OIDC_REDIRECT_URL)OIDC客户端设置
确保重定向URI完全匹配（包括尾部斜线）

令牌刷新失败

问题： 代理最初可以工作，但一段时间后就会失败。

解决：

检查您的OIDC提供商是否颁发了刷新令牌（某些提供商不颁发某些授权类型的刷新令牌）
验证 offline_access 如果您的提供商要求，则请求范围
清除缓存凭据以获取新令牌： rm -rf ~/.mcp/authful_mcp_proxy/tokens/

与后端的连接失败

问题： 无法连接到远程MCP服务器。

解决：

验证后端URL是否正确且可访问
检查与后端服务器的网络连接
确保后端服务器正在运行并接受连接
尝试直接在浏览器中访问后端URL，以验证其是否可访问
检查可能阻止连接的代理/VPN问题

MCP客户端无法识别代理

问题： Claude Desktop或其他客户端显示服务器错误。

解决：

验证JSON语法是否正确（没有尾随逗号，引号正确）
检查二进制路径是否正确，文件是否可执行
完全重新启动MCP客户端（而不仅仅是刷新）
查看客户端日志中的特定错误消息

调试日志记录

启用调试模式以查看有关身份验证流的详细信息：

authful-mcp-proxy-rs --debug https://mcp.example.com/mcp

或者通过环境变量：

{
  "env": {
    "MCP_PROXY_DEBUG": "1",
    // ... other config
  }
}

还有问题吗？

与一起跑步 --debug 获取详细日志
验证您的OIDC提供商配置
在GitHub上打开一个带有调试日志的问题（编辑敏感信息）

从Python版本迁移

Rust版本与Python版本完全兼容：

✅ 令牌存储：使用相同的文件格式和位置(~/.mcp/authful_mcp_proxy/tokens/) ✅ CLI参数：相同的参数名称和行为 ✅ 环境变量：相同的变量名（OIDC_，MCP_) ✅ OIDC流量：相同的OAuth 2.0授权码+PKCE流 ✅ 客户端配置：Claude Desktop配置中的插入式替换

迁移步骤：

安装Rust二进制文件（参见安装)
更新您的Claude Desktop配置以使用二进制路径，而不是 uvx authful-mcp-proxy
重新启动Claude Desktop-您现有的缓存令牌将自动工作！

性能改进：

🚀 更快的启动：<1秒vs 2-3秒
💾 低位存储器：约10-20 MB vs 50-80 MB
📦 占地面积更小：3.3 MB二进制文件与50+MB Python+依赖项

贡献

欢迎投稿！这是一个Rust重写，与原始Python版本具有相同的功能。

发展：

# Clone and build
git clone https://github.com/yourusername/authful-mcp-proxy-rs.git
cd authful-mcp-proxy-rs
cargo build

# Run tests
cargo test

# Run with example backend
cargo run -- \
  --oidc-issuer-url https://auth.example.com \
  --oidc-client-id test-client \
  https://mcp.example.com/mcp

项目结构：

src/config.rs -CLI和配置解析
src/oidc/ -OIDC客户端实现（发现、PKC、令牌、回调）
src/middleware.rs -用于令牌注入和401重试的HTTP中间件
src/proxy/ -MCP代理服务器（stdio↔ HTTP网桥）
tests/ -集成和单元测试

跨平台测试： 该项目旨在为Linux、macOS和Windows提供一流的支持。请在提交PR之前在所有平台上测试更改。

许可证

根据Apache许可证2.0版授权。看许可证了解详情。

这是对原始版本的Rust重写 Python授权mcp代理.

使用说明

授权MCP代理（Rust）

目录

这是干什么用的？

技术背景

安装

下载预构建二进制文件

从源代码构建

用法

快速开始

配置选项

使用示例

示例1：克劳德桌面（推荐）

示例2：使用客户机密（机密客户）

示例3：自定义重定向端口

示例4：调试模式

与其他MCP客户端一起使用

MCP检查员

光标/风帆

命令行/直接使用

凭证管理

凭证存储在哪里？

清除缓存凭据

故障排除

浏览器无法打开进行身份验证

401未经授权的错误

重定向URI不匹配

令牌刷新失败

与后端的连接失败

MCP客户端无法识别代理

调试日志记录

还有问题吗？

从Python版本迁移

贡献

许可证

相关 MCP

网页内容抓取工具

MCP聚合中间件

飞书MCP代理服务

Expo文档MCP服务器

图像生成服务器

Java企业应用开发框架