Authful MCP Proxy Rs

授权MCP代理（Rust）

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

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

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

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

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

配置选项

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

所需配置：

可选配置：

高级选项：

跑 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

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

故障排除

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

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

解决：

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

401未经授权的错误

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

解决：

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

重定向URI不匹配

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

解决：

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

令牌刷新失败

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

解决：

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

与后端的连接失败

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

解决：

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

MCP客户端无法识别代理

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

解决：

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

调试日志记录

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

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

或者通过环境变量：

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

还有问题吗？

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

从Python版本迁移

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

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

迁移步骤：

1. 安装Rust二进制文件（参见 安装)
2. 更新您的Claude Desktop配置以使用二进制路径，而不是 uvx authful-mcp-proxy
3. 重新启动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代理.