nextmcp客户端身份验证
MCP主机的OAuth客户端库 -“MCP生态系统的Passport.js”
一个主机端助手库，用于与NextMCP服务器进行OAuth身份验证 琐碎的这是一个缺失的部分，它允许Claude Desktop、Cursor、Windsurf等主机集成身份验证，而无需编写一行OAuth代码。
](https://www.npmjs.com/package/nextmcp-client-auth) 
为什么这个图书馆存在
MCP主机不想学习您的身份验证系统。 他们想要一个可以导入的“正常工作”的小助手。
这个库只提供了一个函数调用来处理：
- ✓ 正在读取服务器身份验证元数据
- ✓ PKCE OAuth流
- ✓ 重定向/回调处理
- ✓ 令牌存储
- ✓ 自动令牌刷新
- ✓ 身份验证头注入
把它想象成： “一个函数调用=经过身份验证的MCP连接”
安装
npm install nextmcp-client-auth快速开始
Node.js（带自动环回服务器）
import { connectWithNextMCPAuth } from "nextmcp-client-auth";
const connection = await connectWithNextMCPAuth({
serverUrl: "http://localhost:8000",
onAuthStart(url) {
console.log("Please visit:", url);
// Opens browser automatically in most terminals
},
});
// Use the authenticated connection
const response = await connection.transport.send({
method: "tools/list",
});
console.log("Tools:", response.result);浏览器
import { connectWithNextMCPAuth } from "nextmcp-client-auth";
const connection = await connectWithNextMCPAuth({
serverUrl: "https://api.example.com",
onAuthStart(authUrl) {
// Redirect user to auth URL
window.location.href = authUrl;
},
});
// Make authenticated requests
const response = await connection.transport.send({
method: "tools/list",
});就这样 无需OAuth代码。
特性
🔐 完整的OAuth 2.0支持
- PKCE流程 -对公共客户端（浏览器、移动设备、台式机）安全
- GitHub和谷歌 -与标准OAuth提供程序配合使用
- 自动发现 -从服务器获取身份验证元数据
- 状态验证 -内置CSRF保护
💾 智能令牌管理
- 自动存储 -本地存储（浏览器）或
~/.nextmcp/（Node.js） - 自动刷新 -令牌在到期前透明刷新
- 多服务器 -不同服务器的不同令牌
🚀 开发者体验
- TypeScript -全型安全
- 交叉平台的 -适用于浏览器、Node.js、Electron
- 调试模式 -设置
NEXTMCP_AUTH_DEBUG=1查看详细日志 - 零依赖 -使用内置的Web Crypto API
🎯 生产就绪
- 错误处理 -清除所有故障模式的错误类型
- 超时保护 -身份验证流的可配置超时
- 线程安全 -处理并发令牌刷新
- 内存安全 -日志中没有令牌泄漏
API 参考
connectWithNextMCPAuth(config)
建立经过身份验证的MCP连接的主要功能。
参数：
interface ConnectConfig {
serverUrl: string; // MCP server URL
onAuthStart?: (authUrl: string) => void; // Called when auth flow starts
redirectUri?: string; // Custom redirect (optional)
tokenStore?: TokenStore; // Custom token storage (optional)
debug?: boolean; // Enable debug logs
loopbackPort?: number; // Port for callback server (Node.js)
}退货：
interface AuthenticatedConnection {
transport: MCPTransport; // Use this to send MCP requests
tokens: OAuthTokens; // Current access/refresh tokens
metadata: AuthMetadata; // Server's auth requirements
disconnect(): Promise; // Clean up and remove tokens
}例子：
const connection = await connectWithNextMCPAuth({
serverUrl: "http://localhost:8000",
debug: true,
onAuthStart(url) {
console.log("Auth URL:", url);
},
});
// Make authenticated requests
await connection.transport.send({ method: "tools/list" });
// Disconnect when done
await connection.disconnect();令牌存储
默认情况下，令牌存储在：
- 浏览器：
localStorage - Node.js：
~/.nextmcp/sessions/{host}.json
您可以提供自定义商店：
import { TokenStore, OAuthTokens } from "nextmcp-client-auth";
class CustomTokenStore implements TokenStore {
async saveTokens(serverUrl: string, tokens: OAuthTokens): Promise {
// Your storage logic
}
async getTokens(serverUrl: string): Promise {
// Your retrieval logic
}
async deleteTokens(serverUrl: string): Promise {
// Your deletion logic
}
async clear(): Promise {
// Clear all tokens
}
}
const connection = await connectWithNextMCPAuth({
serverUrl: "http://localhost:8000",
tokenStore: new CustomTokenStore(),
});错误处理
库抛出特定的错误类型：
import {
OAuthError,
PKCEError,
TokenRefreshError,
CallbackTimeoutError,
AuthMetadataError,
} from "nextmcp-client-auth";
try {
const connection = await connectWithNextMCPAuth({
serverUrl: "http://localhost:8000",
});
} catch (error) {
if (error instanceof OAuthError) {
console.error("OAuth failed:", error.message, error.code);
} else if (error instanceof CallbackTimeoutError) {
console.error("User didn't complete auth in time");
} else if (error instanceof AuthMetadataError) {
console.error("Server doesn't support OAuth");
}
}高级用法
自定义重定向URI
const connection = await connectWithNextMCPAuth({
serverUrl: "http://localhost:8000",
redirectUri: "http://localhost:3000/oauth/callback",
onAuthStart(authUrl) {
// Your app should handle the callback at /oauth/callback
window.location.href = authUrl;
},
});手动令牌刷新
import { refreshAccessToken } from "nextmcp-client-auth";
const newTokens = await refreshAccessToken({
provider: metadata.providers[0],
refreshToken: currentTokens.refresh_token,
});PKCE挑战生成
import { generateVerifier, generatePKCE } from "nextmcp-client-auth";
const verifier = generateVerifier();
const pkce = await generatePKCE(verifier);
console.log("Challenge:", pkce.challenge);
console.log("Verifier:", pkce.verifier);运作原理
┌─────────────┐
│ Host App │
│ (Cursor,etc)│
└──────┬──────┘
│
│ 1. connectWithNextMCPAuth()
▼
┌─────────────────────────────────────────────────┐
│ nextmcp-client-auth Library │
│ │
│ 2. Fetch /.well-known/mcp-auth │
│ 3. Generate PKCE challenge │
│ 4. Open auth URL │
│ 5. Listen for callback │
│ 6. Exchange code → tokens │
│ 7. Store tokens │
│ 8. Return authenticated transport │
└──────┬──────────────────────────────────────────┘
│
│ 9. transport.send() + auto refresh
▼
┌─────────────┐
│ NextMCP │
│ Server │
└─────────────┘示例
请参阅 examples/ 完整示例目录：
- 带环回的Node.js -
- 自定义重定向URI -
- 浏览器 -
examples/browser/index.html
需求
- Node.js 18+或具有Web Crypto API的现代浏览器
- 配置了OAuth身份验证的NextMCP服务器
发展
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Run examples
cd examples/node
npm install
npm run simple常见问题解答
Q： 我需要了解OAuth吗？
A. 不，这就是这个图书馆的意义所在。只需拨打电话 connectWithNextMCPAuth().
Q： 这适用于所有OAuth提供商吗？
A. 是的，NextMCP服务器支持的任何OAuth 2.0提供程序（GitHub、Google等）
Q： 安全怎么办？
A. 该库使用PKCE（代码交换证明密钥），这是公共客户端的推荐流程。令牌被安全地存储（建议在浏览器生产环境中使用httpOnly Cookie）。
Q： 我可以在Electron中使用这个吗？
A. 对！它在主进程和渲染进程中都有效。
Q： 我该如何处理注销？
A. 呼叫 await connection.disconnect() 删除令牌并关闭连接。
Q： 这支持DPoP吗？
A. 还没有，但它在路线图上。
贡献
欢迎投稿！请看 贡献.md.
许可证
麻省理工学院© NextMCP 贡献者
相关项目
______________________________________________________________________
由以下材料制成❤️ 对于MCP生态系统