使用说明

通用MCP OAuth服务器

一个通用的 模型上下文协议（MCP）服务器 与；带有；用 OAuth 2.1 与……兼容的认证方式 任何OIDC提供者 (PingOne、Okta、Google、Azure AD、Auth0、Keycloak 等更多平台)。

🌟 特点/功能

✅ 通用OIDC支持 - 与任何OAuth 2.1/OIDC提供者兼容
✅ 完整的OAuth 2.1实现 - 支持PKCE的授权服务器
✅ MCP 工具 - 包括echo、sum和stock_price工具（易于扩展）
✅（对号，表示正确、确认或同意） 美观的审批对话框 - 用户友好的同意流程
✅ 表示“正确”或“确认”的意思。 生产就绪 - 全面的日志记录、错误处理和安全保障
✅ 轻松配置 - 基于环境的配置，辅以辅助脚本

🚀 快速入门

1. 克隆并构建

git clone <repository>
cd mcp-oauth-server
make build

2. 配置您的OIDC提供者

选项A：使用配置脚本（推荐）

# Interactive configuration for popular providers
./configure.sh pingone
./configure.sh okta --domain mycompany.okta.com
./configure.sh google
./configure.sh azure --tenant-id your-tenant-id
./configure.sh custom

选项B：手动环境配置

cp .env.example .env
# Edit .env with your OIDC provider settings

3. 启动服务器

make run

4. 配置您的MCP客户端

在 Cursor（或其他 MCP 客户端）中：

{
  "mcp-oauth-server": {
    "transport": "sse",
    "url": "http://localhost:8080/sse"
  }
}

🔧 支持的 OIDC 提供商

PingOne 身份云

./configure.sh pingone

Okta（注：Okta是一个提供身份管理服务的公司名称，直接翻译为中文即“奥克塔”，但通常我们保留其英文原名以指代该公司）

./configure.sh okta --domain mycompany.okta.com

Google Cloud Identity（谷歌云身份）

./configure.sh google

Microsoft Azure AD（Azure Active Directory）

./configure.sh azure --tenant-id your-tenant-id

Auth0（音译可为“奥思托”，但通常直接使用原名）

./configure.sh auth0

Keycloak（可直接作为专有名词，不翻译）

./configure.sh keycloak

自定义 OIDC 提供者

./configure.sh custom

⚙️ 环境变量

变量	描述	示例
`PORT`	服务器端口	`8080`
`SERVER_URL`	服务器基础URL	`http://localhost:8080`
`OIDC_CLIENT_ID`	OAuth 客户端 ID	`your-client-id`
`OIDC_CLIENT_SECRET`	OAuth 客户端密钥	`your-client-secret`
`OIDC_AUTH_URL`	授权端点	`https://provider/auth`
`OIDC_TOKEN_URL`	令牌端点	`https://provider/token`
`OIDC_USER_URL`	用户信息端点（可选）	`https://provider/userinfo`
`OIDC_SCOPES`	OAuth 范围	`openid profile email`

🔒 OAuth 2.1 流程

发现MCP客户端在发现OAuth元数据时 /.well-known/oauth-authorization-server
注册客户端动态注册于 /register
授权用户访问 /authorize 并批准访问权限
认证用户使用您的OIDC（开放身份认证协议）提供商进行身份验证
代币兑换客户端在（某处）用代码换取访问令牌 /token
受保护的访问客户访问MCP工具于 /sse 带有Bearer令牌

🛠️ 可用的MCP工具

回声

回显任何输入信息

{"message": "Hello World"}

总和

将两个数字相加

{"a": 5, "b": 3}

股票价格

返回模拟股票价格数据

{"symbol": "AAPL"}

🔍 端点

终点	用途
`/.well-known/oauth-authorization-server`	OAuth 元数据发现
`/register`	动态客户端注册
`/authorize`	授权 + 审批对话框
`/token`	代币交换
`/callback`	来自OIDC提供者的OAuth回调
`/sse`	受保护的MCP服务器发送事件

🏗️ 建筑学

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  OAuth Server    │    │  OIDC Provider  │
│   (Cursor)      │    │  (This App)      │    │ (Ping/Okta/etc) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ 1. Discover OAuth     │                       │
         │────────────────────► │                       │
         │                       │                       │
         │ 2. Register Client    │                       │  
         │────────────────────► │                       │
         │                       │                       │
         │ 3. Start OAuth Flow   │                       │
         │────────────────────► │                       │
         │                       │                       │
         │ 4. User Approval      │ 5. Redirect to OIDC   │
         │   (Browser Dialog)    │───────────────────────►│
         │                       │                       │
         │                       │ 6. Auth Callback      │
         │                       │◄───────────────────────│
         │                       │                       │
         │ 7. Exchange Token     │                       │
         │────────────────────► │                       │
         │                       │                       │
         │ 8. Access MCP Tools   │                       │
         │────────────────────► │                       │

🚦 测试OAuth流程

启动服务器：
```
./mcp-server
```

访问授权URL （将 client_id 替换为日志中的实际 ID）：

http://localhost:8080/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=mcp:read

批准该请求 在对话中
完成身份验证 与您的OIDC提供者一起
获取授权码 并兑换代币

📝 添加自定义MCP工具

要添加您自己的MCP工具，请编辑 main.go:

// Add tool definition
mcp.AddTool(server, &mcp.Tool{
    Name:        "my_tool",
    Description: "My custom tool",
}, handleMyTool)

// Add handler function  
func handleMyTool(ctx context.Context, request *mcp.CallToolRequest, args MyToolArgs) (*mcp.CallToolResult, MyToolOutput, error) {
    // Your tool logic here
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: "Tool result"},
        },
    }, MyToolOutput{}, nil
}

🔐 安全特性

OAuth 2.1 合规性 - 最新的OAuth安全标准
PKCE 支持 - 用于增强安全性的代码交换证明密钥
携带令牌认证 安全的API访问
CORS 支持 - 正确处理跨域问题
请求记录 - 完整的审计轨迹
令牌过期 - 自动令牌生命周期管理

🚨 安全最佳实践

环境变量：

永远不要将真实凭证提交给版本控制系统
使用 .env 用于本地开发的文件（添加到 .gitignore)
在生产环境中使用安全的密钥管理（如AWS Secrets Manager等）

生产部署：

仅使用HTTPS（生产环境中绝不要使用HTTP）
设置强大且唯一的客户端密钥
实现速率限制
监控OAuth流程中的可疑活动
定期轮换客户端密钥

🤝 贡献（或“参与贡献”）

为仓库创建分支（或“克隆仓库”）
创建你的特性分支（git checkout -b feature/amazing-feature)
提交您的更改（git commit -m 'Add amazing feature')
推送到分支（git push origin feature/amazing-feature）
打开一个拉取请求

📄 许可证

此项目采用MIT许可证授权，请参阅LICENSE文件了解详情。

🙋‍♂️ 支持

问题通过 GitHub Issues 报告错误或请求功能
文档代码中提供了完整的API文档
示例检查 examples/ 使用示例目录

为MCP社区倾心打造