xiantong 文档
MCP 服务器

xiantong MCP 身份验证

为 MCP 服务器连接配置身份验证

MCP 身份验证

配置 MCP 服务器连接的身份验证

MCP 服务器通常需要身份验证才能访问其工具。xiantong 支持多种身份验证方式，以安全地连接受保护的服务器。

身份验证类型#

在 MCP 来源配置中的 authType 字段决定了身份验证的处理方式：

类型使用场景工作原理
oauth互动登录，用户范围访问打开浏览器进行授权
bearer静态令牌、API 密钥提示输入令牌
none无需身份验证无需额外配置

OAuth 身份验证#

对于支持 OAuth 的服务器，请将 authType 设置为 "oauth"：

{
"type": "mcp",
"name": "GitHub",
"tagline": "GitHub 仓库访问",
"icon": "https://github.com/favicon.ico",
"mcp": {
"transport": "http",
"url": "https://api.githubcopilot.com/mcp/",
"authType": "oauth"
}
}

首次使用此来源时：

  1. xiantong 检测到需要 OAuth 身份验证
  2. 会打开浏览器窗口供您授权访问
  3. 授权后，您会被重定向回应用
  4. OAuth 令牌会安全地存储以供将来使用

令牌刷新#

OAuth 令牌在过期时会自动刷新。如果刷新失败，系统会提示您重新认证。

Bearer 令牌身份验证#

对于使用静态 API 密钥或 bearer 令牌的服务器，请将 authType 设置为 "bearer"：

{
"type": "mcp",
"name": "Exa Search",
"tagline": "神经网络搜索",
"icon": "https://exa.ai/favicon.ico",
"mcp": {
"transport": "http",
"url": "https://mcp.exa.ai/mcp",
"authType": "bearer"
}
}

首次使用此来源时，系统会提示您输入 API 密钥：

The "Exa Search" source needs credentials.
Enter bearer token: ****************************

Stored securely

凭据以加密形式存储在 ~/.xiantong/credentials.enc，不会出现在配置文件中。

公开服务器#

对于不需要身份验证的服务器，请将 authType 设置为 "none"：

{
"type": "mcp",
"name": "公共工具",
"tagline": "公众可用工具",
"mcp": {
"transport": "http",
"url": "https://public.example.com/mcp",
"authType": "none"
}
}

无需额外配置。

本地服务器（Stdio）#

使用 stdio 传输的本地服务器通常不需要网络身份验证：

{
"type": "mcp",
"name": "本地 MCP",
"tagline": "MCP 说明",
"mcp": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@package/name", "/path/to/dir"]
}
}

如果本地服务器需要凭据（例如数据库密码），通常会通过环境变量或配置文件读取，而不是通过 MCP 身份验证流程。

凭据管理#

查看已存凭据#

您无法查看实际凭据值，但可以看到存储了哪些信息：

> /debug

会显示凭据作用范围，例如：

Credentials:
source_oauth::workspace-id::github
source_bearer::workspace-id::exa

删除凭据#

要清除特定来源的凭据，请从凭据文件中删除其条目，或在「设置 > 来源」中删除该来源。要清除所有凭据：

rm ~/.xiantong/credentials.enc

凭据作用域#

凭据采用三部分键格式进行分层作用域：

source_{authType}::{workspace_id}::{source_slug}

这意味着：

  • 不同工作区拥有独立凭据
  • 删除来源会移除其凭据
  • 凭据不会在工作区间泄露

示例：多种身份验证类型#

一个工作区中同时使用不同身份验证方式的来源：

[
{
"type": "mcp",
"name": "GitHub",
"tagline": "仓库和问题管理",
"mcp": {
"transport": "http",
"url": "https://api.githubcopilot.com/mcp/",
"authType": "oauth"
}
},
{
"type": "mcp",
"name": "Exa Search",
"tagline": "神经网络网络搜索",
"mcp": {
"transport": "http",
"url": "https://mcp.exa.ai/mcp",
"authType": "bearer"
}
},
{
"type": "mcp",
"name": "公共 API",
"tagline": "公共数据访问",
"mcp": {
"transport": "http",
"url": "https://public-api.example.com/mcp",
"authType": "none"
}
}
]
  • GitHub - OAuth，打开浏览器登录
  • Exa Search - Bearer，提示输入 API 密钥
  • 文件系统 - Stdio，无需网络身份验证
  • 公共 API - none，不需要身份验证

身份验证故障排除#

OAuth 窗口未打开

  • 检查默认浏览器是否正常
  • 确保终端可访问 GUI
  • 防火墙可能阻止本地回调服务器

令牌被服务器拒绝

  • 验证令牌是否具有所需权限/作用域
  • 检查令牌是否已过期
  • 确认服务器 URL 是否正确
  • 确保 authType 与服务器要求匹配

曾经正常但需重新认证

  • 令牌可能已被吊销
  • 凭据文件可能已损坏
  • 在「设置 > 来源」中删除该来源并重新添加以重新认证

认证了错误账号

  • 在「设置 > 来源」中删除该来源
  • 重新添加该来源并使用正确账号进行认证
  • 检查浏览器中登录的是否为正确账号

安全最佳实践#

优先使用 OAuth 而非 bearer 令牌

OAuth 令牌可设置作用域、撤销和轮换。静态令牌更难安全管理。

使用提示的令牌输入

让 xiantong 提示输入令牌，而不是将其存储在配置文件中。

限制令牌作用域

在创建 API 密钥或授权 OAuth 时，仅授予来源所需权限。

定期轮换凭据

对于敏感服务，定期清除并重新输入凭据，以确保其保持最新。

上一页连接 MCP 服务器