OAuth-MCP-代理服务器

Name: OAuth-MCP-代理服务器
Author: tuannvm

作者：tuannvm10 星标更新：2025-11-04

安装使用来源：spider==github.com

项目介绍

OAuth MCP 代理

用于 Go MCP 服务器的 OAuth 2.1 身份验证库。

支持两种 MCP SDK：

✅ mark3labs/mcp-go
✅ modelcontextprotocol/go-sdk（官方）

一次性设置： 配置提供者并添加 WithOAuth() 到您的服务器。 结果： 所有工具自动受到令牌验证和缓存的保护。

mark3labs/mcp-go

import "github.com/tuannvm/oauth-mcp-proxy/mark3labs"

oauthServer, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{
    Provider: "okta",
    Issuer:   "https://your-company.okta.com",
    Audience: "api://your-mcp-server",
})

mcpServer := server.NewMCPServer("Server", "1.0.0", oauthOption)
streamable := server.NewStreamableHTTPServer(mcpServer, /*options*/)
mux.HandleFunc("/mcp", oauthServer.WrapMCPEndpoint(streamable))

官方 SDK

import mcpoauth "github.com/tuannvm/oauth-mcp-proxy/mcp"

mcpServer := mcp.NewServer(&mcp.Implementation{...}, nil)
_, handler, _ := mcpoauth.WithOAuth(mux, cfg, mcpServer)
http.ListenAndServe(":8080", handler)

为什么使用这个库？

双 SDK 支持 - 适用于 mark3labs 和官方 SDK
简单集成 - 一个 WithOAuth() 调用保护所有工具
自动 401 处理 - 符合 RFC 6750 的错误响应与 OAuth 发现
零工具配置 - 所有工具自动受到保护
快速令牌缓存 - 5 分钟缓存，小于 5 毫秒验证
生产就绪 - 安全加固，经过实战测试
多个提供者 - HMAC，Okta，Google，Azure AD

它是如何工作的？

请求流程

sequenceDiagram
    participant 客户端
    participant MCP 服务器
    box lightyellow oauth-mcp-proxy 库
    participant 中间件
    participant 缓存
    participant 提供者
    end
    participant 您的工具处理器

    客户端->>MCP 服务器: 请求 + Bearer 令牌
    MCP 服务器->>中间件: WithOAuth() 截获

    alt 令牌在缓存中且新鲜
        中间件->>缓存: 检查令牌哈希
        缓存-->>中间件: 返回缓存用户
    else 令牌未缓存或已过期
        中间件->>提供者: 验证令牌 (HMAC/OIDC)
        提供者-->>中间件: 用户声明
        中间件->>缓存: 存储用户 5 分钟
    end

    中间件->>您的工具处理器: 传递带有上下文用户的请求
    您的工具处理器->>您的工具处理器: GetUserFromContext(ctx)
    您的工具处理器-->>客户端: 发送响应

令牌验证流程

flowchart TB
    Start([您的 MCP 服务器接收请求]) --> Extract[oauth-mcp-proxy: 提取令牌]
    Extract --> Hash[oauth-mcp-proxy: SHA-256 哈希]
    Hash --> CheckCache{oauth-mcp-proxy: 令牌缓存？}

    CheckCache -->|命中缓存| GetUser[oauth-mcp-proxy: 获取缓存用户]
    CheckCache -->|未命中缓存| Validate{oauth-mcp-proxy: 验证}

    Validate -->|有效| Claims[oauth-mcp-proxy: 提取声明]
    Validate -->|无效| Reject([返回 401])

    Claims --> Store[oauth-mcp-proxy: 缓存]
    Store --> GetUser

    GetUser --> Context[oauth-mcp-proxy: 将用户添加到上下文中]
    Context --> Tool[您的工具处理器: GetUserFromContext]
    Tool --> Response([您的 MCP 服务器: 返回响应])

    style Start fill:#e8f5e9
    style Extract fill:#fff9c4
    style Hash fill:#fff9c4
    style CheckCache fill:#fff9c4
    style Validate fill:#fff9c4
    style Claims fill:#fff9c4
    style Store fill:#fff9c4
    style GetUser fill:#fff9c4
    style Context fill:#fff9c4
    style Tool fill:#e8f5e9
    style Response fill:#e8f5e9
    style Reject fill:#ffebee

oauth-mcp-proxy 做了什么：

从 HTTP 请求中提取 Bearer 令牌
验证您的 OAuth 提供者（带缓存）
将认证用户添加到请求上下文中
所有您的工具自动受到保护

快速开始

使用 mark3labs/mcp-go

1. 安装

go get github.com/tuannvm/oauth-mcp-proxy

2. 添加到您的服务器

import (
    oauth "github.com/tuannvm/oauth-mcp-proxy"
    "github.com/tuannvm/oauth-mcp-proxy/mark3labs"
)

mux := http.NewServeMux()

// 启用 OAuth（一次设置）
oauthServer, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{
    Provider: "okta",                    // 或 "hmac", "google", "azure"
    Issuer:   "https://your-company.okta.com",
    Audience: "api://your-mcp-server",
    ServerURL: "https://your-server.com",
})

// 创建带有 OAuth 的 MCP 服务器
mcpServer := mcpserver.NewMCPServer("Server", "1.0.0", oauthOption)

// 添加工具 - 所有工具自动受到保护
mcpServer.AddTool(myTool, myHandler)

// 设置具有自动 401 处理的端点
streamable := mcpserver.NewStreamableHTTPServer(
    mcpServer,
    mcpserver.WithHTTPContextFunc(oauth.CreateHTTPContextFunc()),
)
mux.HandleFunc("/mcp", oauthServer.WrapMCPEndpoint(streamable))

3. 访问认证用户

func myHandler(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    user, ok := oauth.GetUserFromContext(ctx)
    if !ok {
        return nil, fmt.Errorf("需要身份验证")
    }
    // 使用 user.Username, user.Email, user.Subject
}

使用官方 SDK

1. 安装

go get github.com/modelcontextprotocol/go-sdk
go get github.com/tuannvm/oauth-mcp-proxy

2. 添加到您的服务器

import (
    "github.com/modelcontextprotocol/go-sdk/mcp"
    oauth "github.com/tuannvm/oauth-mcp-proxy"
    mcpoauth "github.com/tuannvm/oauth-mcp-proxy/mcp"
)

mux := http.NewServeMux()

// 创建 MCP 服务器
mcpServer := mcp.NewServer(&mcp.Implementation{
    Name:    "my-server",
    Version: "1.0.0",
}, nil)

// 添加工具
mcp.AddTool(mcpServer, &mcp.Tool{
    Name: "greet",
    Description: "问候用户",
}, func(ctx context.Context, req *mcp.CallToolRequest, params *struct{}) (*mcp.CallToolResult, any, error) {
    user, _ := oauth.GetUserFromContext(ctx)
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: "你好，" + user.Username},
        },
    }, nil, nil
})

// 添加 OAuth 保护
_, handler, _ := mcpoauth.WithOAuth(mux, &oauth.Config{
    Provider: "okta",
    Issuer:   "https://your-company.okta.com",
    Audience: "api://your-mcp-server",
}, mcpServer)

http.ListenAndServe(":8080", handler)

您的 MCP 服务器现在需要 OAuth 身份验证。

示例

参见 examples/README.md 以获取详细的设置指南，包括 Okta 配置。

SDK	示例	描述
mark3labs	简单	最小设置 - 可复制粘贴
mark3labs	高级	ConfigBuilder，多个工具，日志记录
官方	简单	最小设置 - 可复制粘贴
官方	高级	ConfigBuilder，多个工具，日志记录

支持的提供者

提供者	最适合	设置指南
HMAC	测试，开发	docs/providers/HMAC.md
Okta	企业 SSO	docs/providers/OKTA.md
Google	Google Workspace	docs/providers/GOOGLE.md
Azure AD	Microsoft 365	docs/providers/AZURE.md

文档

入门：

设置指南 - 完整的服务器集成和客户端配置
配置指南 - 所有配置选项
提供者设置 - OAuth 提供者指南

高级：

安全指南 - 生产最佳实践
故障排除 - 常见问题

许可证

MIT 许可证 - 详见 LICENSE